Working With CLI Agents

The Mental Model

Use Coldtea like a focused development cockpit:

The agent still runs as its own CLI process.
Terminal output is rendered faithfully.
Agent commands and permission prompts stay native to the agent.
Coldtea observes files, tasks, sessions, and workspace state through side channels rather than parsing terminal output.

This keeps the agent familiar while giving your team better project, review, and context tools.

Coldtea includes discovery and launch support for common CLI coding agents, including Claude Code, Codex CLI, Gemini CLI, and OpenCode. Available launchers depend on your Coldtea version and workspace settings.

If an agent is missing from the launcher:

Confirm the CLI is installed.
Confirm the binary is available on your shell PATH.
Restart Coldtea so discovery can run again.
Check whether the agent needs first-run setup in a normal terminal.

OpenCode On Windows

OpenCode support on native Windows is planned as a WSL-first integration. The first Windows pass should run opencode inside a selected WSL distro, keep OpenCode config/auth/session files inside that distro, and show clear setup messages when WSL or WSL OpenCode is missing.

Native Windows launch through PowerShell, cmd.exe, or Git Bash is not part of that first pass. See OpenCode Windows and WSL support for the platform plan and QA matrix.

OpenCode Detection Health

Coldtea detects OpenCode by looking for the opencode binary through the user's login shell, the process PATH, and common package-manager locations such as npm global prefixes, Bun, pnpm, Volta, nvm, and Homebrew bin directories. Detection is cached briefly so startup and session listing do not repeatedly spawn shells or scan OpenCode session history.

Coldtea does not run opencode --version during startup detection. Package manager shims can initialize Node runtimes, so the startup health signal records only whether opencode was found and which safe source found it. If OpenCode is missing, the launcher marks it unavailable and logs the checked source names without logging full PATH entries, provider credentials, or OpenCode auth files. Install OpenCode in the shell you normally use, then restart Coldtea or wait for the discovery cache to refresh.

For saved-session discovery, Coldtea does not call opencode session list --format json on every workspace load. In OpenCode 1.15.11 that command exposes --max-count but no project filter or offset, so Coldtea resolves opencode db path with a short timeout, caches that database location briefly, and reads only session metadata for the current project page. If the command fails, times out, or the database schema cannot be read, OpenCode session discovery returns an empty list instead of blocking other agents. Older path-less OpenCode rows are matched by their stored directory path. Coldtea also canonicalizes a bounded set of recent path-less rows so symlink-equivalent legacy entries can still appear without scanning the full history. Very old path-less rows with unusual directory spellings may be omitted until OpenCode records path metadata for that session.

OpenCode Launch Policy

Coldtea launches OpenCode as opencode with no Coldtea-supplied default args. That preserves OpenCode's native TUI, first-run setup, /connect auth flow, model switching, and permission prompts. Agent Settings default args are still available as an explicit user preference: Coldtea appends them after opencode, before any operation-specific args.

Saved-session actions use OpenCode's TUI continuation flags:

opencode [user default args...] --session <session-id>
opencode [user default args...] --session <session-id> --fork

As of May 28, 2026, OpenCode's CLI docs list --fork as a flag used with --continue or --session, so Coldtea keeps the session ID on --session and adds --fork as the final operation-specific flag.

Coldtea does not default to opencode run or permission-bypass flags. If you add advanced args, OpenCode owns whether those flags are valid for the TUI.

Deleting an OpenCode brew uses opencode session delete <session-id>. Coldtea validates the session against OpenCode's global database before it runs the command, runs the command from the brew's project/worktree directory, and only then removes Coldtea-owned session metadata. If validation or deletion fails, the brew row shows a failure state with the OpenCode/validation error in its tooltip.

OpenCode export/import are future Coldtea share/restore features, not current brew actions:

opencode export [session-id]
opencode import <file|share-url>

Revert also remains future work and needs CLI re-verification before Coldtea adds UI for it.

Coldtea loads its notification plugin from a Coldtea-owned OPENCODE_CONFIG_DIR only inside panes that have the required Coldtea session environment. OpenCode merges that directory after global and project config; the Coldtea directory contains only the notification plugin, so user config remains available. Coldtea attaches its MCP server and startup prompt through session-scoped OPENCODE_CONFIG_CONTENT, which OpenCode merges after project .opencode sources. The inline content contains only {env:...} placeholders for COLDTEA_MCP_URL, COLDTEA_MCP_TOKEN, and COLDTEA_STARTUP_PROMPT_FILE, so the pane token and prompt text stay in process environment / temporary session files. OpenCode concatenates instructions arrays across merged config sources, so existing user/project instruction files stay active alongside Coldtea's startup prompt. Manual opencode launches preserve existing OPENCODE_CONFIG_DIR, OPENCODE_CONFIG, OPENCODE_CONFIG_CONTENT, and OPENCODE_TUI_CONFIG values rather than replacing user-provided config. If user-owned OPENCODE_CONFIG_DIR or OPENCODE_CONFIG_CONTENT prevents automatic Coldtea plugin or MCP/prompt attachment, the wrapper prints a terminal diagnostic.

