Skip to content

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.

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.

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

Terminal window
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.

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.

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 as 5h 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 status to 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.

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.

  1. Open the command palette (⌘K) and pick Install agent hooks….
  2. 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 ↩.
  3. Read the result. It lists the files mocante wrote and any warnings.
  4. 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, claude is not on the PATH, or a claude plugin command 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.

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 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.

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.

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.

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.

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:

~/.config/mocante/agents/aider.json
{ "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.