GitKB Codex Plugin

This repository is the authoritative source for the GitKB Codex plugin payload and its package/MCP regression tests. The gitkb/codex-plugins marketplace references ./plugin here through a Git-backed source; it does not maintain a plugin copy. Plugin behavior changes belong in this repository. Catalog release promotion only updates the marketplace's approved commit selector.

GitKB gives Codex local code intelligence first: symbols, callers, callees, impact analysis, dead-code detection, semantic search, and service-edge queries through the git-kb CLI and MCP tools. Full GitKB setup adds the persistent knowledge graph for tasks, specs, decisions, architecture, and team sync.

The user-facing plugin README lives at plugin/README.md.

Repository Layout

.agents/plugins/marketplace.json      # Repo-level Codex marketplace manifest
plugin/                               # Installable Codex plugin payload
plugin/.codex-plugin/plugin.json      # Plugin manifest
plugin/hooks/hooks.json               # Codex hook registration
plugin/.mcp.json                      # GitKB MCP server registration
plugin/skills/                        # Minimal bootstrap skill
tests/                                # Packaging and policy checks
Makefile                              # Local validation and release checks

Design Policy

This plugin is a thin marketplace and bootstrap wrapper. It should not become a second copy of GitKB's canonical Codex integration.

• Keep first value CLI-backed through git-kb code ....
• Delegate hooks to git-kb hook codex.
• Keep legacy harness behavior out of the plugin identity and behavior.
• Do not vendor the full .kb/skills set generated by git-kb init codex.
• Do not add broad command files that duplicate canonical GitKB workflows.
• Guide full setup through git-kb init && git-kb init codex.

Prerequisites

Local development uses:

• git-kb
• jq
• Codex CLI

Development

Run the normal local checks:

make lint
make test

Run the complete release gate:

make release-check

Manual Install Testing

From this repository, add and install the local marketplace:

codex plugin marketplace add .
codex plugin add gitkb@gitkb

Then open a normal Git repository in Codex and ask a code intelligence question, such as:

• "What calls authenticate()?"
• "Find likely dead code."
• "What's the blast radius of changing this file?"

The plugin should guide Codex toward git-kb code ... commands and MCP tools without requiring any external harness.

Release Readiness

Before any public release or marketplace submission:

make release-check

Keep this repository private while iterating. Flip visibility or mirror to a public repository only after human review confirms the package contains no proprietary code, internal-only URLs, credentials, or unreleased product details. The root .agents/plugins/marketplace.json points Codex at the installable plugin under ./plugin.

Versioning

The plugin version is declared in:

• plugin/.codex-plugin/plugin.json

Keep the marketplace and plugin docs aligned when preparing a release.

MCP Launch Regression Tests

make test checks the packaged environment allowlist and cache version, and runs negative controls for cache symlinks, special files, executable modes, receipt path escapes, optimized Python, protocol failures, output limits, and process cleanup. Python 3.11 or newer is required for these test tools. The installation test exercises the actual Codex MCP launch boundary with synthetic sessions, custom registry settings, paths with spaces and Unicode, and credential canaries. It reuses an isolated plugin installation across two sessions and a launch without activity context. A second isolated run first installs a bundled 0.1.0 fixture, reproduces its missing context, then upgrades the same gitkb@gitkb installation and repeats those checks. The harness bounds protocol buffers and diagnostic reads, and terminates its own app-server process group. It does not start a model turn or run an activity sink, and it does not use your Codex home or credentials.

make test-integration CODEX_TEST_BINARY=/absolute/path/to/provider/codex

Pass the provider binary, rather than an ATC shim. CI runs this test with Codex 0.159.2, in addition to the release checks.