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)

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 (Function) -- src/routes/checkout.py

Symbols removed (1):
  - old_charge (Function) -- src/payments/legacy.py

Clean call graphs

Noise Filtering

Built-in blocklist (138 entries) automatically filters language builtins (print, len, isinstance), JS/TS globals (console, setTimeout, fetch), React hooks (useState, useEffect), and common stdlib methods from the call graph. Your graph shows your code's relationships, not noise from list.append().

The Pipeline

Axon builds deep structural understanding through 12 sequential analysis phases:

MCP Integration

Axon exposes its full intelligence as an MCP server. Set it up once, and your AI agent has structural understanding of your codebase forever.

Setup

Claude Code — add to .mcp.json in your project root (or run claude mcp add axon -- axon serve --watch):

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

Cursor — add to your MCP settings:

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

Optional new feature:

axon host --watch

This starts a shared host for the UI and multiple MCP clients. axon setup --claude / axon setup --cursor still prints the standard config.

The --watch flag enables live re-indexing — the graph updates as you edit code.

Tools

Every tool response includes a next-step hint guiding the agent through a natural investigation workflow:

query   -> "Next: Use context() on a specific symbol for the full picture."
context -> "Next: Use impact() if planning changes to this symbol."
impact  -> "Tip: Review each affected symbol before making changes."

Resources

API Endpoints

The web UI is backed by a FastAPI server. All endpoints are under /api:

Cypher queries are validated server-side — write keywords (CREATE, DELETE, DROP, etc.) are rejected after comment stripping.

How It Compares

Supported Languages

Installation

# With pip
pip install axoniq

# With uv (recommended)
uv add axoniq

# With Neo4j backend support
pip install axoniq[neo4j]

Requires Python 3.11+. The web UI (frontend + backend) is included — no Node.js or extra install needed.

From Source

git clone https://github.com/harshkedia177/axon.git
cd axon
uv sync --all-extras
uv run axon --help

To rebuild the frontend after making changes (requires Node.js 18+):

cd src/axon/web/frontend
npm install && npm run build

CLI Reference

axon analyze [PATH]          Index a repository (default: current directory)
    --full                   Force full rebuild (skip incremental)
    --no-embeddings          Skip vector embedding generation (faster indexing)

axon status                  Show index status for current repo
axon list                    List all indexed repositories (auto-populated on analyze)
axon clean                   Delete index for current repo
    --force / -f             Skip confirmation prompt

axon query QUERY             Hybrid search the knowledge graph
    --limit / -n N           Max results (default: 20)

axon context SYMBOL          360-degree view of a symbol
axon impact SYMBOL           Blast radius analysis
    --depth / -d N           BFS traversal depth (default: 3)

axon dead-code               List all detected dead code
axon cypher QUERY            Execute a raw Cypher query (read-only)

axon watch                   Watch mode — live re-indexing on file changes
axon diff BASE..HEAD         Structural branch comparison

axon host                    Shared host for UI + HTTP MCP (default: localhost:8420)
    --port / -p PORT         Port to serve on (default: 8420)
    --watch / --no-watch     Enable live file watching
    --dev                    Dev mode — proxy to Vite dev server for HMR
    --no-open                Don't auto-open browser

axon ui                      Launch the web UI (default: localhost:8420)
    --port / -p PORT         Port to serve on (default: 8420)
    --watch / -w             Enable live file watching with auto-reindex
    --dev                    Dev mode — proxy to Vite dev server for HMR
    --no-open                Don't auto-open browser
    --direct                 Force standalone mode even if a shared host exists

axon setup                   Print MCP configuration JSON
    --claude                 For Claude Code
    --cursor                 For Cursor

axon mcp                     Start the MCP server (stdio transport)
axon serve                   Start the MCP server
    --watch, -w              Enable live file watching with auto-reindex
axon --version               Print version

Example Workflows

"I need to refactor the User class — what breaks?"

# See everything connected to User
axon context User

# Check blast radius — grouped by depth
axon impact User --depth 3

# Find files that always change with user.py
axon cypher "MATCH (a:File)-[r:CodeRelation]->(b:File) WHERE a.name = 'user.py' AND r.rel_type = 'coupled_with' RETURN b.name, r.strength ORDER BY r.strength DESC"

"Is there dead code we should clean up?"

axon dead-code

"What are the main execution flows?"

axon cypher "MATCH (p:Process) RETURN p.name, p.properties ORDER BY p.name"

"Which parts of the codebase are most tightly coupled?"

axon cypher "MATCH (a:File)-[r:CodeRelation]->(b:File) WHERE r.rel_type = 'coupled_with' RETURN a.name, b.name, r.strength ORDER BY r.strength DESC LIMIT 20"

Knowledge Graph Model

Nodes

Relationships

Node ID Format

{label}:{relative_path}:{symbol_name}

Examples:
  function:src/auth/validate.py:validate_user
  class:src/models/user.py:User
  method:src/models/user.py:User.save

Architecture

Source Code (.py, .ts, .js, .tsx, .jsx)
    |
    v
+----------------------------------------------+
|         Ingestion Pipeline (12 phases)        |
|                                               |
|  walk -> structure -> parse -> imports        |
|  -> calls -> heritage -> types                |
|  -> communities -> processes -> dead_code     |
|  -> coupling -> embeddings                    |
+----------------------+-----------------------+
                       |
                       v
              +-----------------+
              | KnowledgeGraph  |  (in-memory during build)
              +--------+--------+
                       |
          +------------+------------+
          v            v            v
     +---------+ +---------+ +---------+
     | KuzuDB  | |  FTS    | | Vector  |
     | (graph) | | (BM25)  | | (HNSW)  |
     +----+----+ +----+----+ +----+----+
          +------------+------------+
                       |
              StorageBackend Protocol
                       |
           +-----------+-----------+
           v           v           v
     +----------+ +----------+ +----------+
     |   MCP    | |  Web UI  | |   CLI    |
     |  Server  | | (FastAPI | | (Typer)  |
     | (stdio)  | |  + React)| |          |
     +----+-----+ +----+-----+ +----+-----+
          |             |            |
     Claude Code    Browser      Terminal
     / Cursor      (developer)  (developer)

Tech Stack

Storage

Everything lives locally:

your-project/
+-- .axon/
    +-- kuzu/          # KuzuDB graph database (graph + FTS + vectors)
    +-- meta.json      # Index metadata and stats

Add .axon/ to your .gitignore.

A global registry at ~/.axon/repos/ is automatically populated on axon analyze, enabling axon list to discover all indexed repositories across your machine.

The storage layer is abstracted behind a StorageBackend Protocol — KuzuDB is the default, with an optional Neo4j backend available via pip install axoniq[neo4j].

Development

git clone https://github.com/harshkedia177/axon.git
cd axon
uv sync --all-extras

# Run tests
uv run pytest

# Lint
uv run ruff check src/

# Run from source
uv run axon --help

# Frontend development (React + Vite with HMR)
cd src/axon/web/frontend
npm install
npm run dev                  # Vite dev server on :5173
# In another terminal:
uv run axon ui --dev         # Backend on :8420, proxies to Vite

License

MIT

Read the case study → — the design decisions, the trade-offs, and what broke along the way.

Built by Harsh Kedia.