ix-codex-plugin

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.

What This Repo Replicates

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, or Read, or the Claude plugin manifest format. File edits are hooked through Codex's apply_patch tool.
• Because of that, the Codex port matches the Claude plugin semantically, but not event-for-event.

Requirements

• 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.

Skills

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:

Skill	What it does	Key rule
$ix-understand [target]	Build a mental model of a system or the whole repo	Graph only; no code reads
$ix-investigate <symbol>	Deep dive: what it is, how it connects, execution path	Graph first; one symbol read max
$ix-impact <target>	Change risk: blast radius, affected systems, test targets	Depth scales with risk
$ix-plan <targets...>	Risk-ordered implementation plan for a set of changes	Parallel impact; finds shared dependents
$ix-debug <symptom>	Root cause analysis from symptom to candidates	Minimal source reads at suspects only
$ix-architecture [scope]	Design health: coupling, smells, hotspots	Graph only; never reads source
`$ix-docs [--full] [--style narrative	reference	hybrid] [--split] [--single-doc] [--out ]`

Helper skills:

Skill	What it does
$ix-help <task or question>	Routes a request to the best Ix skill or raw command
$ix-tutorial [topic]	Explains how to use the plugin in Codex with copy-paste examples

How To Invoke Skills In Codex

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

Agent Playbooks

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

Playbook	Purpose
ix-explorer	General-purpose graph exploration
ix-system-explorer	Full architectural model of a codebase or region
ix-bug-investigator	Root cause analysis from symptom to candidates
ix-safe-refactor-planner	Blast radius plus safe change sequencing
ix-architecture-auditor	Structural health report with ranked improvements

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

Automatic Hooks

Trigger	Codex hook	Effect
Codex session starts	SessionStart	Injects Ix operating guidance and the graph-first rules
User sends a prompt	UserPromptSubmit	Injects ix briefing once per 10 min if Ix Pro is available
Codex runs Bash with grep/rg	PreToolUse	Front-runs with ix text plus ix locate and injects a concise summary
Codex runs Bash with read-style commands (cat, sed, head, tail, awk)	PreToolUse	Front-runs with ix inventory, ix overview, and ix impact for the target file
Codex edits files (apply_patch, or a shell redirect)	PreToolUse	Warns with ix impact when a touched file has a medium/high/critical blast radius
Codex has edited files	PostToolUse	Requests the same guarded background refresh as Stop
Codex finishes responding	Stop	Refreshes the graph in the background (ix map <root> --silent) — only for an already-mapped git repository, never $HOME, at most once per 2 minutes per repository

Unsupported Claude-only hook points today:

• Grep
• Glob
• Read

All hook text meant for the model is returned as hookSpecificOutput.additionalContext, the only channel Codex adds to the model's input.

Hook trust

Codex (0.155) runs a hook from hooks.json only after you have reviewed and trusted its exact definition. After installing or updating the hooks, start Codex interactively and accept the "Hooks need review" prompt; until then the Ix hooks are skipped. codex exec cannot ask, so it skips untrusted hooks.

Hooks are a stable, default-on Codex feature ([features] hooks) since Codex 0.124, so the installer no longer writes the old codex_hooks = true flag. That key is now a deprecated alias; you can delete it from your config.toml. On Codex older than 0.124, set codex_hooks = true under [features] yourself.

• write post-hooks in the current Codex hook bundle

Install

Quick install

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

What gets installed

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/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/post_tool_use.py
• .codex/hooks/stop.py

MCP:

• registered with Codex as ix-memory, served by the Ix CLI (ix mcp) — no file is installed

Upgrading

Re-run the same installer; no flags are needed. Over any earlier version it:

• overwrites the files the plugin owns and removes the ones it no longer ships (recorded in .codex/ix-plugin-version.json), and never touches anything else in .codex/;
• merges into an existing hooks.json: the plugin's entries from any earlier version are replaced in place, and every other hook in the file is kept;
• checks everything before writing, then swaps the new files in together — a failed install leaves the previous one exactly as it was;
• runs ix mcp install --host codex with a time limit and reports how it went. A registration of the mcp/server.py that 2.4.1 and earlier shipped is replaced (and the old file removed); any other server already named ix-memory is left alone unless you pass --force;
• removes the /tmp/ix-codex-hooks cache older hooks used, if it is yours and holds only cache files.

If hooks.json changed, Codex asks you to trust the hooks again on its next start.

--force is only for replacing what is not the plugin's: a marketplace entry named ix-memory that points elsewhere, a hooks.json that is not valid JSON, or a different ix-memory MCP server.

Home-local install

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

This writes:

• ~/.codex/plugins/ix-memory
• ~/.agents/plugins/marketplace.json
• ~/.codex/hooks.json
• ~/.codex/hooks/*.py

Repo-local install

./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/hooks.json
• /path/to/project/.codex/hooks/*.py

Symlink mode for local development

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

Help

./install.sh --help

.\install.ps1 --help

Manual Install

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

Repo marketplace

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.

Personal 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.

Hooks without the installer

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

• .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/post_tool_use.py
• .codex/hooks/stop.py

Verify active plugin version

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
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 to write the file.

Repo Guidance

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.