Imported from ix-infrastructure/ix-codex-plugin (AGENTS.md). Install upstream with npx skills add ix-infrastructure/ix-codex-plugin. Copyright stays with the author.

ix-codex-plugin

This repo is the Codex plugin for Ix Memory. When working in this repo, use ix commands to navigate it just like any other codebase.

Cognitive Model

Codex + Ix operates as a three-layer system:

Ix Graph      = structured memory (code relationships, history, decisions)
Codex         = reasoning engine (infers, synthesizes, decides)
Skills/Agents = cognition layer (task abstractions over the graph)

This means Codex is not a command wrapper. Codex uses Ix as memory to reason, then synthesizes answers. The graph provides facts; Codex provides understanding.

Behavioral Rules

Always

• Use Ix graph data before reading source code
• Read at symbol level only with ix read <symbol>, never whole files unless the whole file is the explicit subject
• Use high-level skills (ix-investigate, ix-understand) not raw command dumps
• Stop early once you can answer the question
• Label evidence and distinguish graph-backed facts from inferences

Never

• Scan entire files unless the whole file is the question
• Call ix depends --depth 3+ or ix trace without a specific question
• Assume behavior without graph or code evidence
• Output raw command output
• Run ix map for exploration
• Run ix rank without both --by and --kind
• Run ix inventory without --kind — --kind is required (e.g. ix inventory --kind file --path <dir> --format llm)
• Add --path to ix callers or ix callees — these subcommands do not accept --path
• Add --limit to ix locate — this subcommand does not accept --limit

Reasoning Strategy

When answering a question about a codebase:

1. Orient       -> ix subsystems or ix overview
2. Locate       -> ix locate
3. Explain      -> ix explain
4. Trace/Depend -> ix trace or ix depends only if needed
5. Read         -> ix read <symbol> only if implementation detail is still unclear
6. Synthesize   -> answer the question, cite evidence
7. Suggest      -> one useful next step

Skip steps if earlier steps answer the question. Most questions should stop by step 3.

ix read vs Native File Reads

Decision rule: Ix is the primary memory layer. Use ix read <symbol> whenever the question is about a symbol's behavior, logic, or implementation. Native file reads are a fallback for file-structural tasks only.

Native reads are NOT allowed for:

• Answering "what does X do" (use ix read X)
• Pre-edit risk analysis (use ix impact)
• Debugging a function (use ix trace + ix read <candidate>)
• Understanding class members (use ix contains then ix read per method)
• Any task where a symbol-level read can answer the question

Good — symbol-level read:

Task: "What does AuthMiddleware.validate do?"
✓  ix read AuthMiddleware.validate --format llm     # reads the exact method
✗  Read src/middleware/auth.py                        # reads 400 lines to find one function

Bad — whole-file read for symbol analysis:

Task: "Debug why user login fails"
✗  Read src/auth/login.py                            # scans the whole file looking for the bug
✓  ix trace login --downstream --format llm          # then ix read <suspected-failure-point>

Token Budget Rules

Skill Reference

Agent Playbooks

The agents/ directory carries the same exploration and audit playbooks as the Claude plugin for parity. Codex does not currently install these as first-class local agents from .codex-plugin/plugin.json, so treat them as reusable playbook docs rather than marketplace-exposed runtime agents.

Included playbooks:

• ix-explorer
• ix-system-explorer
• ix-bug-investigator
• ix-safe-refactor-planner
• ix-architecture-auditor

Hook Notes

The Codex hook bundle mirrors the Claude plugin where Codex exposes an equivalent event:

• SessionStart injects Ix operating guidance
• UserPromptSubmit injects the Ix Pro briefing once per 10 minutes
• PreToolUse for Bash front-runs grep/rg and read-style shell commands with Ix context
• Stop runs ix map asynchronously

Current Codex limitations:

• no direct hook matcher for Grep or Glob
• no direct hook matcher for Read
• no direct hook matcher for Edit/Write pre-checks
• no direct PostToolUse mapping in this repo's current Codex hook setup

Because of that, the Codex port matches the Claude behavior as closely as the Codex runtime allows, but not event-for-event.

Repo Structure

plugins/ix-memory/
  .codex-plugin/plugin.json     - plugin manifest
  skills/
    ix-understand/SKILL.md      - mental model
    ix-investigate/SKILL.md     - symbol deep dive
    ix-impact/SKILL.md          - risk analysis
    ix-plan/SKILL.md            - change plan
    ix-debug/SKILL.md           - root cause analysis
    ix-architecture/SKILL.md    - structural health
    ix-docs/SKILL.md            - narrative-first docs

.codex/
  config.toml                   - enables Codex hooks
  hooks.json                    - hook event mapping
  hooks/
    common.py                   - shared helpers
    session_start.py            - startup guidance
    user_prompt_submit.py       - Ix Pro briefing injection
    pre_tool_use.py             - Bash search/read interception
    stop.py                     - background graph refresh

agents/
  ix-explorer.md
  ix-system-explorer.md
  ix-bug-investigator.md
  ix-safe-refactor-planner.md
  ix-architecture-auditor.md

ix CLI Quick Reference

Pass --format llm for output you read directly — compact key=value records, typically 2-4x smaller than json. Use --format json only when a tool/script machine-parses the result. Pro commands (briefing, bugs, decisions, plans, goals, …) still use --format json.

ix rank requires --by and --kind.