Agent matrix
Coldtea launches agent CLIs. It does not install them, log in for them, or replace their own permission model.
Use this page when an agent is missing from the launcher, starts with the wrong defaults, or behaves differently from another agent.
Supported local launchers
Coldtea launches four local CLIs: Claude Code, Codex, Gemini, and OpenCode. Cursor is not supported.
| Agent | Command Coldtea looks for | Default local launch | Setup owner | Notes |
|---|---|---|---|---|
| Claude Code | claude | --permission-mode default | Claude | Coldtea manages Claude auth and can pass task and MCP context. Claude still owns slash commands, model choice, and permissions. |
| Codex | codex | --sandbox workspace-write --ask-for-approval on-request | Codex | Coldtea can attach MCP through Codex config args for launched panes. Codex sandbox and approval behavior still comes from Codex. |
| Gemini | gemini | --approval-mode default | Gemini | Coldtea registers a coldtea MCP server in Gemini settings using session environment variables. Gemini owns auth and approval modes. |
| OpenCode | opencode | no extra args | OpenCode | Coldtea attaches its tools through OpenCode's own config. OpenCode owns /connect, provider setup, model switching, and its TUI prompts. |
Except for Claude, each local CLI authenticates in its own pane. Which agents you see depends on which binaries Coldtea can find on your machine.
Background and cloud agents
Background and cloud runs use three agents: claude, codex, and opencode. Gemini is local only and has no Coldtea auth screen.
You set cloud agent credentials in settings, or when Coldtea first needs them for a cloud run. Two methods are available:
| Agent | API key | Subscription |
|---|---|---|
| claude | Paste a provider API key. | Use your Claude subscription with a setup token. |
| codex | Paste a provider API key. | Use your ChatGPT subscription by signing in through codex login. |
| opencode | Connect through OpenCode, not a pasteable key. | Connect through OpenCode. |
You can skip cloud setup during onboarding and add it when you first need a cloud run.
How discovery works
Coldtea checks for known agent binaries through the shell environment and common install locations. It launches the bare command name, such as codex, so package-manager shims and version managers still choose the runtime.
If an agent is missing:
- Run the command in a normal terminal.
- Finish the agent's own first-run login or setup.
- Make sure the binary is on
PATHfor the shell Coldtea opens. - Restart Coldtea after changing shell setup.
- Check Settings → Agents for saved launch args.
Do not debug provider auth from Coldtea first. If the agent cannot start outside Coldtea, fix the agent install first.
Launch presets
Settings can save default launch args per agent. The presets are convenience wrappers around each CLI's own flags.
| Preset idea | What it usually means |
|---|---|
| Supervised | Start with the agent's normal approval flow. |
| Plan or read-only | Prefer inspection and planning before edits. Availability depends on the agent. |
| Auto-edit | Let the agent apply edits more freely while keeping other prompts. Availability depends on the agent. |
| Full autonomy or full access | Bypass more approval or sandbox checks. Treat this as a deliberate risk choice. |
OpenCode is different here: Coldtea's default local preset runs the OpenCode TUI directly and lets OpenCode own provider and permission prompts.
Task tools and MCP
Agent panes launched by Coldtea may receive session-scoped MCP access. That can let an agent inspect panes, read task context, write logs, drive the in-app browser, or work with labels and QA runs when those tools are available.
Not every pane gets every tool:
- The agent must be launched from Coldtea.
- Some tools require TeaHouse or task access, so you have to be signed in.
If MCP tools are missing, see MCP and local API.
What Coldtea does not own
Coldtea does not choose the model response, bypass a provider's account limits, or make an unsafe command safe.
For every agent, keep the same rule: if the CLI is asking to run a command, read the command as if you typed it yourself.
Next: connect agents or permissions.