<p align="center"> <img src="https://raw.githubusercontent.com/harshkedia177/axon/main/axon-logo.png" alt="Axon logo" width="420" /> </p>

Axon

The knowledge graph for your codebase — explore it visually, or let your AI agent query it.

Indexes any codebase into a structural knowledge graph — every dependency, call chain, cluster, and execution flow. Explore it through an interactive web dashboard with force-directed graph visualization, or expose it through MCP tools so AI agents get full structural understanding in every tool call.

$ axon analyze .

Walking files...               142 files found
Parsing code...                142/142
Tracing calls...               847 calls resolved
Analyzing types...             234 type relationships
Detecting communities...       8 clusters found
Detecting execution flows...   34 processes found
Finding dead code...           12 unreachable symbols
Analyzing git history...       18 coupled file pairs
Generating embeddings...       623 vectors stored

Done in 4.2s — 623 symbols, 1,847 edges, 8 clusters, 34 flows

Then explore your codebase visually:

axon ui                      # Opens interactive dashboard at localhost:8420

Three views, one command:

• Explorer — Interactive force-directed graph (Sigma.js + WebGL). Click any node to see its code, callers, callees, impact radius, and community. Community hull overlays show architectural clusters at a glance.
• Analysis — Health score, coupling heatmap, dead code report, inheritance tree, branch diff — your codebase health in one dashboard.
• Cypher Console — Write and run Cypher queries against the graph with syntax highlighting, presets, and history.

Plus: command palette (Cmd+K), keyboard shortcuts, flow trace animations, graph minimap, and SSE-powered live reload when watch mode is active.

---

The Problem

Your AI agent edits UserService.validate(). It doesn't know that 47 functions depend on that return type, 3 execution flows pass through it, and payment_handler.py changes alongside it 80% of the time.

Breaking changes ship.

This happens because AI agents work with flat text. They grep for callers, miss indirect ones, and have no understanding of how code is connected. Context windows are finite. LSPs don't expose call graphs. Grepping gives you strings, not structure.

The agent needs a knowledge graph — not more text.

---

How Axon Solves It

Most code intelligence tools give the agent raw files and hope it reads enough. Axon takes a different approach: precompute structure at index time so every tool call returns complete, actionable context.

A 12-phase pipeline runs once over your repo. After that:

• axon_impact("validate") returns all 47 affected symbols, grouped by depth (will break / may break / review), with confidence scores — in a single call
• axon_query("auth handler") returns hybrid-ranked results grouped by execution flow, not a flat list of name matches
• axon_context("UserService") returns callers, callees, type references, community membership, and dead code status — the full picture

Three benefits:

1. Reliability — the context is already in the tool response. No multi-step exploration that can miss code.
2. Token efficiency — one tool call instead of a 10-query search chain. Agents spend tokens on reasoning, not navigation.
3. Model democratization — even smaller models get full architectural clarity because the tools do the heavy lifting.

Zero cloud dependencies. Everything runs locally — parsing, graph storage, embeddings, search. No API keys, no data leaving your machine.

---

TL;DR

pip install axoniq            # 1. Install
cd your-project && axon analyze .  # 2. Index (one command, ~5s for most repos)
axon ui                       # 3. Explore visually at localhost:8420

For AI agents — add to .mcp.json in your project root:

{
  "mcpServers": {
    "axon": {
      "command": "axon",
      "args": ["serve", "--watch"]
    }
  }
}

For developers — explore the graph yourself:

axon ui                      # Interactive dashboard (standalone or attaches to running host)
axon ui --watch              # Live reload on file changes
axon host --watch            # Shared host: UI + multi-session MCP

---

What You Get

Explore your codebase visually

Web UI

A full interactive dashboard — no terminal or extensions required. One command:

axon ui                           # Launch at localhost:8420
axon ui --watch                   # Live reload on file changes
axon ui --port 9000               # Custom port
axon ui --dev                     # Dev mode (Vite HMR on :5173)

