> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Codex

> Install Mirage as a Codex plugin and use mounted data from the Codex CLI or app.

[OpenAI Codex](https://github.com/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`.

<Note>
  Codex can work on repositories in any programming language. The Mirage tool
  server itself requires Node.js 20 or newer.
</Note>

## Install the plugin

Add the Mirage repository as a Codex marketplace, then install the plugin:

```bash theme={null}
codex plugin marketplace add strukto-ai/mirage
codex plugin add mirage@mirage
```

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:

```yaml theme={null}
mounts:
  /scratch:
    resource: ram
  /data:
    resource: disk
    config:
      root: ${PWD}/data
```

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:

```text theme={null}
List the files mounted in Mirage.
Read /data/report.csv and summarize it.
Create /scratch/notes.txt with the findings.
```

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](/typescript/agents/pi). 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:

```bash theme={null}
npx -y @struktoai/mirage-cli mcp
```

You can also embed the transport in a Node application:

```ts theme={null}
import { createMirageMcpServer } from '@struktoai/mirage-agents/mcp'

const server = createMirageMcpServer(workspace)
```

## 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](/typescript/setup/fuse) instead. FUSE has no custom tool namespace, but requires host FUSE setup and does not provide Mirage's agent-level stale-write check.