Documentation

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.

Prerequisites

OpenAI Codex CLI
Node.js 20 or later
A Crosmos API key from the Crosmos Console
Access to at least one Crosmos memory space

Keys use the csk_ prefix.

Install

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:

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.

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.

[sandbox_workspace_write]
network_access = true

Authentication

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

Verify

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

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

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

export CROSMOS_DEBUG=true
tail -f ~/.crosmos/codex.log

Uninstall

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

MCP

Connect Crosmos memory tools to AI clients when you need callable tools.

Memory tools

See the callable memory tool schemas.

GitHub repository

Browse the source code, releases, and issues.

​Prerequisites

​Install

​Authentication

​Verify

​How it works

​Commands

​What gets installed

​Configuration

​Troubleshooting

​Check the connection

​Hooks are not running

​Enable diagnostics

​Uninstall

​Next steps

MCP