Control room

You don’t watch terminals. The task list tells you which agent needs you, which one has a problem and what is ready for you to look at, on your Mac and on your servers alike.

The list, by state

The middle column groups tasks by what they need from you, most urgent first:

Group	When a task stands here
Needs You	The agent waits for an answer or a permission, finished with a question to you, or stopped before it said its work was done (paused, not done yet).
Problems	The server isn’t reachable, the setup failed, the session ended with an error, a restart ended the agent’s subagents, or Done Means is red.
Ready for Review	The agent is done, the task has changes, and the checks didn’t fail.
Automatic Check	Done Means or the Second Opinion is running.
Working	The agent is working.
Resting	The agent is done without changes, or it is a shell.
Parked	The worktree is cleaned up, the branch kept; Resume brings it back.
Merged Today	Merged since midnight. Folded until you open it.

Done means the agent says so

A turn that ends isn’t always finished work: an agent may stop to report progress. In a task, Claude Code and Codex are told to run cavvy done as their very last step. Until they do, an agent that stops waits under Needs You with paused, not done yet, and the card asks you to read its last answer and tell it how to go on. Other agents count as done when they stop, as before.

Subagents lost in a restart

If a restart of the background service ends background agents that Claude Code had started, the task moves to Problems: Subagents ended by a restart names them, because their work may be half done. Let It Continue asks the agent to check what they left behind and carry on.

Unread

A blue dot means unread: a session finished and you haven’t opened it since, or a task gained a part you haven’t looked at. It isn’t a state of its own.

⌥⌘↓ (**Next Session That Needs You**) takes you to the next session that waits or finished unseen.

Questions above the terminal

When a task needs you, a card above the terminal says what it is about. Claude Code’s questions and permission requests stand there in full, because Cavvy reads them from Claude Code’s hooks. For other agents Cavvy shows what it can read from the screen, or says that the question is on the screen.

You answer in the terminal: Answer in the Terminal (⌘↩) takes you to it. The agent’s own interface stays what counts.

Notifications, Dock and menu bar

Settings → General → Attention:

• Notify when a session needs input and Notify when a session is done. Notifications offer Open and Later.
• Show count of sessions waiting for you on Dock icon.
• Keep Cavvy in the menu bar when the window closes, on by default. Closing the window then doesn’t quit Cavvy. The menu bar lists Needs You, Problems and Ready for Review, with New Task… below; the number next to the icon counts what needs you and what has problems.

The sessions themselves run in the background service either way, also when you quit Cavvy.

Since you last looked

Select All Projects with no task selected, and the right column shows Since you last looked: one card per project with what happened since you were last here, such as tasks started, parts taken in, checks, merges. The lines come from the event log of each server. Apple Intelligence writes at most the headline, and the page says so.

Usage

Usage at the bottom of the sidebar shows the five-hour and weekly limits of Claude Code and Codex, and when they are free again. Codex usage comes from its own files on this Mac. For Claude Code, turn on Read Claude Code’s login from the keychain in Settings → Usage; Cavvy then asks Anthropic with that login, at most every five minutes, and never renews it.

Step in at any time

• Answer or redirect an agent in its terminal, or with Return… from the review window.
• Stop all agents of a task with Stop Task…, or add a repository to it yourself with Take In a Repository.
• Comment on lines of a change; the comments go to the agent as one prompt.

What Cavvy tells the agents, and how to turn it off, is on What Cavvy changes in agents.