Axon

Root-cause debugging & vulnerability MCP server and CLI for AI coding agents.

Axon traces a fault signal back to its source — like the axon that carries a neuron's signal. It gives an agent the tools to localize bugs, verify fixes, and find security vulnerabilities with high precision.

Companion to Cortex. Cortex is the context/graph brain; Axon is the debugging + security tracer. Cortex is optional — Axon runs fully standalone.

Current release facts (2026-07-09 docs refresh): package/plugin version 0.5.11; published distribution name axon-debug; executable name axon.

Why Axon

Research shows no agent hits "90% detect everything" universally. Axon reaches ≥90% on a defined slice by stacking four proven levers:

1. Context grounding — code graph + retrieval, built-in (no external deps).

2. Executable verification — reproduce → fix → confirm FAIL→PASS.

3. Adversarial triage — a refuter agent must disprove each finding → kills false positives (the security adoption killer).

4. Static-analysis grounding — SAST output the agent filters/confirms.

Related MCP server: yo-bug

Plug-and-play by design

• Zero-config. Install → run. Nothing else needed.

• No GPU, no model download, no daemon. Retrieval defaults to BM25 + ripgrep.

• Dependency-light startup. Plugin startup uses bin/axon-mcp.py, which imports axon.mcp_stdio directly; no plugin-local pip install or venv bootstrap is required.

• Optional accelerators, auto-detected, never required:

  • Cortex → richer code graph/impact. Preferred transport is Cortex's MCP server (cortex mcp; override with AXON_CORTEX_MCP_CMD, set it to off to force the CLI), which reuses Cortex's persistent per-repo index. Falls back to the cortex CLI (per-call budgets tunable via AXON_CORTEX_INGEST_TIMEOUT / _BUNDLE_TIMEOUT / _GRAPH_TIMEOUT), then to the built-in provider — logging why it degraded.

  • mcp extra → FastMCP-based server path when you want it.

  • semgrep extra → Semgrep-backed SAST when you want it.

• Same agent tools and output shape on every rung. Accelerators only improve quality/speed; their absence never breaks a feature.

Tools (MCP)

axon serve exposes Axon's MCP registry over stdio, including index, graph_context, search, status, localize, run_tests, repro, verify_fix, rank_patches, spectrum, inspect, investigate, sast_scan, refute, and triage.

Quickstart

pip install -e .      # or: uvx axon-debug
axon --help           # current subcommands: serve, index, doctor, gc
axon doctor           # environment + active backend
axon index <repo>     # build/refresh the code index
axon serve            # start the MCP server (stdio)

Point any MCP host (Claude Code, etc.) at axon serve. Runs with no Cortex, no GPU, no model download.

Install as a Claude Code plugin

Inside an interactive Claude Code session, use slash commands:

/plugin marketplace add "/path/to/Axon"
/plugin install axon@axon

From a shell, use the Claude Code CLI equivalents:

claude plugin marketplace add "/path/to/Axon"
claude plugin install axon@axon

You can substitute the Git remote if you prefer not to use the local clone path: https://github.com/alilfrances/Axon.git

Install as a Codex plugin

codex plugin marketplace add "/path/to/Axon"
codex plugin add axon@axon

Codex can use the same Git remote source instead of the local path: https://github.com/alilfrances/Axon.git

Official command references: Codex plugin marketplace CLI, Codex plugin install flow, and Claude Code plugin marketplaces.

Start a new Claude Code or Codex session after installation so the plugin MCP server and hooks are loaded.

Plugin startup needs python3 and does not run pip or create a venv. bin/axon-mcp.py loads the dependency-free axon.mcp_stdio adapter directly. Semgrep-backed SAST is optional: install semgrep on PATH to enable it. Codex installs plugins into its local plugin cache; after updating Axon, run codex plugin marketplace upgrade axon and restart Codex so the MCP server is loaded from the refreshed cache.

Versioning: Axon uses semver; bump pyproject.toml, src/axon/__init__.py, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and .codex-plugin/plugin.json together on release.

Status

Current package/plugin version is 0.5.11. The repository's pytest suite now contains 115 test functions. Older v0.3 / 60 tests statements are retained only in dated planning or verification records.

See docs/VERIFICATION.md for the dated verification log and docs/PLAN.md for the original planning document.

v0.3 debugging upgrades — function-level localization, runtime-state inspection, patch ranking, and one-call investigate bundles add deterministic evidence for root-cause debugging workflows. Measured on the django/sympy SWE-bench Verified slice (n=8, no LLM, no regression from v0.2): File@3 50%, File@10 75%, Function@10 12% (new deterministic-only baseline — the calling agent is the reranking layer).

Security

Report vulnerabilities privately through the process in SECURITY.md. Public repository hardening requirements are tracked in docs/GITHUB_SECURITY.md.