Skip to content

Agent tools

mocante offers an agent a set of MCP tools that act on the session the agent runs in. With them, the agent can find out where it is and what you are looking at, rename or close its session when the work is done, show you a file, check its dev servers and drive the session’s built-in browser. “We are finished, clean up after yourself” becomes one instruction to the agent instead of a trip back to the dashboard.

An agent can also reach beyond its session: give the agent in another session a task, start a new session with an agent in it, clone a repository as a new workspace, or add a project. “Fix the docs in parallel while you finish this” becomes one instruction too.

  1. Open the command palette with ⌘⇧P (Ctrl+Shift+P on Linux) and run Install agent MCP server….
  2. Pick the agent and the host. The list shows each agent with an MCP client on each connected host: Claude Code, Codex and opencode. pi has no MCP client, so it is not listed.
  3. Restart the agent. None of them load new MCP servers while they run.
  4. Check the install: in Claude Code or Codex, /mcp lists mocante.

Install once per agent on each host where you run it. On a remote host nothing else is needed: the tools reach your device through the connection mocante already has.

For Claude Code, the tools come in the same mocante plugin as its hooks, so Install agent MCP server… and Install agent hooks… do the same thing for Claude Code. In Claude Code the tools are named mcp__plugin_mocante_mocante__<tool>. If you wrote permission rules for the older mcp__mocante__<tool> names, update them.

To install the newest bridge on every host after a mocante update, run Update agent hooks and MCP on all hosts from the command palette. It changes only the hosts where the server is installed and out of date.

If the agent is not found on the host, the install fails and shows the command to run by hand.

Most tools act on the session the calling agent runs in. session_send and session_stop reach another session, and only its agent: they cannot rename, close or browse it. session_create, workspace_add and project_add only add new things; they cannot change or remove what is there. setup_command_set changes only the worktree setup command.

Tool What it lets the agent do
session_info Read its session: name, host, project, workspace, branch, worktree path, tabs, and what is on your screen.
session_rename Rename the session, for example after the task it turned out to be.
session_close Close the session, remove its worktree and delete its branch.
session_share Show you a file: a screenshot, a recording, a report. See files.
review_list Read your review threads on the worktree’s code, and those of no agent.
review_reply Answer in a review thread, and resolve it when it is done.
review_resolve Resolve a review thread.
review_comment Start a review thread on lines of a file, to point you at code.
session_list List every session with its project, host, branch and the agents in it, with their status.
session_send Send the agent in another session a message, which it gets as its next prompt.
session_stop Interrupt the agent in another session while it works.
workspace_list List the projects with their workspaces, and the hosts.
session_create Start a session with an agent in it, on a branch of its own, and give that agent a task.
workspace_add Clone a repository onto a host as a new workspace of a project, or add a folder that is there.
project_add Add a project.
setup_command_set Set or clear the worktree setup command of a workspace or a project.
server_list List the session’s dev servers: state, ports and address of each.
server_logs Read the recent output of one dev server.
server_restart Restart a dev server, or start a stopped one.
browser_* Open, read, click, type in, screenshot and close the session’s built-in browser.

session_info tells the agent which panes of its session you have open, the file in the code view, the page in the browser pane, and which pane has the keyboard. So you can say “look at the file I have open” or “what is wrong with this page” without a path or a URL.

An agent can give another session’s agent a task with session_send, for example “ask the agent in the docs session to document this flag”. The message starts with a line that names the sending session, so the agent knows where it came from, and that it came from another agent, not from you. The agent that gets the message can answer with session_send too.

How the message arrives depends on the two agents:

  • Claude Code to Claude Code on the same host: the message goes through Claude Code’s own messages between sessions, marked as from another session, not from you. Claude reads it between its tool calls, or starts a turn with it if it is idle. If the receiving session holds messages from other sessions for your approval, approve it there. This does not work when the sending session is in auto mode, which refuses it, so the message goes the next way instead.
  • To Claude Code otherwise: mocante’s hooks give it to Claude Code as its next prompt, once it finishes what it is doing. Anything you have typed and not sent stays in the prompt box.
  • To any other agent, or to Claude Code without mocante’s current hooks: it is typed into the agent’s tab and sent. Anything you have typed there and not sent goes with it.

