mirage acp goes in place of the agent’s command and starts the agent itself:
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
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
mirageis replaced by the workspace’s; the others stay. - A config with no
workspace_idmakes a workspace that lives as long asmirage acpdoes, as withmirage mcp.