| View | What It Shows | |------|--------------| | Explorer | Interactive force-directed graph (Sigma.js + WebGL), file tree sidebar, symbol detail panel with code preview, callers/callees, impact analysis, and process memberships. Community hull overlays reveal architectural clusters. | | Analysis | Health score, coupling heatmap, dead code report, inheritance tree visualization, branch diff, and aggregate stats — your codebase health at a glance. | | Cypher Console | Query editor with syntax highlighting, preset query library, results table, and query history. |

Extras: Command palette (Cmd+K), keyboard shortcuts, graph minimap, flow trace and impact ripple animations, SSE-powered live reload when watch mode is enabled.

The UI is backed by a FastAPI server with a full REST API — see API Endpoints below.

Find anything — by name, concept, or typo

Hybrid Search (BM25 + Vector + Fuzzy)

Three search strategies fused with Reciprocal Rank Fusion:

• BM25 full-text search — fast exact name and keyword matching via KuzuDB FTS
• Semantic vector search — conceptual queries via 384-dim embeddings (BAAI/bge-small-en-v1.5)
• Fuzzy name search — Levenshtein fallback for typos and partial matches

Results are ranked with test file down-ranking (0.5x) and source function/class boosting (1.2x), then grouped by execution flow so the agent sees architectural context in a single call.

Know what breaks before you change it

Impact Analysis with Depth Grouping

When you're about to change a symbol, Axon traces upstream through the call graph, type references, and git coupling history. Results are grouped by depth for actionability:

• Depth 1 — Direct callers (will break)
• Depth 2 — Indirect callers (may break)
• Depth 3+ — Transitive (review)

Every edge carries a confidence score (1.0 = exact match, 0.8 = receiver method, 0.5 = fuzzy) so you can prioritize what to review.

Find what to delete

Dead Code Detection

Not just "zero callers" — a multi-pass analysis that understands your framework:

1. Initial scan — flags symbols with no incoming calls
2. Exemptions — entry points, exports, constructors, test code, dunder methods, __init__.py symbols, decorated functions, @property methods
3. Override pass — un-flags methods overriding non-dead base class methods
4. Protocol conformance — un-flags methods on Protocol-conforming classes
5. Protocol stubs — un-flags all methods on Protocol classes (interface contracts)

Understand how code runs, not just where it sits

Execution Flow Tracing

Detects entry points using framework-aware patterns:

• Python: @app.route, @router.get, @click.command, test_* functions, __main__ blocks
• JavaScript/TypeScript: Express handlers, exported functions, handler/middleware patterns

Then traces BFS execution flows from each entry point through the call graph, classifying flows as intra-community or cross-community.

See your architecture without reading docs

Community Detection

Uses the Leiden algorithm (igraph + leidenalg) to automatically discover functional clusters. Each community gets a cohesion score and auto-generated label. Agents can ask "what cluster does this symbol belong to?" and get the answer without reading a single design doc.

Find hidden dependencies git knows about

Change Coupling (Git History)

Analyzes 6 months of git history to find dependencies that static analysis misses:

coupling(A, B) = co_changes(A, B) / max(changes(A), changes(B))

Files with coupling strength >= 0.3 and 3+ co-changes get linked. These show up in impact analysis — so when you change user.py, the agent also knows to check user_test.py and auth_middleware.py.

Always up to date

Watch Mode

Live re-indexing powered by a Rust-based file watcher (watchfiles):

$ axon watch
Watching /Users/you/project for changes...

[10:32:15] src/auth/validate.py modified -> re-indexed (0.3s)
[10:33:02] 2 files modified -> re-indexed (0.5s)

File-local phases (parse, imports, calls, types) run immediately on change. Global phases (communities, processes, dead code) batch every 30 seconds.

Structural diff, not text diff

Branch Comparison

Compare branches at the symbol level using git worktrees (no stashing required):

$ axon diff main..feature

Symbols added (4):
  + process_payment (Function) -- src/payments/stripe.py
  + PaymentIntent (Class) -- src/payments/models.py

Symbols modified (2):
  ~ checkout_handler (Functi