Troubleshooting

Start with the boring checks. Most Coldtea issues are about the wrong project, missing CLI setup, a stale shell environment, or the wrong TeaHouse.

First checks

Before digging deeper:

• Restart Coldtea.
• Confirm the selected project still exists on disk.
• Confirm the project is a Git repository.
• Confirm the active tab, path, and branch are the ones you expect.
• Confirm the agent command works in a normal terminal.
• Confirm you are signed in to the expected TeaHouse if you use shared tasks or integrations.

Agent does not appear

Check:

1. The CLI is installed.
2. The binary is available on your shell PATH.
3. The command works outside Coldtea.
4. The agent has completed its own first-run login or provider setup.
5. Coldtea was restarted after installing the agent or changing shell files.
6. Your build includes that launcher.

If the agent works in a normal terminal but not in Coldtea, capture the agent name and startup error before asking for help.

OpenCode auth or provider setup fails

Coldtea hosts OpenCode. It does not manage OpenCode provider keys.

Try:

• Start OpenCode in a Coldtea pane and run /connect.
• Or open a shell pane and run opencode auth login.
• Use provider environment variables or OpenCode config when your provider expects that.
• Restart the OpenCode session after reconnecting.

Do not paste API keys into Coldtea tasks, plans, logs, screenshots, or shared settings.

OpenCode tools or startup context are missing

Coldtea adds session-scoped side channels around OpenCode when it launches through the managed wrapper/plugin path.

Check:

• The pane was launched by Coldtea, not an unrelated terminal.
• The OpenCode pane printed any wrapper diagnostic about preserved OPENCODE_CONFIG_DIR or OPENCODE_CONFIG_CONTENT.
• Your own OpenCode config did not block Coldtea's plugin or MCP attachment.
• The pane has completed at least one OpenCode turn if session id capture is still pending.

For local API details, see MCP and local API.

Terminal pane looks stuck

Check whether the agent is:

• Waiting for a permission prompt.
• Waiting for keyboard input.
• Running a long command.
• Sitting inside a shell prompt after a failed command.

Try sending a newline only when you know the prompt is active. Open a second pane for diagnostics instead of interrupting a foreground process you still need.

Editor does not open

Try:

• Confirm a project is selected.
• Toggle the editor surface off and on.
• Restart Coldtea if the editor bridge did not become ready.
• Check whether your organization or local policy allows the selected project path.

If the terminal works but the editor does not, keep the terminal open while debugging so you do not lose the active context.

Tasks, plans, or logs are missing

Check:

• The active TeaHouse.
• The selected team or task board.
• Whether the agent session was launched from the task.
• Whether the work happened in a different project or worktree.
• Whether an integration sync is still running.
• Whether the upstream Linear or GitHub account can see the issue or repo.

A plain brew is not automatically task-linked. If you expected logs on a task, the brew needs to start from that task or use task-aware tools.

Worktree setup fails

Check:

• The base project is a clean enough Git checkout for the action you are taking.
• The base branch is the one you intended.
• .coldtea/config.json is valid JSON.
• Local overrides in .coldtea/config.local.json are valid and machine-safe.
• Setup commands can be rerun without breaking the worktree.
• Ports, local databases, and copied files do not collide with another worktree.

Worktree scripts run in visible panes. Read the failing command before retrying.

GitHub or Linear access looks wrong

Check both Coldtea and the provider:

1. Active TeaHouse and team.
2. Connected integration status.
3. Browser account used during auth.
4. GitHub App repository access or Linear workspace/team access.
5. Whether sync has had time to finish.

Coldtea membership does not override upstream permissions. GitHub and Linear still decide what their accounts and installations can see.

Local API or MCP tools are missing

Check:

• The agent was launched from Coldtea.
• The pane belongs to the expected project or worktree.
• You are signed in if the tool needs TeaHouse or task access.
• The feature is enabled for your workspace.
• The agent's config did not block Coldtea's session config.

Do not copy COLDTEA_MCP_TOKEN or local API URLs into support tickets unless your team has approved that path.

When to ask for help

Send the smallest useful report:

• What you tried to do.
• The exact project/worktree context.
• The agent and launch preset.
• The visible error message.
• Whether the same command works outside Coldtea.
• Which checks you already tried.

Leave out secrets, tokens, private customer data, and full terminal dumps unless someone specifically asks through an approved support channel.

Next: FAQ, agent setup, or security and privacy.