Skip to content
Blueprint AI

Terminal Mode

The panel can swap its chat view for a fully-featured terminal at any time. The terminal is a real xterm.js emulator wired to a pseudo-TTY (ConPTY on Windows, POSIX PTY on macOS/Linux), so it behaves exactly like a native shell — including curses-style apps, interactive prompts, and color escapes.

Switching modes

Section titled “Switching modes”

Two paths:

  • Click the slash button [/] in the ActionRow and choose Switch to terminal
  • Type /terminal in the input field

To go back:

  • Type /chat in the terminal
  • Or use the slash menu’s Switch to chat

Switching mode preserves the underlying session — the JSONL keeps growing for chat events, and the terminal’s scrollback is held in memory until you close the tab.

What runs

Section titled “What runs”
OSShell launched
Windowscmd.exe via ConPTY
macOS$SHELL (fallback /bin/sh)
Linux$SHELL (fallback /bin/sh)

Working directory:

  • The terminal starts in AgentWorkingDirectory (see Project Settings)
  • If that’s blank, it starts in the project root (the directory containing the .uproject)

Environment variables are inherited from the editor process — including any PATH extensions, ANTHROPIC_API_KEY, etc. that the editor sees.

Terminal features

Section titled “Terminal features”

The xterm.js emulator supports:

  • ANSI / VT escapes — 256-color, true-color, bold, italic, underline, strike
  • Scrollback — 10,000 lines by default
  • Mouse selection — click-drag to select, right-click to copy
  • Clipboard — Ctrl+Shift+C / Ctrl+Shift+V (Windows / Linux), Cmd+C / Cmd+V (macOS)
  • Resize — the shell receives SIGWINCH (POSIX) / ResizePseudoConsole (Windows) when the panel resizes, so top, vim, etc. redraw correctly
  • Native command history — arrow up / down go through the shell’s history, not the chat input

Typical uses

Section titled “Typical uses”
Terminal window
# Run Blueprint AI CLI directly
python Plugins/BlueprintAI/Scripts/cli.py apply spec.json
python Plugins/BlueprintAI/Scripts/cli.py schema --domain blueprint


# Run a different agent without sign-in
claude


# Watch a build
cmake --build Build --config Development


# Inspect engine logs while PIE is running
Get-Content Saved/Logs/*.log -Wait


# Run any helper script the project already has
python Scripts/deploy/check_secrets.py

The terminal can be a one-off — open it, run a command, close back to chat.

Command Line agent

Section titled “Command Line agent”

If the active agent in the ModeSelector is set to Command Line, the panel skips chat entirely and stays in terminal mode permanently. The TopBar still shows the session name and history drawer, but the InputBar collapses to just the slash button.

This is useful when:

  • You want to use the panel as a generic editor-docked terminal (no AI involvement)
  • You’re using a CLI-only AI tool that doesn’t expose a programmatic API
  • You just want a shell next to the viewport

Session detection from the terminal

Section titled “Session detection from the terminal”

While the terminal is running, the panel watches the Claude project directory for new JSONL files. If you run:

Terminal window
claude

…and have a conversation inside the terminal, the resulting JSONL file shows up in the SessionDrawer automatically when the run ends. You can switch the panel back to chat mode and the session is right there.

Use the terminal for CLI flags or debug commands the panel doesn’t expose directly.

Theming

Section titled “Theming”

Terminal colors and font are driven by the same styling layer as the rest of the panel:

Resources/Theme/Terminal/terminal.json
{
    "--terminal-bg": "#151515",
    "--font-mono-family": "\"Cascadia Code\", \"Consolas\", monospace",
    "--font-size-terminal": "13px"
}

Edit the JSON, save, and the running terminal redraws — no editor restart needed.

Copy / paste behavior

Section titled “Copy / paste behavior”
  • Copy is bound to the OS shortcut and uses the selected range, not the whole scrollback
  • Paste sends the clipboard contents to the shell — newlines run as Enter presses, so multi-line paste runs as multiple commands
  • Bracketed paste mode is on by default, so modern shells (PowerShell, bash, zsh, fish) recognize a paste as a single chunk and only run after you press Enter

Limitations

Section titled “Limitations”
  • No tmux-style multiplexing — the panel runs one shell per terminal tab. Spawn a second Blueprint AI panel tab for a second shell.
  • No native search bar — Ctrl+F search is on the roadmap. For now, scroll up with the mouse wheel.
  • GPU rendering only — xterm.js uses the WebGL renderer when available; on machines without GPU compositing the canvas fallback is slower but functional.