Skip to content

Connection Profiles

Seven connection profiles determine how SuperQode connects to model providers and agent runtimes. Each profile has a connector type, optional runtime, and detect() check.

Connection Profiles

1. ACP Agent (connector: acp-picker)

Opens an interactive picker showing all discovered ACP agents (OpenCode, Claude Code, Gemini CLI, Codex CLI, OpenHands, etc.). Always available. No model auth setup needed.

2. BYOK Provider (connector: byok, runtime: builtin)

Brings your own API key. Opens a cloud provider picker, then model selector. Uses builtin runtime. detect() checks for any of 7 API key env vars (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).

3. Local Model (connector: local, runtime: builtin)

Connects to local/self-hosted model servers. Opens a local provider picker (Ollama, MLX, LM Studio, vLLM, SGLang, TGI, DS4). Always available.

4. Codex Subscription (connector: runtime, runtime: codex-sdk)

Self-contained: brings its own model and auth via Codex login. Requires openai_codex package and ~/.codex/auth.json. Auto-connects on selection.

5. Claude Agent SDK (connector: runtime, runtime: claude-agent-sdk)

Self-contained: uses Anthropic API key directly. Requires claude_agent_sdk package and ANTHROPIC_API_KEY. Auto-connects on selection.

6. Antigravity CLI (connector: external-cli)

Handoff profile: shows the command to run agy in a terminal. Does not connect SuperQode's own loop. Requires agy binary on PATH.

TUI Usage

In the TUI, use :connect to open the type picker. Each profile shows availability status (green "ready" or yellow "needs setup" with guidance). Navigate with arrows or number keys.

Direct shortcuts:

  • :connect codex - connect Codex SDK directly
  • :connect claude - connect Claude Agent SDK directly
  • :connect antigravity - show agy handoff
  • :connect byok [provider[/model]] - connect to cloud provider
  • :connect local [provider[/model]] - connect to local provider
  • :connect acp [agent] - connect to ACP agent

Special syntax: :connect byok - (previous), :connect byok ! (history), :connect byok last (reconnect).

CLI Usage

Use --connect / -C global flag:

superqode --connect codex --print "review this"
superqode -C claude --print "summarize changes"

Use superqode connect subcommands:

superqode connect acp opencode
superqode connect byok anthropic claude-sonnet-4
superqode connect local ollama qwen3:8b
superqode connect setup deepseek --json

Runtime Mapping

  • Codex profile -> runtime: codex-sdk
  • Claude profile -> runtime: claude-agent-sdk
  • BYOK/Local -> runtime: builtin
  • ACP -> no runtime change (ACP subprocess)
  • Antigravity -> handoff (no runtime)
  • Advanced -> user picks runtime

When --connect implies a runtime, it sets SUPERQODE_RUNTIME but does not override an explicit --runtime flag.