FAQ

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

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.

GitHub integration supports repository-aware Coldtea workflows where enabled. 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.

Are all features available to every team?

No. Agents, cloud runs, Matcha QA, integrations, and some task flows can depend on build, plan, feature flags, and TeaHouse setup.

Use the visible app surface as the source of truth for your workspace.

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.