Skip to main content
The Agent Client Protocol is how an app such as Zed, a JetBrains IDE or t3code drives a coding agent: the app starts the agent and the two talk JSON-RPC over the agent’s stdin and stdout. mirage acp goes in place of the agent’s command and starts the agent itself:
ACP carries the conversation: prompts, replies, tool calls and permission requests, which pass through unchanged. The agent reaches the workspace two ways underneath: Claude never asks the client for files, and its built-in tools are turned off, so it works over MCP alone. Gemini CLI writes and edits files through the client, but reads them and runs commands with its own tools. The agent runs where the client starts it and nothing is uploaded, so no machine is needed. A workspace on a hosted server works the same way, reached with the CLI’s login.

Clients

Agents

Only Claude’s own tools are turned off. Another agent’s own tools work on the computer it runs on, beside the workspace’s tools; turn them off in the agent’s settings to keep it to the workspace, such as tools.exclude for Gemini CLI or permission for OpenCode.

Set up

1

Install the CLI

2

Create the workspace

workspace.yaml
3

Install the agent

Install the agent’s ACP command from the agents table, such as Claude’s:
4

Add the agent to the client

Give the full path of mirage when the client does not start it from a shell that has it on its PATH.

Example

Fix a bug in a workspace file from Zed, with Claude.
1

Put a file in the workspace

2

Ask in Zed

Open any folder, start a Claude on Mirage thread from the set up above, and ask:
Claude reads the file with the workspace’s read tool and changes it with edit. The folder open in Zed stays as it was.
3

Check the workspace

Options

An agent asks for a file by its absolute path on the client. A path inside the session’s folder lands under --root; any other absolute path is read as a workspace path. Put -- before the agent’s command so its options stay its own. The exit status is the agent’s, and 127 when there is no such command.

How it behaves

  • A request the agent makes of the client, other than a file read or write, reaches the client unchanged, as does everything the client sends.
  • An MCP server of the client’s named mirage is replaced by the workspace’s; the others stay.
  • A config with no workspace_id makes a workspace that lives as long as mirage acp does, as with mirage mcp.