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

# Codex

> Add automatic, persistent context to the OpenAI Codex CLI.

The Crosmos Codex plugin adds persistent project context to the OpenAI Codex CLI. It recalls relevant context before each prompt and captures completed exchanges after the assistant finishes a turn through Codex lifecycle hooks.

MCP is optional. Use it when you need callable Crosmos memory tools in another MCP client. See the [MCP overview](/mcp/overview).

## Prerequisites

* OpenAI Codex CLI
* Node.js 20 or later
* A Crosmos API key from the [Crosmos Console](https://console.crosmos.dev)
* Access to at least one Crosmos memory space

Keys use the `csk_` prefix.

## Install

```bash theme={null}
npx @crosmos/codex install
```

The installer asks for your API key and lets you select a memory space. Existing verified credentials are reused when available.

You can select a space explicitly:

```bash theme={null}
export CROSMOS_API_KEY="csk_..."
npx @crosmos/codex install --space "<space-id>"
```

The installer can also install these optional Codex skills:

* `$crosmos-status`
* `$crosmos-recall`
* `$crosmos-save`

Restart Codex after installation. If the hooks are not active, open Codex and approve or enable the registered Crosmos hooks when prompted.

<Warning>
  Codex's default `workspace-write` sandbox can block outbound API requests from automatic hooks and installed skills. Enable network access in `~/.codex/config.toml`, then restart Codex. See the [Codex advanced configuration](https://learn.chatgpt.com/docs/config-file/config-advanced).

  ```toml theme={null}
  [sandbox_workspace_write]
  network_access = true
  ```
</Warning>

## Authentication

The installer stores verified credentials and the selected memory space in `~/.crosmos/credentials.json`. Set `CROSMOS_API_KEY` to override saved credentials.

## Verify

```bash theme={null}
npx @crosmos/codex status
```

The status command checks the API connection, selected memory space, hook runtime, hook registration, and managed skills.

If recall or capture is not running after a successful install, inspect the hooks in Codex and confirm that they are approved.

## How it works

The plugin uses Codex lifecycle hooks and the Crosmos SDK. Memory failures do not block your Codex session.

| Hook | When it runs | What it does |
| - | - | - |
| `UserPromptSubmit` | Before each prompt | Searches Crosmos and injects relevant memories into the turn. |
| `Stop` | After the assistant completes a turn | Captures the completed exchange in the selected memory space. |
| `PreCompact` | Before compaction | Deferred from v1; pending-memory recovery is not implemented. |

Use the optional skills when you want direct control:

* `$crosmos-status` — check Crosmos configuration and connectivity.
* `$crosmos-recall` — search selected-space memory on demand.
* `$crosmos-save` — submit one private memory for ingestion.

Automatic recall still runs before every prompt, and automatic capture runs after completed turns.

## Commands

```bash theme={null}
npx @crosmos/codex install
npx @crosmos/codex install --space "<space-id>"
npx @crosmos/codex login
npx @crosmos/codex status
npx @crosmos/codex recall "<query>"
npx @crosmos/codex save "<text>"
npx @crosmos/codex --help
npx @crosmos/codex --version
npx @crosmos/codex uninstall
```

## What gets installed

| Path | Purpose |
| - | - |
| `$CODEX_HOME/hooks.json` | Registers the Crosmos Codex hooks. Existing unrelated hook entries are preserved. |
| `$CODEX_HOME/crosmos/` | Managed hook runtime files. |
| `~/.agents/skills/crosmos-*` | Optional skills managed by Crosmos. |
| `~/.crosmos/credentials.json` | Local API credentials and selected memory space. |
| `~/.crosmos/codex.log` | Sanitized hook diagnostics when `CROSMOS_DEBUG` is enabled. |

## Configuration

Environment variables override saved credentials where applicable.

| Variable | Description |
| - | - |
| `CROSMOS_API_KEY` | API key used for authentication. |
| `CROSMOS_API_URL` | Optional Crosmos API URL. When omitted, the SDK supplies its default. |
| `CROSMOS_DEBUG` | Set to `true`, `1`, `yes`, or `on` to enable sanitized hook diagnostics. Disabled by default. |

## Troubleshooting

### Check the connection

```bash theme={null}
npx @crosmos/codex status
```

If authentication or the selected space is unavailable, run installation again with a valid API key and, when needed, `--space <space-id>`.

### Hooks are not running

Restart Codex, then inspect its hook controls and approve or enable the Crosmos registrations. Confirm that `status` reports the runtime and `hooks.json` as installed.

### Enable diagnostics

```bash theme={null}
export CROSMOS_DEBUG=true
tail -f ~/.crosmos/codex.log
```

## Uninstall

```bash theme={null}
npx @crosmos/codex uninstall
```

Uninstall removes the Crosmos hook registrations, managed runtime files, and managed skills. It preserves your credentials and remote memories.

## Next steps

<CardGroup cols={2}>
  <Card title="MCP" icon="puzzle-piece" href="/mcp/overview">
    Connect Crosmos memory tools to AI clients when you need callable tools.
  </Card>

  <Card title="Memory tools" icon="list-check" href="/mcp/tools">
    See the callable memory tool schemas.
  </Card>

  <Card title="GitHub repository" icon="github" href="https://github.com/crosmos-labs/codex-crosmos">
    Browse the source code, releases, and issues.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.