A Codex plugin that turns Codex into a graph-reasoning engineering agent using Ix Memory as its structured memory backend.

Codex + Ix = reasoning engine + persistent code knowledge graph. Skills are cognitive abstractions, not CLI wrappers.

This repo now mirrors the ix-claude-plugin content model as closely as Codex currently allows:

• the same seven high-level cognitive skills
• Codex-specific helper skills for routing and onboarding
• the same graph-first operating guidance
• the same agent playbooks, shipped here as reusable docs under agents/
• hook behavior that front-runs shell search/read actions with Ix context

Codex runtime limitation:

• Codex does not currently expose Claude-style hook matchers for Grep, Glob, Read, edit preflight hooks, or the Claude plugin manifest format.
• Because of that, the Codex port matches the Claude plugin semantically, but not event-for-event.

• Ix Memory installed and running (ix status returns ok)
• python3 in PATH for the installer and hook scripts
• ripgrep (rg) is recommended

Ix Pro is optional. If present, the UserPromptSubmit hook injects the Ix session briefing once per 10 minutes, matching the Claude plugin behavior.

Codex registers every skill in plugins/ix-memory/skills/. Use the $-prefixed skill name in chat, for example $ix-tutorial or $ix-understand.

Core analysis skills:

Helper skills:

Codex skill invocation uses a $-prefixed skill name. Start your prompt with the registered skill name, then add the task or target inline.

Local Codex plugins do not currently guarantee slash-command popups or /skill autocomplete for these skills, so $ix-* is the reliable primary UX.

Recommended patterns:

• $ix-help how does the auth subsystem work?
• $ix-understand this repo
• $ix-investigate IxClient
• $ix-impact Ix/ix-cli/src/client/api.ts
• $ix-plan session_start.py common.py
• $ix-debug ContextService query flow
• $ix-tutorial how do I use the ix-memory plugin in Codex?

For exact lookups, raw ix commands are still appropriate:

• Run ix locate IxClient --format llm
• Run ix callers IxClient --limit 15 --format llm

For parity with ix-claude-plugin, this repo also ships the same playbooks in agents/:

These are documentation artifacts today. Codex local plugins do not currently install them as first-class custom agents through .codex-plugin/plugin.json.

Unsupported Claude-only hook points today:

• Grep
• Glob
• Read
• edit preflight hooks
• write post-hooks in the current Codex hook bundle

curl -fsSL https://raw.githubusercontent.com/ix-infrastructure/ix-codex-plugin/main/codex-install.sh | sh

Then restart Codex and install or enable ix-memory from the ix-codex-plugin marketplace. Running the installer only copies/registers the plugin; the skills do not appear until the plugin is enabled in Codex.

PowerShell:

irm https://raw.githubusercontent.com/ix-infrastructure/ix-codex-plugin/main/codex-install.ps1 | iex

The hosted installers cache the source checkout in ~/.ix/codex-plugin-source and default to --home --plugin --hooks --mcp.

If you only want the plugin and not the hooks:

./install.sh --home --plugin

If you only want a repo-local install:

./install.sh --repo /path/to/project --plugin --hooks --mcp

If you want a fully local checkout for development or advanced flags, clone the repo and use the local wrappers:

git clone https://github.com/ix-infrastructure/ix-codex-plugin.git
cd ix-codex-plugin
./install.sh --home --plugin --hooks --mcp

Plugin:

• plugins/ix-memory/.codex-plugin/plugin.json
• plugins/ix-memory/skills/*
• .agents/plugins/marketplace.json

The plugin install step registers a marketplace entry. It does not auto-enable ix-memory; restart Codex and enable the plugin before expecting its skills to show up.

Hooks:

• .codex/config.toml
• .codex/hooks.json
• .codex/hooks/common.py
• .codex/hooks/session_start.py
• .codex/hooks/user_prompt_submit.py
• .codex/hooks/pre_tool_use.py
• .codex/hooks/stop.py

MCP:

• .codex/mcp/server.py

./install.sh --home --plugin --hooks --mcp --mode copy

This writes:

• ~/.codex/plugins/ix-memory
• ~/.agents/plugins/marketplace.json
• ~/.codex/config.toml
• ~/.codex/hooks.json
• ~/.codex/hooks/*.py
• ~/.codex/mcp/server.py

./install.sh --repo /path/to/project --plugin --hooks --mcp --mode copy

This writes:

• /path/to/project/plugins/ix-memory
• /path/to/project/.agents/plugins/marketplace.json
• /path/to/project/.codex/config.toml
• /path/to/project/.codex/hooks.json
• /path/to/project/.codex/hooks/*.py
• /path/to/project/.codex/mcp/server.py

./install.sh --repo /path/to/project --plugin --hooks --mcp --mode symlink

./install.sh --help

.\install.ps1 --help

Codex also supports manual local plugin installation through a marketplace file.

1. Copy plugins/ix-memory into <repo>/plugins/ix-memory.
2. Add or update <repo>/.agents/plugins/marketplace.json with an entry pointing to ./plugins/ix-memory.
3. Restart Codex.
4. Install ix-memory from that repo marketplace.

1. Copy plugins/ix-memory into ~/.codex/plugins/ix-memory.
2. Add or update ~/.agents/plugins/marketplace.json with source.path pointing to ./.codex/plugins/ix-memory.
3. Restart Codex.
4. Install ix-memory.

Copy these into either the repo or ~/.codex:

• .codex/config.toml
• .codex/hooks.json
• .codex/hooks/common.py
• .codex/hooks/session_start.py
• .codex/hooks/user_prompt_submit.py
• .codex/hooks/pre_tool_use.py
• .codex/hooks/stop.py

Each --hooks install writes a small metadata file at .codex/ix-plugin-version.json in the target directory. This lets you confirm exactly which build of the plugin is active.

cat .codex/ix-plugin-version.json

Example output:

{
  "plugin_name": "ix-memory",
  "plugin_version": "2.3.0",
  "source_path": "/home/you/ix-codex-plugin",
  "installed_at": "2026-04-29T18:00:00+00:00",
  "git_commit": "a1b2c3d4e5f6..."
}

At the start of every Codex session the SessionStart hook reads this file and emits a one-line header into the session context:

ix-memory plugin v2.3.0 active | installed 2026-04-29 | commit a1b2c3d

To confirm a reinstall took effect:

1. Reinstall: ./install.sh --repo /path/to/project --hooks --force
2. Check the new timestamp: cat /path/to/project/.codex/ix-plugin-version.json
3. Start a new Codex session — the version line in the session context will reflect the new install date and commit.

If the version line is missing, the hooks were installed manually without using the installer. Run ./install.sh --repo /path/to/project --hooks --force to write the file.

The repo-level operating guide lives in AGENTS.md. It carries the Claude plugin's graph-first reasoning model, skill reference, token-budget rules, and Codex-specific notes about hook/runtime differences.