Terminal User Interface (TUI)¶

SuperQode includes a rich Terminal User Interface (TUI) for interactive coding-agent sessions.

Features¶

• Rich Output: Colored, formatted terminal output
• Progress Tracking: Real-time progress indicators
• Compact Tool Activity: Search, read, edit, and shell tools are summarized by default
• Quiet Streaming Logs: Agent thinking and successful tool output are hidden by default
• Provider Selection: ACP, BYOK, and Local provider pickers with setup hints
• Model Labels: Tool support, vision, reasoning, coding, context, and price labels where available
• Local DS4 Support: DS4 appears in the local provider picker when configured
• Interactive Prompts: User input with completion
• File Browser: Navigate project files
• Agent Switcher: Switch between agents
• Harness Hub: Browse, inspect, use, and build harnesses with mouse or keyboard
• Focused Results: Important outcomes open above the transcript and remain in Activity
• Command Palette: Quick actions
• Status Bar: Session status at a glance
• Optional Vim Navigation: Modal keyboard control for the transcript, panes, searches, and pickers

Launching the TUI¶

# Start TUI mode
superqode

# Start with a harness spec
superqode --harness harness.yaml

Folded pastes and shell-output staging¶

Pastes of at least 20 lines or 2,000 characters become compact [Block …] markers at the current cursor position. Click a block chip to inspect it, or use :blocks through the command palette. Preview pages contain at most 32,768 characters; the full original text, including whitespace and line endings, is expanded in place when you send a normal message. Remove a block with its × chip or the preview's Remove button. Back and Escape leave the draft intact. Small pastes and command-line pastes stay literal.

After a local shell command (> or !) completes, click Preview and stage for next message, or open :output from the command palette. Select text or edit the current preview page, then choose Stage excerpt. This adds that excerpt, command and exit code to the composer; it does not send it. Type your question and press Enter when ready. Opening the palette lets you inspect output without replacing your existing draft. Only the latest completed local shell output is available through this action.

Folded text is limited to 100 blocks, 2,097,152 characters per block, and 4,194,304 characters per expanded message. Oversized pastes are rejected with a visible message. The shell-output handle retains at most 2,097,152 characters and labels any truncation. Each staged excerpt remains bounded by the preview page. Large pastes avoid rendering their full text, but sending their full content still increases model input size. Submitted message display is bounded to 8,000 characters and 80 lines while session history retains the complete message.

Unsent folded payloads are included in the existing private workspace draft recovery file. Recovery is bounded to a 32 MiB serialized draft. Image bytes remain outside that file. Deleting a marker supports normal editor undo until a new block is staged; the explicit Remove action discards its payload.

Runs, approvals and delivery¶

The persistent strip below the status bar shows Runs, Approvals, Delivery, and Queue. Open the overview with Ctrl+O, or use:

The overview preserves your prompt draft and cursor. Use arrow keys to select, Enter to inspect, Tab to reach actions, and Escape to return. Escape from the overview leaves pending requests pending. The layout stacks the list above the details in narrower terminals. SuperQode's current theme and diamond branding are retained.

Tool requests show their owner, arguments, reason and available invocation identity. Approve once applies to the selected request; a changed request requires a fresh decision. Contextual approvals bind the invocation, argument digest and policy revision, and never override DENY. If the original policy scope cannot be restored, resumption stops rather than dropping that scope. The inbox exposes requests reported by the active runtime and child manager; vendor prompts outside those interfaces remain in their vendor UI.

For a WorkOrder, Open enters its Delivery inspector. Inspect the full current candidate and enter a review reason before approving. Approval and merge are separate actions. Merge requires an accepted candidate and applicable checks; merge and rollback each require a second Execute click to confirm. Existing backend checks still validate the repository state before changing it. Completed task reviews provide files and recorded checks; they are not accepted WorkOrder candidates. Missing checks and usage remain explicitly unrecorded.

Observed state refreshes every two seconds while the overview is open. The persistent strip refreshes live counts every second and WorkOrder counts every three seconds. WorkOrder inspection reads up to the latest 100 orders in the selected store, then filters to the current project. It does not create a store when none exists.

WorkOrder and context inspectors¶

Open :work view ID for task dependencies, evidence, recovery and candidate review. Actions execute while the view remains open, and an explicit Interrupt control stops its own worker process. See the coding demo for interruption, restart, checks and human approval.

Use :context evidence after a native Core or hosted PiPy context decision. The separate screen shows mode, selector, character counts, cache reuse and actual proposed excerpts. Open original and Next page retrieve bounded text with current permission checks. Shadow proposals remain distinct from applied excerpts. This command does not enable recovery or context enforcement.

Common TUI Workflow¶

Use this flow for a normal coding session:

1. Launch from the project root.
2. For local coding, run :local init to generate superqode.local.yaml and a readiness report.
3. Connect a provider, ACP agent, or local model with :connect.
4. Load a harness with :harness superqode.local.yaml when you want portable policy.
5. Type a focused prompt and press Enter.
6. Approve or reject pending tool calls.
7. Ask for a summary of changed files and tests.

Example:

:connect
:local init
:harness superqode.local.yaml
:status
Summarize this repository and suggest the smallest safe improvement.
Find one low-risk cleanup, make the smallest fix, and run the narrowest useful test.
:approve
Summarize what changed.

To talk to a remote A2A agent: :connect → Reach a remote agent with protocols → Agent2Agent (A2A), or :connect a2a. A bare :connect a2a <url> or :a2a connect <url> opens the same screen with the origin filled in. Leave the credential empty for an open card. The purple chips under the credential are OAuth on, Headers, mTLS, and Inspect. Click Headers or mTLS to open those fields on the same screen. Click Inspect for the wire log and Check. After Connect, type in the message field and Send. That is the chat with the remote agent. Later Sends keep the same contextId thread. Skill examples fill the box. Use saves the connection and stays on the screen; Back returns. y copies the last reply, r resends, Esc stops a wait. The main prompt stays your ACP or local agent; it does not become the A2A agent. Later: :a2a call <name> "your message".

TUI Layout¶

