Brews

A brew is an agent session in Coldtea. You pour a brew, an agent runs in a visible terminal pane, and the session shows up in the Brews sidebar so you can get back to it later.

Use the Brews sidebar when you want to return to a session, see which project or worktree it belongs to, or decide whether to reopen, resume, fork, rename, or delete it.

Pour a brew

Press Cmd+N (Ctrl+N on Windows and Linux) to start a new brew, or use the start button in the sidebar. Either way you land in the composer, where you write the first prompt and can mention a file with @.

Before the agent runs, pick which one to launch.

The agent picker

The picker chooses which CLI runs the brew. It lists the agents you have installed and enabled, with these labels:

• Claude
• Codex
• Gemini
• OpenCode

Coldtea manages Claude's auth. The other CLIs authenticate in their own pane. If an agent you expect is missing from the picker, it is not installed or not enabled yet. You set the list and its order in Settings under Agents.

Agent-launch shortcuts

Ctrl+1 through Ctrl+9 start a new brew with one of your installed agents. Ctrl+1 launches the first agent in your list, Ctrl+2 the second, and so on, following the order you set in Settings under Agents. These use Ctrl on every platform, including macOS, because Cmd+1 through Cmd+9 switch terminal tabs there.

The workspace home lists each installed agent next to its shortcut, so you can see which number maps to which agent without guessing.

Before you start

Check four things before you pour:

1. Project: the repo is the one you mean to edit.
2. Branch or worktree: the agent has the right lane of work.
3. Task: the work has a durable record if someone else needs to review it.
4. Agent setup: the CLI works in a normal terminal.

A plain brew is fine for a small question. Use a task-linked brew when the work may create a diff, need review, or outlive the current terminal session.

Write the first prompt

A good first prompt gives the agent a job, a boundary, and a check.

Read the task and inspect the docs app. Update only the workflow docs that are still stubs. Keep the voice plain and run the docs lint command when done.

That prompt is not fancy. It is useful because it tells the agent what to do, what not to do, and how to prove the change. See make a code change for the full loop.

What shows up as a brew

A brew usually comes from one of three places:

• A plain terminal agent session.
• A task-linked session started from the Tasks surface.
• A worktree session created for isolated branch work.

Each row shows the agent, the session title, recent activity, and whether the work happened in a worktree or a cloud run. Which actions you get depends on the agent: resume and fork need the agent to keep its own session record, which is why OpenCode sessions offer both.

Search history

Search the sidebar to find an old session. Type a few characters and open a result to bring that session back.

Open or resume a brew

Opening a brew brings the session back into the workspace, either in the active pane or in a new tab. Coldtea may ask which you want; to stop being asked, turn on the option to always open brews in a new tab in Settings.

Resuming goes further: it reattaches to the agent's own saved session, so it keeps the context it had. That is only possible for agents that save their sessions. Before you send a follow-up prompt, check the path and branch. A resumed session needs the same care as a terminal you never closed.

Before continuing an older brew, read the record first:

1. Read the task description.
2. Read the latest plan if one exists.
3. Read the relevant session logs.
4. Inspect the current diff.
5. Check the active path and branch.

Then send a prompt that names the next action. Do not ask the agent to "continue" if there are several possible meanings:

Continue from the latest session log. Fix the two review comments only, then rerun the docs checks listed in the task.

Rename and delete

Rename a brew when the generated title is too vague. Good titles are boring and specific:

• Fix login redirect
• Docs feature pages
• Review COL-290 diff

Delete old brews when the session no longer helps you. Coldtea removes its own record, and for agents that keep their own saved sessions, asks the CLI to delete its copy too.

Do not keep stale brews as a memory system. Put lasting context in a task, plan, or session log.

When to resume, fork, or start fresh

Resume when the next instruction is obvious from the current terminal state, task, plan, or diff. If you have to explain the whole job again, a fresh brew is usually cleaner.

Fork or start fresh when the old session has the wrong assumptions, too much stale context, a rebased branch, or a path you no longer trust. Start fresh too when you want a review-only pass with no edits, or when the next task is related but not the same task.

Worktree and task context

A brew can be tied to a worktree or a task. That is the useful version of history: not "here is some terminal output", but "this agent was working on this task in this branch".

Use task-linked brews when the work needs review or handoff. Use a plain brew for quick local questions and throwaway experiments.

Next: make a code change, or read the core brew model.