After you update mocante, run Install agent hooks… and restart Claude Code, so each session loads the current hooks.

A message to, or a stop of, an agent in a session on another host always asks for your approval, whatever Ask before an agent messages another session says. Allow it for the session, and the agent can keep the conversation going without asking again. This approval is separate from the one for sessions on the same host: allowing messages on the same host for the session does not allow messages to another host. This keeps an agent on a remote host from typing into the agents on your own computer unless you agreed to it. Sessions that started each other never ask.

With session_create, an agent starts a new session, starts an agent in it, and gives that agent a task. Ask for it in your own words, for example “start a session on the branch docs/search and have it document the search flags”. The new session shows in the sidebar like any other, and you can watch it or type into it.

  • In a git repository, the new session works on a branch in a worktree of its own, so the two agents do not change each other’s files. A branch that does not exist yet starts from the repository’s default branch.
  • The new agent is the same kind as the one that asked, unless it asks for another one, such as Codex.
  • The task arrives once the new agent is ready. If the agent asks you something when it starts, such as whether to trust a new folder, answer it in that session first.
  • The new agent can send its result back with session_send. mocante also tells the agent that started it when the new agent finishes a turn, waits for input, stops on an error, is interrupted before it finishes (this last one needs the agent’s hooks), or closes its session. So the first agent can check the work, answer a question, or give it more.
  • Messages between the new agent and the agent that started it need no approval, in either direction. Other agents in the first session are not part of this, and a message to them counts as one between any two sessions. A rename keeps the link, and so does moving the first agent’s tab to another session.
  • The new agent reports only to the agent that started it. If you close that agent’s tab or session, the new agent keeps its result in its own session for you to read. A session you start again under the closed session’s name is a new session: a message from either agent to it always asks for your approval, so the result never reaches it by mistake, and you can still allow it. You can also tell the new agent to message any other session.
  • A session started this way cannot start sessions itself, and one session can have at most eight of them running at a time.

With workspace_add, an agent clones a repository onto a host as a new workspace of a project, for example “check out github.com/acme/billing in the Acme project and look at its tests”. By default the clone goes into the project’s base folder, under the repository’s name, on the host the agent runs on. If a workspace on that host was already cloned from the same URL, the agent gets that one instead. A large clone can take a while: the agent hears when it is ready. With project_add, an agent adds a new project to put workspaces in.

session_close ends the agent that calls it, together with every tab of the session. The agent gives you its summary first, then calls the tool.

Before it removes anything, the tool checks for work that would be lost: uncommitted changes, or commits that no remote branch has. If it finds any, it refuses and tells the agent how many. The agent can then commit and push, or close anyway if you tell it to. The agent can also close the session and keep the worktree for later. A session in the main checkout has no worktree, so closing it only ends the session.

When you move a Claude Code conversation to the background with /background, the agent keeps its mocante tools in the same session. mocante follows the conversation from the tab it ran in, so this works only for a conversation that ran in a mocante session’s tab, or one you resume with claude --bg --resume. A job that you start with claude --bg from a shell has no session in mocante, and its mocante tools refuse.

A background job may run while you are not looking at it, so mocante treats it apart from the agents in the session’s tabs:

  • An approval you gave in the session does not cover its background jobs, and an approval you give a background job does not cover the tabs. Its requests say “background job”.
  • It cannot read 1Password secrets.
  • Messages from other sessions (session_send) still go to the session’s tabs, not to the background job. A session that a background job starts does not report back to it.

Some calls wait for your approval: a call that changes the session, runs JavaScript in a page, starts a session, adds a workspace or a project, changes a setup command, or messages or stops an agent on another host. So do browser calls, if you switch on Ask before an agent drives the browser in Settings › Agents, and messages to other sessions on the same host, if you switch on Ask before an agent messages another session. Both are off by default.