┌─────────────────────────────────────────────────────────────────┐
│ SuperQode - Session: session-20260108-143052                  ×│
├─────────────────────────────────────────────────────────────────┤
│ Sidebar        │ Main Content Area                              │
│                │                                                 │
│ ◉ Files        │ Agent Output                                   │
│ ◯ Agents       │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│ ◯ Findings     │                                                 │
│ ◯ Artifacts    │ Analyzing src/api/users.py...                  │
│                │                                                 │
│ Files          │ Found potential SQL injection at line 42       │
│ ├── src/       │                                                 │
│ │   ├── api/   │ ```python                                      │
│ │   └── utils/ │ query = f"SELECT * FROM users WHERE id = {id}" │
│ └── tests/     │ ```                                            │
│                │                                                 │
├─────────────────────────────────────────────────────────────────┤
│ ⌘K Command Palette │ Mode: Quick Scan │ Findings: 2 │ 00:45    │
└─────────────────────────────────────────────────────────────────┘

State Change Notifications¶

Consequential selections use four coordinated surfaces:

1. A temporary notification identifies the completed action and active value.
2. The top status bar retains the active runtime, agent, model, harness, and mode.
3. Focused result screens show details and recovery actions above the transcript.
4. :activity keeps session outcomes and their primary actions available for review.

The conversation transcript still stores a compact durable receipt, but it is not the only place a user must look for an important result.

This applies to provider connections, ACP agents, model selection, local model readiness, harness changes, session resume, and interaction mode changes. Connection errors remain visible longer and include a recovery command in the transcript.

For example, selecting an OpenCode model produces a Model ready notification, updates the top bar to show OpenCode, the selected model, and ACP, and records the same selection in the transcript. The notification adapts to narrow terminals and does not replace the persistent status bar.

Progress messages remain in the activity indicator instead of creating repeated notifications. Informational diagnostic output remains in the transcript. This keeps notifications limited to state changes that require user awareness.

Key Bindings¶

Quick Actions¶

Access via Command Palette (Ctrl+K) or Command Mode (:) in TUI:

