axoniq 0.2.3

Graph-powered code intelligence engine — indexes codebases into a knowledge graph, exposed via MCP tools for AI agents and a CLI for developers.

Axon

Building the knowledge graph for AI code agents.

Indexes any codebase into a structural knowledge graph — every dependency, call chain, cluster, and execution flow — then exposes it through smart MCP tools so AI agents never miss code.

$ 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

---

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)

Then add to .mcp.json or .claude/settings.json:

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

Your AI agent now has full structural understanding of your codebase. The knowledge graph updates live as you edit.

---

What You Get

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:

Phase	What It Does
File Walking	Walks repo respecting .gitignore, filters by supported languages
Structure	Creates File/Folder hierarchy with CONTAINS relationships
Parsing	tree-sitter AST extraction — functions, classes, methods, interfaces, enums, type aliases
Import Resolution	Resolves import statements to actual files (relative, absolute, bare specifiers)
Call Tracing	Maps function calls with confidence scores. Noise filtering skips 138 language builtins
Heritage	Tracks class inheritance (EXTENDS) and interface implementation (IMPLEMENTS)
Type Analysis	Extracts type references from parameters, return types, and variable annotations
Community Detection	Leiden algorithm clusters related symbols into functional communities
Process Detection	Framework-aware entry point detection + BFS flow tracing
Dead Code Detection	Multi-pass analysis with override, protocol, and decorator awareness
Change Coupling	Git history analysis — finds files that always change together
Embeddings	384-dim vectors for every symbol, enabling semantic search. Skip with --no-embeddings

---

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 or .claude/settings.json:

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

Cursor — add to your MCP settings:

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

Or run axon setup --claude / axon setup --cursor to generate the config.

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

Tools

Tool	What the agent gets
axon_query	Hybrid search (BM25 + vector + fuzzy) with results grouped by execution flow
axon_context	360-degree view — callers, callees, type refs, confidence tags, dead code status
axon_impact	Blast radius grouped by depth — direct (will break), indirect (may break), transitive
axon_dead_code	All unreachable symbols grouped by file
axon_detect_changes	Map a git diff to affected symbols and execution flows
axon_list_repos	All indexed repositories with stats
axon_cypher	Read-only Cypher queries against the knowledge graph

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

URI	Description
axon://overview	Node and relationship counts by type
axon://dead-code	Full dead code report
axon://schema	Graph schema reference for Cypher queries

---

How It Compares

Capability	grep / ripgrep	LSP	Context window stuffing	Axon
Text search	Yes	No	Yes	Yes (hybrid BM25 + vector)
Find all callers	No	Partial	Hit-or-miss	Yes (full call graph with confidence)
Type relationships	No	Yes	No	Yes (param/return/variable roles)
Dead code detection	No	No	No	Yes (multi-pass, framework-aware)
Execution flow tracing	No	No	No	Yes (entry point -> flow)
Community detection	No	No	No	Yes (Leiden algorithm)
Change coupling (git)	No	No	No	Yes (6-month co-change analysis)
Impact analysis	No	No	No	Yes (depth-grouped with confidence)
AI agent integration	No	Partial	N/A	Yes (full MCP server)
Structural branch diff	No	No	No	Yes (node/edge level)
Watch mode	No	Yes	No	Yes (Rust-based, 500ms debounce)
Works offline	Yes	Yes	No	Yes

---

Supported Languages

Language	Extensions	Parser
Python	.py	tree-sitter-python
TypeScript	.ts, .tsx	tree-sitter-typescript
JavaScript	.js, .jsx, .mjs, .cjs	tree-sitter-javascript

---

Installation

# With pip
pip install axoniq

# With uv (recommended)
uv add axoniq

# With Neo4j backend support
pip install axoniq[neo4j]

Requires Python 3.11+.

From Source

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

---

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 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

Label	Description
File	Source file
Folder	Directory
Function	Top-level function
Class	Class definition
Method	Method within a class
Interface	Interface / Protocol definition
TypeAlias	Type alias
Enum	Enumeration
Community	Auto-detected functional cluster
Process	Detected execution flow

Relationships

Type	Description	Key Properties
CONTAINS	Folder -> File/Symbol hierarchy	--
DEFINES	File -> Symbol it defines	--
CALLS	Symbol -> Symbol it calls	confidence (0.0-1.0)
IMPORTS	File -> File it imports from	symbols (names list)
EXTENDS	Class -> Class it extends	--
IMPLEMENTS	Class -> Interface it implements	--
USES_TYPE	Symbol -> Type it references	role (param/return/variable)
EXPORTS	File -> Symbol it exports	--
MEMBER_OF	Symbol -> Community it belongs to	--
STEP_IN_PROCESS	Symbol -> Process it participates in	step_number
COUPLED_WITH	File -> File that co-changes with it	strength, co_changes

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
        +----------+     +----------+
        |   MCP    |     |   CLI    |
        |  Server  |     | (Typer)  |
        | (stdio)  |     |          |
        +----+-----+     +----+-----+
             |                |
        Claude Code      Terminal
        / Cursor         (developer)

Tech Stack

Layer	Technology	Purpose
Parsing	tree-sitter	Language-agnostic AST extraction
Graph Storage	KuzuDB	Embedded graph database with Cypher, FTS, and vector support
Graph Algorithms	igraph + leidenalg	Leiden community detection
Embeddings	fastembed	ONNX-based 384-dim vectors (~100MB, no PyTorch)
MCP Protocol	mcp SDK (FastMCP)	AI agent communication via stdio
CLI	Typer + Rich	Terminal interface with progress bars
File Watching	watchfiles	Rust-based file system watcher
Gitignore	pathspec	Full .gitignore pattern matching

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

---

License

MIT

---

Built by @harshkedia177