Troubleshooting And FAQ

First Checks

Start with the basics:

• Restart Coldtea.
• Confirm the selected project still exists on disk.
• Confirm the project is a Git repository.
• Confirm your CLI agent works in a normal terminal.
• Confirm you are signed in to the expected team workspace if you use shared tasks or integrations.

An Agent Does Not Appear

Check the following:

• The agent CLI is installed.
• The agent binary is available from your normal shell.
• The agent has completed its own first-run login or setup.
• Coldtea was restarted after installing the agent.
• The project is selected before launch.

If the agent works in a normal terminal but not in Coldtea, capture the exact agent name and startup error before contacting support.

OpenCode Auth Or Provider Setup Fails

Coldtea hosts OpenCode; it does not manage OpenCode provider credentials. If an OpenCode pane reports missing auth, invalid API keys, subscription limits, or an unavailable model:

• Launch OpenCode normally in a Coldtea pane and run /connect.
• Or open a shell pane and run opencode auth login.
• Use provider environment variables or OpenCode provider config when that is how your provider expects to authenticate.
• Check the OpenCode providers guide for provider-specific setup and custom provider config.
• Check the OpenCode CLI docs for opencode auth commands.
• Check the OpenCode troubleshooting guide for auth, model, and provider package recovery.

After reconnecting, restart the OpenCode session from Coldtea. Do not paste API keys into Coldtea settings; enter them only into OpenCode or your shell/config.

OpenCode Wrapper, Logs, Or Config Look Wrong

Coldtea adds only session-scoped side channels around OpenCode. If OpenCode launches but Coldtea lifecycle, MCP, startup prompt, or saved-session behavior is missing:

• Inspect the Coldtea dev app log or support log for [coldtea:agents], [coldtea:terminal], [coldtea:local_api], and [coldtea:lifecycle].
• Inspect the OpenCode pane output for wrapper diagnostics about preserved OPENCODE_CONFIG_DIR or OPENCODE_CONFIG_CONTENT.
• Check Coldtea's shell integration files under ~/.coldtea/shell/ or, on RC builds, ~/.coldtea-rc/shell/. OpenCode files should include bin/opencode and hooks/opencode/plugins/coldtea-notify.js.
• Check OpenCode config in ~/.config/opencode/opencode.json, project opencode.json / opencode.jsonc, and .opencode/.
• Use OpenCode's own diagnostics from a shell pane when the problem appears to be inside OpenCode itself. For example: opencode --print-logs --log-level DEBUG.

Treat OpenCode auth files, Coldtea MCP tokens, and local API URLs as sensitive. Do not copy the contents of ~/.local/share/opencode/auth.json into bug reports.

A Terminal Pane Looks Stuck

• Check whether the agent is waiting for approval or keyboard input.
• Try sending a newline if the agent prompt is active.
• Avoid closing panes with active foreground processes.
• Open a second pane for diagnostics rather than interrupting the active agent.

Coldtea renders the real terminal, so native agent prompts and shell state still matter.

The Editor Does Not Open

Try these checks:

• Confirm a project is selected.
• Reopen the editor surface.
• Restart the desktop app if the editor bridge did not become ready.
• Confirm your organization or local policy allows the selected project path.

Tasks Or Plans Are Missing

• Refresh the task view.
• Confirm you are in the expected organization or team context.
• Confirm the agent session was launched from the task when you expected a task link.
• Wait for sync to finish if the task came from a connected integration.
• Check whether the work happened in a different project or worktree.

For parallel work setup, see Parallel agents and worktrees.

Linear Or GitHub Auth Fails

• Confirm you are signed in to the expected browser account.
• Retry the connection flow from Coldtea.
• Check whether the browser page says the connection succeeded and can be closed.
• Confirm your account has access to the workspace or repository you are trying to connect.

For local permission boundaries, see Security and permissions.

FAQ

Does Coldtea replace my agent's CLI?

No. Coldtea hosts the CLI in a real terminal and adds workspace, review, task, and team context around it.

Does Coldtea require cloud features?

The core desktop terminal and editor loop is local-first. Team features, shared tasks, and integrations use cloud services where required.

Should I use worktrees?

Use worktrees when running parallel agents, testing risky ideas, or keeping a task isolated from your main checkout. For one small task, the current project directory is often enough.

Are all capabilities available to every team?

No. Available agents, integrations, and team features depend on your plan, workspace settings, and the version of Coldtea you are using. Use the visible app surfaces as the source of truth.