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
Section titled “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
Section titled “Start an agent”There is no agent picker. Open a tab and type the agent’s command, as you would in any terminal:
claudemocante 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
Section titled “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
Section titled “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;
- for Claude Code 2.1.287 or later, add a mod that tells mocante how many
background agents still run and why a turn ended, so a tab stays
working until the last background agent finishes and an interrupted
turn shows as idle. The mod also reports how full the context window
is and what the session has cost, which the status bar and the fleet show
as
42% context · $1.37, and how much of your plan’s 5-hour and 7-day windows is used, which the status bar shows as5h 7% 7d 13%(hover for when each resets). In Claude Code itself, the mod shows a line above the prompt while mocante waits for you to answer a permission, with the time left, and a line when its hooks are older than mocante. It also shows a toast when mocante opens the session’s browser pane or opens a link from the session on your device. Type/mocante statusto see the session’s name, branch, tabs and dev servers without starting a turn.
A Claude Code prompt that sits idle for a minute is not a question for you, so it does not turn the tab to needs input. An agent that ends without saying so, for example when it is killed, leaves a shell in its tab: mocante then shows the tab as idle and keeps the conversation id, so you can resume it.
A Claude Code inside another tmux, such as a nested tmux in a mocante tab, does not speak for the mocante tab: its status, its permission prompts and the messages you send go only to the agent of that tab.
Hooks are optional. If a hook stops reporting, mocante goes back to reading the screen.
Install agent hooks
Section titled “Install agent hooks”When a tab runs an agent with no hooks on its host, a strip above the terminal offers Install hooks. Restart the agent after the install, because it reads its hooks only when it starts. Don’t offer again stops the offer for that agent on that host, on this device. You can still install from the command palette.
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. With more than one host connected, the first rows install an
agent on all hosts, and the last row, All agents, installs every
agent on every host. To install several, press
⇥on each row (or click its box), and then press↩. - 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;
- a file it must read is there but cannot be read, or the host does not answer in time. mocante never writes a config it could not read first;
- for Claude Code,
claudeis not on thePATH, or aclaude plugincommand fails. The message ends with the commands to run by hand.
A config file that the install changes, such as ~/.codex/hooks.json, keeps
its permissions. If you made it readable only by you, it stays that way.
Hooks need curl on the host. The result warns you when it is missing.
Keep hooks up to date
Section titled “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 mocantewith an Update hooks button. The host’s right-click menu has Update agent hooks and MCP. - 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. Each agent’s hooks have their own version, so a new Claude Code plugin marks only Claude Code tabs.
To update every host at once, click Update agents at the top of the Hosts page, or run Update agent hooks and MCP on all hosts from the command palette. mocante checks each connected host again, then installs again only the hooks and MCP servers that are out of date. It does not install for an agent that you did not set up on that host, and it keeps the settings you added to mocante’s MCP entry, such as turning it off. A notification shows what was updated, and gives the agent, the host and the reason for each update that failed.
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
Section titled “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.
Send a message or stop an agent
Section titled “Send a message or stop an agent”To give an agent a prompt without typing into its terminal, right-click its tab, its session or its row in the fleet and pick Send to agent…, or use the command palette. Write the message and press Send (or ⌘↩, Ctrl+Enter on Linux). This works from a phone too.
- With Claude Code 2.1.287 or later and mocante’s hooks installed, the message arrives as your own prompt. If Claude is busy, it waits and starts when Claude finishes.
- Other agents, and Claude Code without the hooks, get the message pasted into the tab and submitted, as if you typed it.
To interrupt an agent that is working, pick Stop agent. Claude Code with the hooks ends its turn. Other agents get Esc, which interrupts Claude Code and Codex.
Resume a conversation
Section titled “Resume a conversation”When an agent exits and its tab stays open, the tab falls 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.
After a reboot of the host, mocante restores the sessions and resumes each agent for you; see Restore sessions after a reboot.
To continue a conversation on a new branch instead, use Fork session…; see git workflow.
Add an agent mocante does not know
Section titled “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.