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

Open the splash to start a new brew. Press Cmd+N (Ctrl+N on Windows and Linux), or use the sidebar button labeled "Start new brew in" followed by your project name. The splash is the composer where you write the first prompt; its input reads "Pour a new one. @ to mention a file", and you 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.

On the workspace home surface, each installed agent shows a "Start with" entry naming that agent (for example "Start with Claude") next to its shortcut, so you can see which number maps to which agent.

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.

The row shows the agent, the session title, recent activity, and any worktree or cloud-run signal Coldtea knows about. The exact actions depend on the agent and the session record. For example, OpenCode sessions can expose resume and fork actions because OpenCode has session IDs Coldtea can use.

Search history

Use the brew history search in the sidebar to find an old session. Type into "Search brews…"; it needs a few characters before it searches. Open a result to bring that session back.

Open or resume a brew

Opening a brew brings the session back into the workspace. From a brew row you can "Open in active pane" or "Open in new tab". Depending on your settings, Coldtea may ask whether to replace the active pane or open the brew in its own tab. To always open resumed brews in a new tab, turn on the matching option in Settings.

"Resume session" reattaches to the agent's saved session so it keeps its prior context. Resume is available when the agent recorded a session ID that Coldtea can reuse. Before you send a follow-up prompt, check the path and branch. A resumed session still 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. From the row's menu choose "Rename", set the session name, and save. 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. "Delete session" removes Coldtea's session record, and for agents with their own saved-session command, Coldtea may also ask the agent CLI to delete the underlying saved session.

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. Fork is available on OpenCode sessions.

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.