Agents

An agent in Coldtea is still the CLI agent you already know. Coldtea does not turn Claude Code, Codex CLI, Gemini CLI, OpenCode, or another tool into a new chat surface. It launches the agent in a real terminal pane and keeps the surrounding workspace readable.

That detail matters. If the agent normally has slash commands, model selection, permission prompts, or provider setup, those still belong to the agent. Coldtea gives it a place to work.

What Coldtea owns

Coldtea owns the workspace around the agent:

• The project or worktree where the terminal starts.
• The pane that shows the live terminal.
• The task link when the brew is task-linked.
• The nearby plan, session log, editor, diff, and review surfaces.
• The local hooks and side channels that help Coldtea understand session state where supported.

That is the wrapper. It is not a replacement brain.

What the agent owns

The agent still owns its own behavior:

• How it reads your prompt.
• Which model or provider it uses.
• How it asks for permission.
• Which commands it proposes.
• Which files it edits.
• What session history the agent CLI stores.

If an agent behaves strangely in a normal terminal, fix that first. Coldtea can make the session easier to watch and review, but it cannot make a broken CLI healthy by hosting it.

Brews are agent sessions

A brew is an agent session inside Coldtea. It may be a quick prompt in a terminal pane, or it may be linked to a task with a plan and logs.

Use a plain brew for disposable work:

• Explain this file.
• Inspect the repo layout.
• Run one command and report back.
• Try a local experiment you expect to throw away.

Use a task-linked brew when the work needs a record:

• A teammate should review it.
• The agent will create a diff you may keep or ask someone to review.
• The work may take more than one session.
• You need to know which checks ran and what failed.

The same agent can do both. The difference is where the intent and handoff live.

Keep prompts small enough to review

Agents are easier to trust when the job has edges.

A useful prompt names:

• The outcome you want.
• The files or area that matter.
• What should stay out of scope.
• The check that would prove the change.

For example:

Update the install docs to mention agent CLI discovery. Keep the change to the docs app. Run the docs lint command when done.

That gives the agent something it can finish and gives you something you can review. "Improve the docs" does neither.

Watch the terminal, then review the diff

The terminal is the agent's working surface. Watch it when risk changes: a plan, a permission prompt, a failing command, or a broad edit.

After that, review like you would review a teammate's branch. Read the task, plan, session log, and diff. Run the checks that fit the change. A confident final message from an agent is not a substitute for review.

Next: read about context, or start with the first brew workflow.