Agents

mocante runs the real agent CLIs in your terminal tabs and watches them. It tells you which agents work, which wait for you and which failed, without changes to how you start them.

Supported agents

Agent	Command	Exact status through hooks	Approve from a notification	Resume
Claude Code	`claude`	yes	yes	yes
Codex CLI	`codex`	yes	yes	yes
opencode	`opencode`	yes	no	yes
pi	`pi`	yes, except “needs input”	no	no

Any other program runs as a plain shell tab. You can teach mocante a new agent.

Start an agent

There is no agent picker. Open a tab and type the agent’s command, as you would in any terminal:

claude

mocante recognizes the agent from the process name and from what it draws on screen. The tab then gets a status dot, and an auto badge that tells you it was detected in a shell. An agent started through node, bun, deno, python, python3 or uv is recognized too.

When the agent exits, the tab goes back to a plain shell.

Statuses

Each agent tab has one of five statuses:

Status	Meaning
needs input	The agent waits for you: a permission prompt, a question or a choice.
error	The agent reported an error.
working	The agent is busy.
completed	The agent finished its turn.
idle	Nothing happens in the tab.

A session takes the most urgent status of its tabs, in the order of the table. When a host is unreachable, its sessions show as offline instead.

The fleet view and the sidebar sort by these statuses, and a switch to needs input sends a notification.

Hooks make status exact

Without any setup, mocante reads each agent’s screen to guess its status. This works for all agents, but a redrawn dialog or a reworded prompt can cause a wrong guess, and a change shows only at the next check.

With hooks installed, the agent tells mocante what it does, the moment it happens. Hooks also:

record the agent’s conversation id, which resume needs;
let you approve or deny a tool call from a notification (Claude Code and Codex);
for Claude Code, install the mocante MCP server too.

Hooks are optional. If a hook stops reporting, mocante goes back to reading the screen.

Install agent hooks

Install hooks once per agent, on each host where you run it.

Open the command palette (⌘K) and pick Install agent hooks….
Pick the agent. Each row names the host: this device or the remote host’s name.
Read the result. It lists the files mocante wrote and any warnings.
Restart the agent in each open tab. No agent reloads its hooks while it runs.

What the install changes on the host:

Agent	Change
Claude Code	Adds a `mocante` plugin through `claude plugin`. Your `settings.json` hooks stay as they are.
Codex CLI	Adds entries to `~/.codex/hooks.json`, next to yours.
opencode	Writes `~/.config/opencode/plugins/mocante-hook.js`.
pi	Writes `~/.pi/agent/extensions/mocante-hook.ts`.

The install stops without a change, and tells you why, when:

a file it would write already exists and mocante did not write it;
a config file is not valid JSON;
for Claude Code, claude is not on the PATH, or a claude plugin command fails. The message ends with the commands to run by hand.

Hooks need curl on the host. The result warns you when it is missing.

Keep hooks up to date

A new mocante version can need newer hooks. mocante checks the hooks on each host when it connects, and once an hour after that.

The Hosts page shows a line such as claude code hooks are from an older mocante with an Update hooks button. The host’s right-click menu has Update agent hooks.
The fleet view shows a warning with a View hosts button.
A tab whose agent reports through old hooks shows a small hook icon in the tab strip.

After you update, restart the agent. A running agent keeps its old hooks until it restarts.

If a hook file on a host was not written by mocante, the Hosts page says so and mocante leaves it alone.

Remove hooks

Pick Uninstall agent hooks… in the palette, then the agent and host. mocante removes only its own entries and files, and then reads the screen again. Restart the agent afterwards.

Resume a conversation

After a reboot or a tmux crash, an agent tab can fall back to a plain shell. If mocante knows the conversation id, the session header shows a Resume button. Click it, or pick Resume agent in the palette, and mocante types the agent’s resume command into the tab:

Agent	Command
Claude Code	`claude --resume <id>`
Codex CLI	`codex resume <id>`
opencode	`opencode --session <id>`

mocante learns the id from the hooks, so resume needs them. The id stays on this device only. pi has no resume flag, so pi tabs do not offer resume.

To continue a conversation on a new branch instead, use Fork session…; see git workflow.

Add an agent mocante does not know

You can describe another agent in a JSON file in ~/.config/mocante/agents/ on the machine that runs mocante. The smallest file names the agent and its command:

{ "id": "aider", "name": "aider", "commands": ["aider"] }

mocante then detects aider in any tab and reads its status with the default rules. A file whose id matches a built-in agent (claude, codex, opencode or pi) replaces that agent’s rules. mocante reads a changed file without a restart, and ignores a file that is not valid.