FAQ

Short answers for the questions that come up during setup and daily use.

What does Coldtea cover beyond writing code?

The same workspace holds the agent, the diff review, and Matcha QA, so a change moves from prompt to reviewed and tested without switching tools. Most agent tools stop at the build step. Coldtea keeps the rest of the lifecycle in the same place.

Does Coldtea replace my agent CLI?

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

Claude Code, Codex CLI, Gemini CLI, and OpenCode still own their own auth, models, slash commands, permissions, and session history.

Does Coldtea install agents for me?

No. Install the agent CLI the way that agent expects, then confirm the command works in a normal terminal.

If the agent command cannot start in your shell, Coldtea will usually fail to launch that agent too.

Are local agent sessions sandboxed?

Coldtea does not add its own sandbox. Local panes run as local processes with your user permissions, and each agent's own sandbox or approval settings still apply.

Worktrees separate Git working directories. They do not isolate credentials, network access, databases, package caches, or local services. See permissions.

When should I use a task?

Use a task when the work needs a durable record: scope, plan, logs, review context, or teammate handoff.

Skip tasks for disposable questions like "explain this file" or "run this command and tell me what happens."

When should I use a worktree?

Use a worktree when a task needs its own branch or when multiple agents should work in parallel without editing the same checkout.

For one small local change, the base project may be enough.

Why is my task or issue missing?

Check the active TeaHouse, selected team, and task board first. Then check integration sync and upstream permissions.

A Linear issue can be missing because the connected Linear account cannot see it. A GitHub-backed action can be missing because the GitHub App does not have repository access.

Does GitHub setup replace my local Git credentials?

No. The terminal still uses your Git remote, SSH keys, credential helper, and gh setup.

The GitHub integration backs repository-aware Coldtea workflows. It is not a replacement for local Git.

Where should secrets go?

Use the system designed for the secret: provider CLIs, credential helpers, environment managers, secret stores, or ignored local config files.

Do not paste secrets into prompts, task descriptions, plans, logs, annotations, screenshots, or shared setup instructions.

What leaves my machine?

For local terminal work, the checkout is local. Data can still leave when a tool sends it somewhere: the agent provider, Git remote, package registry, integration, cloud run, or QA service.

Use the specific agent and provider settings for the exact data path.

Why can I not see a feature I read about?

Most of the time it needs setup you have not done yet. Cloud runs need agent credentials and GitHub access. Matcha QA and the task board need a TeaHouse. An agent needs its CLI installed locally.

The pages here call out what each feature needs before it works. If the setup is done and it still is not there, see troubleshooting.

What should I do when an agent says it is done?

Read the diff. Then check the task, plan, session log, and the commands that ran.

An agent summary is useful context. It is not review.

Next: troubleshooting or the glossary.