mocante asks to Tools Allow for this session
control this session session_rename, session_close, server_restart yes
drive the built-in browser every browser_* tool except browser_evaluate yes
run JavaScript in the page browser_evaluate yes
message other sessions session_send, session_stop on the same host yes
message agents on other hosts session_send, session_stop to another host yes
start sessions with an agent session_create in a workspace on this host yes
start sessions with an agent on other hosts session_create in a workspace on another host yes
add projects and workspaces workspace_add on this host, project_add no
add workspaces on other hosts workspace_add on another host no
change the worktree setup command setup_command_set for a workspace on this host, or a project with no other hosts no
change the worktree setup command on other hosts setup_command_set for a workspace on another host, or a project while you have other hosts no

On a Mac, Touch ID for risky approvals in Settings › Agents also asks for your fingerprint before you allow a call that acts on another host. See settings.

The request shows as a bar at the top of the session, for example “Claude Code asks to start sessions with an agent”. Below it is what the call does, such as “type into e3, then press Enter, which can submit the form”, and then every value the agent passed, one per line: the new name, the URL, the task, the script. Nothing is shortened, so what you approve is what runs. Long details fold after three lines: click Show more to read all of it before you answer. A call too long to show, over 64 KB, is refused and the agent is told to split it. Characters that would hide or reorder text, such as a right-to-left mark, show as their code. Choose one:

  • Allow once allows this call only. The next call of the same kind asks again.
  • Allow for this session allows this call and every later call of the same kind from the agents in this session, until you revoke it. Adding a workspace or a project names a URL or a folder that you see each time, and a setup command runs in each new worktree, so those calls only offer Allow.
  • Deny fails the call, and the agent sees that you denied it.

When the session is not on screen, a desktop notification tells you about the request. A notification shortens its text, so it offers only Deny: click it to open the session and read the whole call before you allow it. The buttons show their keyboard shortcuts, ⌘⇧A, ⌘⇧S and ⌘⇧D on macOS. The command palette also has Approve permission (once), Approve permission for this session and Deny permission.

A shield with a number in the session header shows how many kinds of call you allowed for this session. Hover it to see which, and click it to revoke one, or all of them. Revoke agent approval… in the command palette does the same. After that, the next call of that kind asks again.

  • session_info, session_list, workspace_list, session_share, the review_* tools, server_list and server_logs never ask. They only read, move a file into your own window, or write in the session’s review threads.
  • An approval for the session holds until you revoke it or the session is removed. After mocante restarts, it asks again.
  • An approval for the session covers the agents in its tabs, not its background jobs. Those ask on their own.
  • A request that nobody answers in 100 seconds fails, and tells the agent to ask you to approve it in mocante and call again.
  • A call has two minutes in all. If you approve late, a slow page load gets only the time that is left, and fails with the browser’s own message.
  • A request goes away when the agent stops waiting for it, for example when you press Esc in the agent or close its session. Nothing happens then, even if you approved it at that moment.
  • With no mocante window open, there is nobody to ask, and the call fails with that reason.
  • “Rename this session to something that describes the bug.”
  • “We are done. Commit, push, and close this session.”
  • “Look at the file I have open and explain the function under the cursor.”
  • “Open the app in the browser, log in, and tell me what the console shows.”
  • “Take a screenshot of the settings page and share it with me.”
  • “Answer my review threads, and resolve the ones you fixed.”
  • “The dev server looks stuck. Check its logs and restart it.”
  • “Ask the agent in the docs session to document the new flag.”
  • “Start a session on a new branch and have it write the migration while you fix the tests here.”
  • “Check out github.com/acme/billing in the Acme project and find where invoices are rounded.”
  • Claude Code: the tools are part of the mocante plugin, so Uninstall agent hooks… in the command palette removes them together with the hooks.
  • Codex: run codex mcp remove mocante.
  • opencode: delete mcp.mocante from ~/.config/opencode/opencode.json.

Then restart the agent.