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
• 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

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.

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 three 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. The conversation transcript stores a compact receipt for later review.

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
• :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 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 (size + fit)
• :hub: Enter model-search mode and type a model name (off by default)
• :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
• :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
• :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)
• :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
• :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
• :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.

:sodebar is retained as a compatibility alias for :sidebar. New documentation and scripts should use :sidebar.

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.

On builtin connections (local models and BYOK providers), a message submitted mid-run is steered into the current run: it lands between the agent's tool calls and shapes the work in progress. The log confirms delivery with steering the current run. This is the fastest way to correct course ("skip the docs, focus on the failing test") without cancelling anything.

On connections that cannot be steered (ACP agents, vendor SDK runtimes) and during selection or question flows, messages go to the type-ahead queue instead. The queue renders under the prompt with a live preview and sends automatically when the agent is free. :queue clear empties it.

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

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 ships several accent themes on top of its dark identity. Open the picker with :theme, or apply one directly with :theme <name>:

:theme            # open the picker with live swatch previews
:theme tokyonight
:theme dracula

The choice is saved to ~/.superqode/config.json and applied on the next launch.

Accessibility¶

:theme high-contrast maximizes legibility for low vision or a bright room. Where the other themes use low-contrast greys to de-emphasize text, this one keeps every text tone at or above the WCAG AAA ratio of 7:1 against the background, and keeps success, warning, error, and info distinct from one another.

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>
:harness switch <name>
:harness switch <name> --fork
:sessions switch
:sessions switch <id>
:resume <id>
: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 switch opens a picker that labels every session with its latest harness. Selecting one restores its harness, model, and conversation history.

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

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).

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:
@:

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.

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