OpenCode Auth And Provider Setup

Coldtea treats OpenCode auth as an OpenCode-owned setup step, not as a Coldtea credential flow. Product copy stays short and direct:

Agent Settings hint: "Runs bare opencode; OpenCode owns provider setup via /connect or opencode auth login."
First launch hint: "If OpenCode asks you to connect a provider, complete the prompt in this terminal. Coldtea does not collect or store OpenCode provider keys."
Missing-auth recovery: "Launch OpenCode in a Coldtea pane and run /connect, or run opencode auth login from a shell pane. Then restart the OpenCode session."

OpenCode's TUI includes /connect for adding provider credentials. Its CLI also documents opencode auth login, opencode auth list, and opencode auth logout in the OpenCode CLI docs. OpenCode stores credentials it collects in ~/.local/share/opencode/auth.json and, on startup, also loads provider keys from the environment or a project .env file. Coldtea must not ask for those API keys, write OpenCode auth entries, read the auth file to infer provider state, or copy provider credentials into any Coldtea-owned credential store.

Provider configuration still belongs to OpenCode and the user's shell. Users can bring credentials through:

OpenCode's /connect flow in the TUI.
opencode auth login in a normal shell or Coldtea shell pane.
Provider environment variables inherited from the user's shell, such as cloud provider credentials or service-specific API keys.
OpenCode config in opencode.json / opencode.jsonc, including provider settings and {env:VARIABLE_NAME} or {file:path} substitutions when the user wants config-managed secrets.

Link users to the OpenCode providers guide for provider-specific setup, subscriptions, local providers, custom OpenAI-compatible providers, and model naming. For providers that are not in the /connect list, the user should choose "Other" in OpenCode, create a memorable provider id, then configure that id in OpenCode config; Coldtea should not add a parallel "custom provider" form.

Troubleshooting should keep users in OpenCode's native flow:

Subscription or billing errors: confirm the provider account has the plan, model access, or billing state OpenCode expects, then reconnect with /connect.
API key errors: re-run /connect or opencode auth login, verify the key at the provider, and restart the OpenCode pane.
Model not available: run OpenCode's /models or opencode models, then use model names in <providerId>/<modelId> form.
Unsupported provider: use OpenCode's custom-provider instructions instead of entering a provider key into Coldtea.
Provider package/config errors: follow OpenCode's troubleshooting docs and recover from a normal Coldtea shell pane so you can see the exact OpenCode error. Start with the OpenCode troubleshooting guide.

OpenCode Task Metadata

Coldtea's generated OpenCode plugin tracks the root OpenCode session and sends that root id to /hook/complete as hookSessionId. The live PTY sessionId stays separate, so MCP task tools can link the pane to a Coldtea task while session logs and manually logged implementation plans attribute to the correct OpenCode conversation.

If an OpenCode pane reports that Coldtea has not captured the agent session id yet, start or complete one OpenCode turn and retry. If it still fails, verify the pane launched through Coldtea's wrapper/plugin path so session.status or session.idle events can reach the local API.

OpenCode has session and compaction plugin events, but no current automatic implementation-plan artifact hook equivalent to Claude's plan acceptance hook. Use task_log_implementation_plan from OpenCode when a plan should be stored on a Coldtea task.

Starting A Session

Open a Coldtea project.
Start an agent from the terminal empty state, shortcut, or task launcher.
Choose the target project or worktree when prompted.
Send the prompt exactly as you would in a normal terminal.

Start small when onboarding a new repository. A good first prompt is:

Inspect this repository and summarize the main app structure, test commands,
and any local instructions I should follow before making changes.

Working Safely

Treat every agent session as a real shell process.
Review file changes before accepting them.
Use worktrees when running multiple implementation sessions in parallel.
Keep prompts specific and verifiable.
Ask the agent to run the smallest relevant check after a change.

Coldtea helps organize sessions, but it does not remove the need for normal engineering review.

Multiple Sessions And Panes

Coldtea can manage multiple terminal panes and tabs. Use this when you want to:

Keep a dev server visible while an agent works.
Run tests in a separate shell.
Compare two agent sessions.
Isolate parallel tasks in separate worktrees.

When closing panes, pay attention to warnings about running agents or foreground processes.

Agent Artifacts

Some agents create plans, logs, annotations, or other files as they work. Coldtea watches for supported artifacts and can surface them in the workspace.

If an expected artifact does not appear:

Confirm the agent finished writing it.
Check the project or worktree where the session is running.
Refresh the relevant task or workspace view.
See Troubleshooting and FAQ.

Evolving Workflows

Coldtea will keep improving review and handoff workflows while preserving the same foundation: agents remain real CLI processes, and Coldtea coordinates context around them.