Skip to main content
OpenAI Codex can load Mirage as a plugin. The plugin packages a Mirage guidance skill and six filesystem tools: read, write, edit, ls, grep, and execute_command.
Codex can work on repositories in any programming language. The Mirage tool server itself requires Node.js 20 or newer.

​
Install the plugin

Add the Mirage repository as a Codex marketplace, then install the plugin:
For local development, replace strukto-ai/mirage with the path to a Mirage checkout. Start a new Codex task after installation so the plugin tools and skill are loaded.

​
Configure a workspace

Add .mirage/workspace.yaml to the project where you start Codex:
Mirage searches the current directory and its parents for:
  • .mirage/workspace.yaml or .mirage/workspace.yml
  • workspace.yaml or workspace.yml
  • mirage.yaml or mirage.yml
Set MIRAGE_MCP_CONFIG to an absolute path when the config lives elsewhere.

​
Use the Codex UI

Open Plugins in the Codex app, or run /plugins in the Codex CLI, and confirm that Mirage is enabled. Then use the normal Codex conversation UI:
The plugin keeps Codex’s existing UI, sessions, model selection, approvals, and authentication. Mirage only supplies the filesystem tools.

​
Stale-write protection

The tool server records a content fingerprint when read returns a file. If that file changes before a later edit, the edit fails and tells Codex to read the file again. After the reread, Codex can reconsider the new content and retry. This follows the Pi integration. The current fallback hashes the returned bytes; a future Mirage revision API can replace that without changing the Codex plugin.

​
Run the server directly

The plugin launches this command automatically:
You can also embed the transport in a Node application:

​
Why MCP instead of a Pi-style extension?

Pi exposes an in-process TypeScript API for registering tools. Codex plugins can package skills and tool integrations, but Codex does not expose an equivalent registerTool API. MCP is therefore the supported custom-tool transport, kept behind a thin adapter over Mirage’s shared tool operations. If you want Codex’s built-in file tools to see Mirage paths directly, use a FUSE mount instead. FUSE has no custom tool namespace, but requires host FUSE setup and does not provide Mirage’s agent-level stale-write check.