GitKB with Codex

GitKB ships with a Codex integration that scaffolds agent-ready skills, instructions, and command shortcuts. Use it to keep Codex sessions grounded in GitKB context, code intelligence, and task traceability.

Scaffold the integration

After initializing your KB and configuring MCP, run:

git kb init codex

This generates the Codex integration into your project:

.codex/
├── skills/
│   ├── gitkb.md                 # Core KB management skill
│   ├── code-intelligence.md     # Call graph and symbol workflows
│   ├── explore.md               # Discovery workflows
│   ├── understand.md            # File/symbol understanding
│   └── refactor-safety.md       # Blast radius checks
├── instructions/
│   ├── codex-rules.md           # GitKB-first workflow and discipline
│   └── gitkb-process.md         # Session start/work/completion guidance
└── commands/
    ├── kb-start.md              # Start working on a task
    ├── kb-context.md            # Load project context
    ├── kb-commit.md             # Commit KB changes
    └── kb-status.md             # Show workspace status

Preview what would be generated without writing anything:

git kb init codex --dry-run

Install into CODEX_HOME

By default, git kb init codex only creates repo-local .codex/. To install the assets into your global Codex home directory, run:

git kb init codex --install-home

This installs into $CODEX_HOME when set, or ~/.codex by default.

What the instructions teach Codex

The scaffolded instructions in .codex/instructions/ set the workflow expectations:

• GitKB-first — start with git kb context and keep progress logged in task docs.
• Code intelligence — prefer git kb code tools (or MCP equivalents) over grep.
• Task traceability — scope commits to task docs and include task references.

Example workflow

A typical Codex session with GitKB:

git kb context --compact --code-refs
git kb board
git kb checkout tasks/example-task
git kb code callers src/app.ts::handler
git kb commit -m "Update task progress [[tasks/example-task]]" tasks/example-task

Next steps

• Claude Code — Full Claude integration (rules, skills, slash commands)
• Code Intelligence — Call graph and symbol workflows
• CLI Reference — Full command reference including init codex