Mental model

Coldtea is easiest to understand if you stop thinking of an agent as a chat thread.

Think of each agent as a developer sitting in a visible terminal. Coldtea gives that developer a project, a branch, a task, and a place to leave notes. You still decide what work is worth doing and what changes are safe to ship.

The stack

Coldtea has a few layers:

1. TeaHouse — the team boundary for members, tasks, and integrations.
2. Project — a local Git repository.
3. Tab — a workspace context, often the base project or a worktree.
4. Pane — a terminal, editor, task, browser, or review surface.
5. Brew — an agent session doing work in that context.

When something feels confusing, trace it through those layers. Which TeaHouse owns the task? Which project is open? Which branch is active? Which pane is the agent using?

Agents run in terminals

Coldtea hosts CLI agents in real terminal panes. That is a deliberate choice.

It means the agent can use the same shell, repo, scripts, package managers, and credentials you already use. It also means the agent can make the same kind of mess a shell command can make.

Coldtea adds context and visibility around the terminal. It does not turn every command into a safe command.

Tasks hold intent

A task says what should be done and why. Good tasks are useful to both humans and agents:

• What is the user-visible problem?
• What should be changed?
• What should not be changed?
• What would count as verified?

If you cannot write that much, the task may not be ready for an agent yet.

Plans hold direction

An implementation plan is the proposed route before the edit. It should name the likely files, constraints, and checks.

Plans are not ceremony. They are where you catch a bad approach before it becomes a diff.

Logs hold what happened

A session log is the trail after work starts. It should help someone answer:

• Which agent worked on this?
• What did it change?
• What checks ran?
• What failed or still needs attention?

Logs are especially useful when a task takes more than one brew.

Worktrees split risk

A worktree gives a stream of work its own directory and branch. Use one when two agents need to work at the same time or when you want to try an idea without touching the base checkout.

Do not confuse Git isolation with security isolation. A worktree keeps file edits apart. It does not sandbox network access, credentials, or shell permissions.

The human job

Coldtea is built so you can delegate without going blind. The human job is still to set intent, keep scope tight, review the diff, and decide what ships.

Next: tasks, plans, and logs.