• :connect - Connect to provider/agent
• :free - Keep the current harness and choose a free hosted or account-backed model route
• :home - Return to the SuperQode home screen from any picker or workflow
• :connect kimi-code - Connect Moonshot AI's first-party Kimi Code ACP server
• :connect qwen-code - Connect QwenLM's first-party Qwen Code ACP server
• :connect fx - Connect Vercel Labs' experimental fx agent over ACP
• :connect fx-key - Connect fx with AI_GATEWAY_API_KEY (Open harnesses)
• :harness switch fx - Connect fx from the unified picker
• :connect local - Open the local provider picker
• :connect byok - Open the BYOK provider picker
• :local setup <name> - TUI-first guide for model download, serving, context, harness, and smoke
• :local init - Generate superqode.local.yaml and run local readiness checks
• :local airplane prepare - Create a strict no-network local harness
• :local airplane smoke - Verify offline harness and local search readiness
• :local smoke - Run non-destructive local coding readiness checks
• :local search <name> - Find a model + how to get it on every engine (:hub model <name> is a migration alias)
• :hub - Open the full-screen Harness Hub
• :hub ready - Open the Hub filtered to harnesses ready on this machine
• :hub setup - Open the Hub filtered to entries that need setup
• :hub custom - Open the Hub filtered to repository-owned harnesses
• :activity - Revisit important results, state changes, and their next actions
• :steer <message> - Send a correction to the current run when its agent supports live steering
• :steer - Show how to steer a supported running agent
• :optimize - Open Jev Tool Routing setup and status
• :local labs - Browse trusted models.dev Labs recommendations
• :local warm <engine> - Warm a local model and show first-token latency
• :chat - Raw direct-to-model chat: no repo/tools, shows TTFT + tok/s (off by default)
• :harness - Open all coding agents, HarnessSpecs, presets, and project harnesses
• :gauge - Emit and check Agent Quality Records for a release decision
• :harness switch - Open the same Harness Switcher
• :harness switch codex - Connect a vendor coding agent from the same command family
• :harness switch kimi-code - Connect Kimi Code from the unified picker
• :harness switch qwen-code - Connect Qwen Code from the unified picker
• :harness switch acp:qwen - Connect an ACP agent with bounded context replay
• :harness switch acp:all - Browse the complete official ACP registry
• :harness all - Open the complete picker explicitly
• :harness <path> - Load a HarnessSpec
• :harness status - Show the active harness
• :harness templates - List built-in harness templates
• :harness off - Disable the active harness
• :explore - Browse capabilities with their local readiness state
• :tour - Show the progressive path from first connection to evaluation
• :eval - Explain or run repository harness evaluation
• :tau - Select, configure, inspect, and retry the optional Tau harness
• :pipy (alias :pi) - Session commands for the PiPy harness: tree, fork, compact, export, skills and prompt templates
• :rlm - Native RLM sessions, optional Python+Bash, history, shared budgets, durable jobs and recursive agents. Open :rlm settings or see RLM profiles for configuration and recovery.
• :runtime list - Show available runtime backends
• :runtime <name> - Switch runtime where available
• :approve - Approve a pending tool call
• :reject - Reject a pending tool call
• :log - Show current output verbosity
• :log minimal - Show status-only tool activity
• :log normal - Show compact tool summaries
• :log verbose - Show full tool outputs and changed file names
• :view <file> - View file content
• :rewind - Open the rewind overlay (or :rewind <n> to jump directly)
• :tree - Show saved session branches and forks
• :theme - Open the theme picker (or :theme <name> to apply one)
• :settings or :appearance - Open appearance settings: theme mode, light/dark pair, spacing, motion and icons
• :trial - Open the guided first task
• :feedback - Review and export a redacted local diagnostic bundle
• :export html|markdown|json - Export the current transcript
• :share - Create, import, list, or revoke portable session artifacts
• :trust - Show or change local trust for this project
• :plugins - List, validate, install, enable, or disable plugins
• :codex - Connect to and manage the Codex SDK runtime
• :claude - Connect to and manage the Claude Agent SDK runtime
• :antigravity - Show Antigravity CLI handoff, status, and migration help
• :muse (alias :muse-code) - Show Muse Code readiness; :muse login runs Meta's own browser sign-in (see Meta Muse Code)
• :fx - Show fx readiness; :fx login runs Vercel's own fx login; :fx connect attaches over ACP (see fx)
• :grok - Grok Build (xAI's agent) on your subscription; :grok api runs SuperQode's harness on the same plan; also status/login/models
• :plan <task> - Ask for a plan only, without native tool execution
• :plan approve - Execute the last planned request with tools enabled
• :plan edit [task] - Edit the pending planned request before execution
• :plan reject - Clear the pending planned request
• :compare <models> - Re-run your last message across several models side by side
• :context - Show, pin, or re-detect the model's loaded context window
• :thinking - Cycle thinking-log verbosity (also Ctrl+T)
• :queue clear - Clear queued type-ahead messages
• :queue send - Send the next queued message when idle
• :workspace add|remove|list - Register extra repositories for cross-repo search
• :memory - Search, remember, and inspect project memory providers
• :sandbox - Show or set the local command sandbox mode
• :help - Show all available commands
• :keys - Show the keyboard reference (also Ctrl+F to search, Ctrl+P to reword your last message)
• :search <text> - Search the transcript; run :search again for the next match (also Ctrl+F)
• :edit - Load your last message back into the prompt to reword it (also Ctrl+P)

Tool and file-change output is collapsed by default so normal coding sessions stay readable. Agent thinking/session notes are also hidden by default. Use Ctrl+T when you want to see thinking logs, and use :log verbose before a task when you want full successful tool output, raw ACP agent session logs, and file names in the session report.

Command Family Index¶

The command palette is the authoritative runtime inventory because optional extensions and connected ACP agents can add commands. The following table maps the built-in command roots. Enter a root without arguments to open its picker, show status, or display its local help where supported.

Use :mode chat|build|plan to choose how prompts run. Use :approval to inspect the tool approval policy, or :approval ask|auto|deny to change it. The header shows ASK, AUTO or DENY separately from the interaction mode. :approvals opens pending requests. External harnesses decide which approval requests they send; their execution policy and sandbox restrictions still apply.

Discovering What Is Available¶

Two commands exist so the product does not have to be explained before it can be used.

:explore opens a browser of every capability category, including agents, providers, local engines, harnesses, runtimes, memory, tools, sandboxes, observability, evaluation, optimization, remote execution, and delivery. Each row is a live probe of this machine rather than a description, so it reports what is actually installed, configured, or one command away. Use the arrow keys to move, Enter to expand a category, and the right arrow to run its command. Only one category stays expanded, keeping the inventory usable in a short terminal. :explore memory jumps straight to one category, and :capabilities is an alias for the same screen.

:tour shows the ownership ladder, from using an agent someone else built to owning and measuring a harness of your own. Each rung is ticked off when the underlying milestone actually happens, so the screen reports progress rather than replaying an introduction. :tour next runs the current step, and :tour 5 opens one rung without running it.

After a connection is active, :home switches from the full onboarding view to a compact operational summary: repository, harness, agent or model, policy, and one recommended next action. The complete product surface remains one command away through :explore.

Progress is stored per user in ~/.superqode/progress.json. Set SUPERQODE_PROGRESS_DIR to relocate it, which is useful for automation that should not write to a developer's own state. Deleting the file only means seeing an already-dismissed hint a second time.

The CLI-backed families use the same subcommand names as their documented CLI counterparts. For example, :work status, :harness doctor, :providers smoke, and :sessions graph correspond to sq work status, sq harness doctor, sq providers smoke, and sq sessions graph. Runtime-specific command families are documented in Agent Runtimes. Public CLI subcommands are indexed in the CLI Reference.

Plan Mode, TODOs, and Questions¶

Plan mode gives you a review step before native tools run:

:plan fix the failing tests     # planning only
:plan                           # show current plan
:plan approve                   # run the planned request
:plan edit adjust the request   # replace the pending request
:plan reject                    # discard it
:plan on                        # make future prompts planning-only
:plan off                       # return to normal execution

For BYOK/local SuperQode AgentLoop sessions, plan mode is enforced in two layers: tool schemas are not sent to the model, and any unexpected tool call is denied before execution. For vendor-owned SDK runtimes, SuperQode also denies approval prompts during plan mode, but tools that a vendor runtime can run without asking still depend on that runtime's own plan/no-tool controls.

Native todo_write updates and runtime-native plan events feed the same pinned plan panel and :plan view. Codex SDK turn/plan/updated / todo_list events and Claude Agent SDK TodoWrite tool calls are normalized into SuperQode's shared plan_update event. This keeps SuperQode's own tools and vendor agent runtimes aligned in one planning surface.

Antigravity CLI is currently an external interactive agy handoff in SuperQode, not a structured runtime. It will use the same plan_update path when Google exposes a documented ACP/headless event stream.

When an agent needs clarification it can use the ask_user tool. The TUI renders an inline question card above the prompt, and your next submitted message answers that question instead of starting a new task. Choice questions accept the option number or option text; empty input uses the default when one is provided.

Typing While The Agent Works¶

You do not have to wait for a run to finish before typing.

The prompt stays editable during a run. Pressing Enter adds your message to the type-ahead queue for the next turn. The queue renders under the prompt with a live preview and sends automatically when the agent is free. :queue clear empties it.

Queued delivery keeps an unfinished draft intact. Cancelling a run pauses queued delivery; :queue send sends the next queued message when the agent is idle.

Use :steer <message> to correct the current run when the connected agent supports live steering. Unsupported steering retains your text as a draft. Approval and agent-question input is handled separately, with your working draft restored after the decision.

Prompt Input¶

The top prompt is a wrapped multiline input. Long prompts expand the prompt box up to a fixed height and then scroll internally, so pasted tasks remain visible instead of being cut off. Press Enter to submit the current prompt.

File mentions (@)¶

Type @ in the prompt to open a fuzzy file picker. As you keep typing it filters the workspace; selecting a directory (ending in /) drills into it. Accepted mentions become @path/to/file references, and the referenced file contents are included with your message when you submit.

> Explain the bug in @src/superqode/agent/loop.py
> Compare @tests/test_tui_smoke.py with @src/superqode/app_main.py

Prompt history and code copying¶

Use Ctrl+K for the searchable command palette. Ctrl+Shift+R opens prompt history search; :history search, :history-search, :search-history, and :prompt-history open the same overlay. Type a fuzzy query, use arrows to navigate, and press Enter to load a complete prompt for editing. Escape keeps your current draft. Ctrl+Y or :yank copies the final fenced code block from the last response.

Images and OS dictation¶

Attach screenshots, diagrams, and mockups with :paste /path/to/image.png, :image /path/to/image.png, or :attach /path/to/image.png. Pasting an image file path also stages it. For a clipboard image, run :paste; clipboard capture runs in the background and depends on your operating system's clipboard support. An inline mention such as Review @screenshot.png also sends image content. Terminal-dropped absolute paths, quoted paths, shell-escaped spaces, and local file:// URLs are recognized as attachments. A path submitted on its own stages the image; add your question and press Enter to send it. Text submitted alongside an image path sends both the text and image. Missing files produce an error and retain the draft rather than being dispatched as slash commands.

The composer shows staged attachments with a clickable ×. You can also use :attach remove <number> or :attach clear. Attaching and removing images keeps your draft. Up to four PNG, JPEG, GIF, or WebP images can accompany a prompt, with a 4 MB limit per image. Image bytes are sent as image content, never read as text files.

Image input is supported in direct Chat with a vision-capable model, the built-in coding loop, ACP agents that advertise image input, and PiPy. Other harness and runtime routes report that composer image input is unavailable. Rejected requests restore the images and draft so you can change connections and retry. Saved coding sessions retain prompt text; reattach images when resuming a session.

Run :voice (alias :dictate), or choose OS Dictation in the command palette, to focus the composer and show guidance. On macOS, enable Dictation in System Settings → Keyboard and use your configured shortcut. On Windows, use Win+H. On Linux, use a desktop dictation tool that inserts text into your terminal. Dictated text stays editable: review it and press Enter to send. Use :voice off to hide the guidance. Terminal support varies; if dictation cannot insert text directly, dictate into a supported text editor and paste it into the composer. SuperQode does not record audio or start the operating system's microphone.

See Apple's Dictation guide and Microsoft's voice typing guide.

Streaming markdown¶

Assistant responses render as live, formatted markdown while they stream - paragraphs, headings, lists, and code blocks appear as they complete. Partially written paragraphs and unterminated code fences are held back so you never see broken formatting mid-stream.

Rewind & Transcript Overlay¶

Press Ctrl+R (or double-tap Escape with an empty prompt) to open the rewind overlay. It shows the full conversation transcript and a list of your earlier messages. Selecting one rewinds the conversation to that point: the agent's stored history is truncated so it forgets everything after that message, and the message is loaded back into the prompt for you to edit and resend.

:rewind          # open the overlay
:rewind 3        # rewind directly to your 3rd message
:rewind last     # rewind to your most recent message

Use this to retry a turn with a better prompt without starting a new session.

Themes¶

SuperQode supports complete light, dark, terminal-derived, and custom JSON palettes. Open the searchable picker with :theme, or apply a name directly:

:theme            # preview the real workspace; F4 exposes it, Esc restores it
:theme tokyonight
:theme dracula
:theme light
:theme system
:theme auto
:theme next       # switch to the next favorite
:theme previous   # restore the previous selection
:theme customize  # edit a copy, check readability and save/export JSON
:settings         # appearance, light/dark pairing, spacing, motion and icons

Highlighting previews immediately, including retained conversation output. Enter applies and saves to ~/.superqode/config.json; Escape restores the original appearance. Drafts and queued tasks remain in place. The gallery includes explicit Light/Dark, Favorites and Recent filters; Ctrl+S toggles a favorite.

Some terminals intercept function keys or Ctrl+S: macOS Terminal sends F3/F4 to the system unless Fn is held, tmux and screen can drop function keys with an old TERM, and Ctrl+S is flow control (XOFF) outside raw mode. In the gallery, move focus to the list (Tab or the arrow keys) and use e to customize, w to view the workspace and f to toggle a favorite. In the customizer and appearance settings, w views the workspace when a text field is not focused. Use superqode --theme light for a temporary startup choice. See Themes for custom files, Pi palette imports, and live editing.

Open :trial for connection validation, project context, an explicit first task and recorded result review. Use :feedback to inspect a redacted diagnostic snapshot and export it locally after review. See the first-session guide and developer trial guide.

Accessibility¶

:theme high-contrast maximizes legibility for low vision or a bright room. All effective body/status text palettes meet a 4.5:1 contrast target on their supported surfaces. The high-contrast preset raises primary, muted, and dim text to at least 7:1 on its black canvas. Success, warning, and error retain distinct labels and colors.

Set NO_COLOR to remove colour entirely:

NO_COLOR=1 superqode

SuperQode never uses colour as the only carrier of meaning. Status words such as ready and needs setup are spelled out, pickers mark the highlighted row with ▶ and a number, and diffs prefix lines with + and -, so a monochrome session loses no information.

Export¶

Save the current conversation to HTML, Markdown, or JSON:

:export                         # writes .superqode/exports/transcript-<timestamp>.html
:export html ~/notes/session    # writes ~/notes/session.html
:export markdown ~/notes/session.md
:export json ~/notes/session.json

HTML keeps styled markdown. Markdown is good for issue trackers and pull request notes. JSON is structured for automation and handoff.

Sessions And Sharing¶

Use session commands when you want to inspect, branch, or hand off work:

:tree
:session
:session rename <name>
:sessions rename <id-or-name> <title>
:harness switch <name>
:harness switch <name> --fork
:sessions switch
:sessions switch <id-or-name>
:sessions switch latest
:resume <id-or-name>
:resume latest
:fork <new-id>
:share
:share create [session] [path]
:share export [session] [path] [--json|--markdown]
:share import <artifact.superqode-share.json> [new-session-id]
:share list
:share revoke <artifact>

Open the Harness Switcher with either command:

:harness
:harness switch

The default view is the complete inventory and always starts at item 1. Its sections are ordered as SuperQode-managed harnesses, vendor coding agents, ACP agents, optional integrations, model and task presets, and project harnesses. The ACP section avoids duplicate vendor routes and ends with Browse All ACP Agents for the complete registry. Every row reports live readiness, continuity, and route or runtime information. The selected row includes its description and any setup warning.

Selecting a missing maintained Python integration opens an in-TUI confirmation. Press Enter to install its SuperQode extra into the exact Python environment running the TUI and continue the switch without restarting. The prompt also shows the equivalent > shell-executor command. External CLI and local runtime installation are left as guided manual steps.

Vim mode also supports j and k for navigation. Harnesses that report fresh session require confirmation because the external runtime cannot guarantee native thread resumption. SuperQode still preserves the session record and transition lineage.

:harness switch <name> accepts HarnessSpec names, vendor agents, and explicit ACP names. A HarnessSpec switch keeps the current session ID and uses its declared continuity policy. A vendor name such as codex dispatches through that agent's native runtime connector. An ACP name such as acp:qwen starts the agent's ACP session and queues a bounded replay of recent user and agent messages for its first prompt. SuperQode reports the replay count in the switch receipt. Agent-native session resumption remains separate. Add --fork only for HarnessSpec entries. :sessions and :sessions switch open the searchable Session Browser (title, harness, model, age, availability, preview). Resume replays the chat transcript into the conversation log and updates the status bar with harness, model, and session label. Use :sessions rename <id-or-name> <title> or rename inside the browser, or :resume latest / Continue last session to jump to the most recent session. Selecting one restores its harness, BYOK provider and model, working directory, and the same transcript. Missing credentials or harnesses fail clearly instead of opening a blank session. BYOK and PiPy harness sessions remain listed after disconnect.

Share artifacts are local/offline superqode-share-v1 JSON files. They are intended for moving a session between machines or teammates without requiring a hosted service.

Project Trust And Plugins¶

Project trust protects local executable surfaces such as project plugins and MCP configuration. Trust is stored outside the repository in ~/.superqode/trust.json.

:trust
:trust status
:trust doctor
:trust yes
:trust no
:plugins
:plugins doctor
:plugins add <local-plugin-dir|plugin.json>
:plugins enable <id>
:plugins disable <id>

:plugins add and :plugins enable require :trust yes.

Runtime-Specific Commands¶

Codex SDK:

:codex
:codex status
:codex models
:codex model
:codex effort
:codex sandbox
:codex review
:codex compact
:codex thread
:codex sessions
:codex resume <thread-id>
:codex fork <thread-id>
:codex rename <name>
:codex archive <thread-id>
:codex account
:codex logout

Claude Agent SDK:

:claude
:claude status
:claude model
:claude permission
:claude sessions
:claude resume <session-id>
:claude rename <name>
:claude tag <tag>
:claude commands
:claude command <name> [args]
:claude review

Antigravity CLI handoff:

:antigravity
:antigravity status
:antigravity migrate
:agy status

fx (Vercel login over ACP):

:connect fx                  # Subscriptions: fx acp after fx login
:connect fx-key              # Open: AI_GATEWAY_API_KEY injected into fx acp
:fx                          # readiness: install, Vercel login, leftover key
:fx connect                  # same as :connect fx
:fx login                    # consent-gated `fx login` (Vercel OAuth)
:fx status                   # same readiness screen
:harness switch fx

:connect fx runs fx, Vercel Labs' experimental coding agent, over ACP. Models are billed as the signed-in team's AI Gateway credits. A leftover AI_GATEWAY_API_KEY is ignored on that route; spend it with :connect fx-key.

Grok subscription (official Grok CLI login):

:connect grok                 # Grok Build, xAI's own agent (ACP), default
:grok                         # same as :connect grok
:grok connect [model]         # ...with an optional model hint
:grok api [model]             # SuperQode's harness on the subscription (opt-in)
:grok api off                 # remove the imported session token
:grok model                   # pick a subscription model for the harness path
:grok models                  # list the signed-in CLI's model catalog
:grok status
:grok login

:connect grok runs Grok Build, xAI's own coding agent, over ACP. To run SuperQode's harness on the same subscription instead, use :grok api [model], which imports the local grok login session and routes through the CLI chat proxy (see the BYOK provider docs).

Prime Agent is available through the native Python RPC client by default. Its ACP server remains a separate explicit route. The command root is :prime, with :prime-agent accepted as an alias:

:prime                        # command surface
:prime connect [model]        # connect through prime-agent-python-client
:connect acp prime-agent      # use Prime Agent's ACP server instead
:prime models [search]        # list the catalog, grouped by provider
:prime model                  # pick a model, then connect
:prime model ollama/qwen3.5:9b   # pin a provider and model
:prime depth 3                # recursion depth (RLM_MAX_DEPTH) for the next launch
:prime goal "ship the release"   # seed a persistent goal
:prime autonomous "pytest -q"    # autonomous mode with a completion gate
:prime agents                 # live sessions and the RLM subagent tree
:prime schedule               # scheduled and recurring prompts
:prime packages               # installed capability packages
:prime status                 # binary, version, logins, local providers
:prime doctor                 # background service health
:prime update                 # run Prime Agent's own updater
:prime login

Prime Agent fixes its model when the process starts, so :prime model pins the selection and reconnects instead of switching in place. Local models registered in ~/.prime/agent/models.json need no API key. See the Prime Agent provider docs.

A repository HarnessSpec works directly in the TUI:

superqode --harness prime-agent.yaml

You can also switch while the TUI is open with :harness switch ./prime-agent.yaml. Both forms connect immediately through the Python RPC client; the next prompt does not require :connect.

Optional Vim Navigation¶

Vim mode is optional. It adds Normal, Insert, Command, and Search states without removing the normal SuperQode command surface:

:vim
:vim on
:vim off
:vim tutor
:set vim
:set novim
:                 # enter a SuperQode command
/pattern          # search the transcript
j / k             # scroll or move through an active picker
gg / G            # transcript beginning or end
Ctrl+U / Ctrl+D   # page navigation
n / N             # search matches
h / l             # sidebar or main prompt
:w [path]
:e <file>
:ls
:grep <term>
q:
@:
:edit external    # compose the current draft in your editor (Vim mode)

The active input state is shown in the status bar and task prompt. The preference is persisted in ~/.superqode/config.json. See Vim-Like Terminal Navigation for the complete key reference, safety behavior, and supported scope.

In Vim Normal mode, entering :, /, or ? keeps your task draft, cursor and selection separately. Escape restores them, and submitting the command or search restores them after it runs. Connection setup keeps its selection and answer fields clear, then restores the task when you return. Draft recovery saves the task while a command or search line is open. Search mode interprets /help as a search for help; use : or Insert mode for commands.

With Vim enabled, Ctrl+E or :edit external opens the current task in your configured editor and returns to Insert mode for review before sending. Markdown headings are retained, editor arguments and shortcut overrides are supported, and an editor error leaves the original draft intact. The existing :edit and Ctrl+P actions still load the previous task for rewording. Vim-off shortcuts, approvals and the :connect workflow retain their existing behavior.

Compare Models¶

Re-run your last message across several models or runtimes at once and read the answers side by side. Each target runs a read-only chat completion concurrently, so this is safe to fan out - and because SuperQode is multi-runtime, you can mix providers in one comparison.

:compare openai/<openai-model> anthropic/<anthropic-balanced-model>
:compare <openai-model> <openai-fast-model>     # bare model names use the connected provider

Command Sandbox¶

:sandbox shows the active local command sandbox (mode, backend, and whether it is currently confining commands). Switch modes for the session with :sandbox <mode>:

:sandbox                   # show status
:sandbox workspace-write   # confine writes to the workspace
:sandbox read-only         # no writes outside temp, no network
:sandbox off               # disable

See Safety & Permissions for what each mode enforces.

Tool Activity Display¶

The TUI shows compact tool rows by default. Successful tools appear as compact action rows while failures remain visible with their error summary. Examples:

read_file(pyproject.toml)
grep("provider", src)
bash("uv run pytest tests")
python_repl(2 lines: "x = 1")

This keeps the main response readable while still showing what the agent did. Errors remain visible in normal mode. Use :log verbose when you need full successful tool output, and Ctrl+T when you need agent thinking/session notes.

Provider and Model Selection¶

Use :connect to choose between ACP agents, BYOK providers, and local model servers.

:connect
:connect byok
:connect local

The BYOK model view includes capability labels:

Local providers include DS4, Ollama, LM Studio, MLX, vLLM, and SGLang when supported by the current installation.

Harnesses In The TUI¶

Harness specs make TUI sessions repeatable. A harness controls runtime, model policy, tools, sandbox behavior, approvals, event storage, and output handling.

Create and check a harness before loading it:

superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml

Load it in the TUI:

:harness harness.yaml

Use a no-tool harness for planning or architecture review without file, shell, or repository tools:

superqode harness init planner --template no-tool --output planner.yaml
superqode --harness planner.yaml

Approvals¶

When the active policy requires approval, the TUI shows the pending operation before it runs.

:approve
:approve 1 always
:reject
:reject 1 "use a safer command"

Use always only when you want to allow matching requests for the rest of the session.

Configuration¶

TUI configuration in superqode.yaml:

superqode:
  tui:
    sidebar_width: 30
    show_line_numbers: true
    syntax_highlighting: true

Widgets¶

Available Widgets¶

Example Usage¶

from superqode.widgets import FileBrowser, AgentSwitcher

# File browser
browser = FileBrowser(root=project_root)
file = await browser.select_file()

# Agent switcher
switcher = AgentSwitcher()
selected = await switcher.select()

Integration with Harness Workflows¶

The TUI allows you to interact with agents for coding tasks, while harness-based workflows are run separately via CLI:

# Start TUI
superqode

# Run harness task via CLI (in separate terminal)
superqode harness run --spec harness.yaml --prompt "analyze this codebase"

Requirements¶

The TUI and its Textual and Rich dependencies are included in the standard SuperQode installation:

uv tool install superqode
superqode

Troubleshooting¶

TUI Not Starting¶

If the TUI fails to start:

1. Check Textual installation:

   python -c "import textual; print('Textual OK')"
   

2. Verify terminal compatibility:

3. Terminal must support ANSI escape codes

4. Recommended: iTerm2, Alacritty, Windows Terminal

5. Check terminal size:

6. Minimum: 80x24
7. Recommended: 120x40

Performance Issues¶

For slow TUI performance:

1. Reduce terminal size
2. Disable syntax highlighting
3. Use quick mode instead of deep mode

Jev tool checks¶

The built-in SystemOne coding harness includes progressive tool discovery, so users do not need an example file or source-tree path:

uv run superqode --tui --harness systemone

It defaults to unified BM25 retrieval with configurable ranking, Jev shadow judging over the shortlist, deferred native and MCP schemas, and the normal permission path. :systemone shows both the tool gate and a discovery summary; :systemone discovery shows the ranked candidates, selection, activation, and execution outcome. :discovery is an alias for that detailed view.

For the native Core/BYOK runtime, set TYPESAFE_API_KEY in the launching shell, then use :systemone live. :systemone shows configuration and the last check. Jev evaluates tool requests; your connected coding model still writes code. External agent runtimes do not use this native gate.

Every evaluation displays its outcome in the conversation, including model, latency, and input-token usage on success. ALLOW permits the call unless a hard policy or explicit policy ASK prevents it. DENY blocks it. Model ASK enters the normal approval flow, even for tools otherwise allowed automatically. API errors and unavailable clients visibly fall back to the existing permission policy.

For a standalone evaluation that executes no tools:

uv run superqode harness run examples/harnesses/systemone/tool-gate.yaml -p '{"tool":"bash","arguments":{"command":"pytest"},"grant":["bash"],"task":"run tests"}'

The JSON includes the actual response model, HTTP status, latency, and usage. A request failure fails the command. systemone.timeout_ms defaults to 5000 and bounds the entire evaluation including retries. Set systemone.record_dir in a harness spec to record sanitized requests and responses for replay. SYSTEMONE_LIVE_RECORD_DIR is only a destination override for live tests.

Direct decision sessions¶

Use :systemone connect factory_route (or :connect systemone factory_route) with TYPESAFE_API_KEY set to connect directly to Jev. This connection needs no coding provider. Enter Review this patch for correctness and security to get a typed route suggestion. The suggestion does not switch or execute a route. :systemone packs lists the bundled packs.

For a custom pack or a configured compatible endpoint:

:systemone connect examples/systemone/ticket-triage-pack.yaml
:systemone connect --spec examples/harnesses/systemone/ticket-triage.yaml

With the ticket pack, enter Our production checkout is down. Please help immediately. The result includes department (Choice), severity (Score), urgency (Noul), confidence, and usage. A result with status: abstain retains the raw answers but sets uncertain output values to null. The caller decides what to do next; the decision harness executes no tools.

Open-ended chat such as “What's the capital of the UK?” uses a coding/chat model: :connect → Connect model to harness → Core → BYOK → provider/model. Enter that provider's API key, not the TypeSafe key. :systemone live separately enables Jev tool checks. A chat answer that uses no tools will not invoke the gate.

See general decision harnesses for pack schemas, confidence policy, compatible endpoints, and CLI examples.

Resume and edit without leaving your session¶

Use :resume latest (or the welcome Continue last session action) to restore the most recent session without sending a prompt. Use :sessions or :resume with no id to open the searchable Session Browser: filter by title, harness, model, or id; page through large stores; inspect availability (ok, missing harness, bad credentials, external-only, missing transcript) and continuity (exact resume, context replay, cannot resume); rename; and resume the selection. Discovery and availability probes run in background workers, so large stores do not freeze input while the browser opens.

Long restored transcripts initially display the most recent 40 messages. Click Load earlier to prepend another page without losing newer turns or your reading position. The complete restored conversation remains available to copy and transcript search. Use :history earlier or :history later to navigate pages from the keyboard.

Connection setup preserves the displayed conversation, prompt draft, and reading position. Back or Escape from the root picker restores them. Short terminals show descriptions for the selected connection; the search dialog's details can be scrolled independently of its buttons.

After an editing or tool-using turn, :activity includes the recorded file changes, diff previews, and test-command outcomes. Unavailable test evidence is shown as Not recorded; the agent's prose alone does not establish that tests passed.

Newly saved custom harness sessions retain their spec path as well as their harness name. Keep that spec available when returning to the project. Resume reports missing credentials, working directories, and referenced transcripts; finish or cancel an active turn before switching sessions.

Local runtime switching is transactional: SuperQode prepares the replacement, then swaps it into the TUI only after resume succeeds. A failed replacement is closed while the current runtime remains active. ACP protocol-adapter resume is strict exact-or-fail and does not silently replace a failed resume with a blank session.

The browser discovers external harness and PiPy history without importing every historical record into the project store. It reads the original model, topic, and activity time from the backend record; only the session you resume is registered for future use. Selected session id and sidebar width are persisted per project under .superqode/ui-state.json.

Toggle the navigator with Sidebar in the header or Ctrl+B. Open Files with Ctrl+2 or :sidebar. Use arrow keys to browse, expand or collapse folders, and Enter to preview a file; mouse selection uses the same preview. Files open in a read-only viewer in the main workspace, leaving the tree available for the next selection. The sidebar's labeled section selector exposes Files, Git changes, Search contents, Context, Harness, Agent, History, and Task changes. Click the section selector, or focus it with Tab, press Enter, choose with Up / Down, and press Enter again. All sections are available either way. Use the sidebar's Narrow / Widen buttons to adjust its width, or drag the wider separator with the visible < > grip. The entire separator is a drag target. Width changes keep room for the main workspace and are saved per project. In a narrow terminal's temporary full-width navigator, resizing is disabled until you return to the file view. Dark themes use a black navigator background; light themes keep a readable light background. File, search, context and change lists use colored language symbols and badges (such as Python, JS, TS, C++ and Rust) without requiring a Nerd Font. Sidebar selection and hover colors follow the active theme. The main Contents viewer uses the theme's syntax colors, code background and readable line numbers; switching themes updates an open file without resetting its position. Ctrl+F searches filenames while focus is in the sidebar. Use Up / Down to choose a result, then Enter, or click the result. All returned filename matches are keyboard-accessible through the scrolling result window.

Esc closes file search, returns from the main viewer to Chat, then closes the sidebar and restores prompt focus. Ctrl+B hides or reopens the sidebar without resetting its selected section. Browsing retains the prompt draft and cursor, the transcript's reading position, and the recent file reading positions. The sidebar opens only when requested. Outside the sidebar and file viewer, Ctrl+F starts transcript search and saves an existing draft in :stash before prefilling the search command.

The existing Search tab searches file contents after a short typing pause. Ignored dependency and build directories are skipped before traversal, and outdated searches cannot overwrite newer results. Select a code-search result with the keyboard or mouse to reveal its matching line in the main viewer, within the preview limits below.

The viewer has Contents and Changes controls. Changes explicitly selects Working tree, Staged, or Latest task; task changes are relative to the recorded task baseline. Git changes includes untracked files. Selecting a staged or unstaged entry opens that specific comparison. Browsing never stages, accepts, rejects, or writes files.

Pin keeps up to four files in the file selector. Chat or Close returns to the conversation. The prompt box stays visible by default during source/diff inspection. The Hide prompt · F4 button at the top of the file view lets you hide it for more reading space; Show prompt · F4 or F4 brings it back while keeping the file open. Ctrl+I also reveals and focuses the prompt. The choice is retained while browsing during the current session, and the draft, cursor and file position remain intact. Sending a task or command returns to Chat to show its results; reopening the file restores its position. The viewer supports understanding and reviewing agent changes without editing source files. Use the prompt to ask the agent to make a change. An approval request or agent question returns to Chat so the decision and its input remain visible. Split enables source and conversation side by side in terminals at least 160 columns wide. Below 100 columns, opening a file hides the navigator; Ctrl+B temporarily shows it at full width for another selection.

With the file reader focused:

The toolbar also exposes Find, Line, Copy, and Path. Vim Normal mode adds j / k, gg / G, and Ctrl+U / Ctrl+D within the visible file reader. h focuses the file tree; l returns from the tree to the open reader. Search fields keep ordinary typing behavior. With Vim disabled, existing navigation remains active.

Source previews read at most 400 lines or 64 KiB per section. Next/Previous navigates larger files without loading their entire contents. Source search and line lookup scan the first 8 MiB; beyond that, use Next. Git diff previews are capped at 1 MiB and displayed in sections. Binary files show an explanation. The source cache retains at most four sections and eight file reading positions. Use your own editor for file edits.

Agent catalog and command completion¶

:connect acp all and the expanded harness picker combine SuperQode's offline agent catalog with the cached official ACP Registry. A registry refresh runs in the background, so opening the picker or typing a completion never waits for the network. Newly published ACP agents become searchable after refresh, while vendor and community integrations that are bundled only with SuperQode remain available. Use :connect acp refresh to request an immediate update.

Typing : or / exposes every declared TUI command. Contextual completion adds agents, providers, models, files, skills, recipes, MCP servers, and runtime values without hiding management subcommands such as :attach clear or :runtime doctor.

Reviewing a task and its next prompt¶

Use :diff task to open the latest task's per-file changes. Activity also offers Review changes on recorded task outcomes. These diffs compare against the working files before the run, so prior staged and unstaged edits remain part of the baseline. The existing :diff command still shows the full working tree.

In a task diff, Undo File (or u) restores one file to that baseline. Press it twice to confirm. Undo refuses a file that changed after the task, and does not alter Git's index. Baselines are kept for the latest three tasks in this TUI session. Files over 2 MB, symlinks and files without a captured baseline cannot be restored this way. Each task has a 32 MB snapshot budget. Task review requires a Git workspace; changes made concurrently during a run can also appear in the comparison, so review the diff before undoing.

Use :context next, or Inspect Next Prompt in the command palette, to inspect the draft, staged file/image/MCP references and available instructions and tools. Select a reference and choose Remove to exclude it while keeping the rest of the draft. Delete also removes the selected reference, and the preview stays open for further removals. Enter focuses the selected item's detail; Tab moves between controls and Esc returns to the draft with its cursor preserved. Instructions and tool lists are read-only. External harnesses and ACP agents own their final context; the preview identifies that boundary. MCP resources are fetched when sending, rather than when inspecting. Direct Chat keeps its existing context behavior.

After a failed connection attempt, :connect retry retries the same target. Failed setup restores the conversation and draft; connection catalog loading also has a Retry button that retains the search. :connect status distinguishes selection and setup from verified access.

The running indicator shows observed tool execution, approval/question waits and incoming response text alongside elapsed time. Waiting for a response does not claim a provider is healthy or identify the reason for a delay.

In Activity, Enter runs the selected outcome's recovery or review action when available; otherwise it focuses the evidence for scrolling. Connection search uses Up/Down to select results, while those keys scroll a focused detail pane. Routine success receipts remain in Activity without opening a popup.

For a repeatable local rendering probe, run python scripts/benchmark_tui_responsiveness.py. It measures streamed code, 10,000-message history, typing, scrolling and resizing at two terminal sizes. The output records headless local timings; SSH latency requires a real terminal session. Add --check --output tui-responsiveness.json to enforce the checked-in performance budgets and save a report. CI runs this check alongside the keyboard regressions and uploads the timing report as an artifact.

Draft recovery and terminal checks¶

SuperQode saves unsent text, cursor position and staged attachment references in .superqode/draft.json within the working directory after 500 ms without an edit or cursor movement, and flushes on normal exit. Returning to the same directory restores the draft without sending it. The file uses owner-only permissions; clearing the draft and its attachments removes it. Drafts larger than 1 MB are not saved. Image bytes are reloaded from the referenced paths when sending, so missing or changed images go through the usual send-time validation. A crash can lose edits inside the debounce window. Read-only workspaces remain usable without draft recovery.

Context preview, connections, outcomes and Activity show one compact line of shortcuts for the focused control. In context preview, Delete appears only for a removable reference.

Run python scripts/check_tui_terminal.py --output tui-terminal.json on macOS or Linux for an offline smoke check using real pseudo-terminals. It verifies bracketed multiline paste, Ctrl+J and CSI-u Shift/Alt+Enter, copy-command routing, OSC 52 emission, resize and Escape at 80×24 and 120×40. Native clipboard writes are disabled during the check. The two TERM profiles exercise terminal parsing; they do not simulate a running tmux server or an SSH connection.

Before a release that changes terminal handling, repeat these checks in macOS Terminal/iTerm2, a Linux terminal, Windows Terminal, tmux and an SSH session:

Record terminal versions and any extended-key or clipboard settings with the results. CI saves PTY reports, but acceptance of OSC 52 by a real terminal and remote clipboard policy require the live checks above.

Command discovery and recovery¶

:help shows implemented command roots, :help theme lists theme actions, and Ctrl+K searches the same command registry used by completion and dispatch. :hotkeys searches effective shortcuts in the app, composer and active modal. Ctrl+D is no longer an application shortcut; Ctrl+T toggles logs.

All declared binding actions can be customized by scope in ~/.superqode/keybindings.json. Existing flat action-to-key files still work. For example:

{
  "app": {"toggle_sidebar": "f2", "focus_input": "f6"},
  "SelectionAwareInput": {"clear_prompt": "alt+u"},
  "HotkeysScreen": {"close": "escape"}
}

Use the action and scope names from :hotkeys. Unknown actions, empty bindings and conflicting keys are reported instead of silently applied. Fixed text editing and contextual navigation gestures remain available alongside these declared actions. Overrides retain their action's priority and apply when a modal opens.

:compact summarizes earlier turns immediately while keeping the latest user turn and its replies. Add instructions, such as :compact focus on pending tests and exact file paths. The full transcript remains stored separately, and resumed native sessions use the summary. A failed or cancelled summary leaves the stored conversation available. Native context compaction requires an idle connected model; external harnesses use their own context commands.

:undo and :redo restore saved task states, including file creation, deletion and binary changes, while preserving pre-task edits and Git's index. If a task file has newer edits, the whole operation stops before changing any file. Checkpoints and recovery actions are stored locally so redo survives a restart. Retention keeps up to 50 recent checkpoints within a bounded local manifest; snapshots contain file content and stay on this machine. Oversized files or unavailable baselines cannot be restored. Rewind saves the original conversation as a separate recovery branch before trimming active history; its notification includes the session ID to resume.

Trusted project commands¶

Place Markdown prompts in .superqode/commands/<name>.md, then explicitly trust the project with :trust yes. Commands appear in completion and execute through a connected native SuperQode harness. Untrusted projects do not load these files. Project commands cannot shadow built-in commands or select a runtime, model, sandbox or approval policy.

---
description: Review the selected code
allowed_tools: [read]
---
Review $ARGUMENTS for correctness. Give file references and suggested fixes.

Run this example with :review src. $ARGUMENTS is literal prompt substitution, not shell evaluation. allowed_tools is optional: when present, it can only restrict the current harness, including remembered grants and nested tool scopes. Omitting it preserves the harness's existing policy; it never grants new permissions. Trust is checked again before execution, and symlinked files, malformed headers and permission-widening metadata are rejected. Use :settings for appearance, :trial for connection validation and a first task, and :feedback for a reviewed diagnostic export.