Your First Session¶

This guide walks through a normal SuperQode TUI session: connect a model or agent, load a harness, ask for a repository task, approve tool calls when needed, and inspect what happened.

SuperQode is your portable coding agent harness. The TUI is the best place to explore a project because it keeps prompts, tool activity, approvals, file changes, and session state visible in one terminal.

Before You Start¶

You need:

• SuperQode installed: superqode --version
• A project directory
• One configured provider, ACP agent, or local model

Start in a Git repository when possible:

cd /path/to/your/project
git status

If this is your first run in a valuable repository, use a throwaway branch.

1. Launch The TUI¶

superqode

The TUI opens with a prompt at the top and the conversation area below it. Type natural-language requests in the prompt and press Enter to submit.

Useful keys:

2. Connect A Model Or Agent¶

Open the connection picker:

:connect

You can also connect directly:

:connect acp opencode
:connect byok openai gpt-4o-mini
:connect local ollama qwen3:8b

Check the current state:

:status

Use ACP when you want an external coding agent, BYOK when you want a hosted model with your API key, and local when you want Ollama, LM Studio, DS4, MLX, vLLM, or another local server.

3. Load Or Create A Harness¶

A harness defines the run contract: runtime, model policy, tools, sandbox policy, approvals, events, and output handling.

For the default coding setup:

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

Then load it in the TUI:

:harness harness.yaml

Other harness commands:

You can also start the TUI with a harness:

superqode --harness harness.yaml

4. Ask A Small First Task¶

Start with a low-risk prompt:

Summarize this repository and identify the smallest safe improvement.

Then try a focused coding task:

Find one low-risk bug or cleanup, make the smallest fix, and run the narrowest useful test.

The TUI keeps successful tool activity compact by default:

read_file(pyproject.toml)
grep("TODO", src)
bash("uv run pytest tests/test_config.py")

Use verbose logs only when you need detail:

:log verbose

5. Handle Approvals¶

When policy requires approval, the TUI shows the pending tool call before it runs. Review the command or file operation, then approve or reject it:

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

Use always only when you want to allow the same kind of request for the rest of the session.

6. Inspect Changes¶

Ask SuperQode what changed:

Summarize the files changed and the tests you ran.

You can also use normal Git commands in another terminal:

git status --short
git diff

If you ran through a harness, JSON runs include a run_id. Use it to inspect events and the graph:

superqode harness events <run-id>
superqode harness graph <run-id>
superqode harness graph <run-id> --json

7. Switch Runtime Or Provider¶

List available runtimes:

:runtime list

Switch runtime when available:

:runtime builtin
:runtime pydanticai
:runtime openai-agents

Use :connect again if you want to switch provider or model.

8. Run Checks When Needed¶

If your harness defines checks, ask the agent to run the narrowest useful one after making changes. You can also put the command directly in checks.custom_steps so the policy travels with the harness.

checks:
  enabled: true
  custom_steps:
    - name: unit-tests
      command: uv run pytest tests/test_config_loader.py
      enabled: true
      timeout: 300

For normal implementation work, stay in the TUI and use focused prompts plus harness policy:

Make the smallest safe fix and run the configured unit test.

Complete First Session¶

cd ~/projects/my-app
superqode harness init my-coder --template coding --output harness.yaml
superqode harness doctor --spec harness.yaml
superqode --harness harness.yaml

Inside the TUI:

:connect
: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.

Troubleshooting¶

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

Next Steps¶

1. Quick Start
2. Harness System
3. Terminal User Interface
4. Runtime Backends
5. Configuration Guide