Skip to content
Back to search

axon

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harshkedia177--axon/badge.svg)](/listings/harshkedia177--axon)

HTML

<a href="/listings/harshkedia177--axon"><img src="/api/listings/harshkedia177--axon/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 667 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/harshkedia177/axon/main/axon-logo.png" alt="Axon logo" width="420" />
  3. </p>
  4. # Axon
  5. [![PyPI version](https://img.shields.io/pypi/v/axoniq)](https://pypi.org/project/axoniq/)
  6. [![PyPI downloads](https://static.pepy.tech/badge/axoniq/month)](https://pepy.tech/projects/axoniq)
  7. [![Total installs](https://static.pepy.tech/badge/axoniq)](https://pepy.tech/projects/axoniq)
  8. [![GitHub stars](https://img.shields.io/github/stars/harshkedia177/axon?style=social)](https://github.com/harshkedia177/axon)
  9. [![License](https://img.shields.io/pypi/l/axoniq)](https://github.com/harshkedia177/axon/blob/main/LICENSE)
  10. **The knowledge graph for your codebase — explore it visually, or let your AI agent query it.**
  11. 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.
  12. ```
  13. $ axon analyze .
  14. Walking files... 142 files found
  15. Parsing code... 142/142
  16. Tracing calls... 847 calls resolved
  17. Analyzing types... 234 type relationships
  18. Detecting communities... 8 clusters found
  19. Detecting execution flows... 34 processes found
  20. Finding dead code... 12 unreachable symbols
  21. Analyzing git history... 18 coupled file pairs
  22. Generating embeddings... 623 vectors stored
  23. Done in 4.2s — 623 symbols, 1,847 edges, 8 clusters, 34 flows
  24. ```
  25. Then explore your codebase visually:
  26. ```bash
  27. axon ui # Opens interactive dashboard at localhost:8420
  28. ```
  29. **Three views, one command:**
  30. - **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.
  31. - **Analysis** — Health score, coupling heatmap, dead code report, inheritance tree, branch diff — your codebase health in one dashboard.
  32. - **Cypher Console** — Write and run Cypher queries against the graph with syntax highlighting, presets, and history.
  33. Plus: command palette (`Cmd+K`), keyboard shortcuts, flow trace animations, graph minimap, and SSE-powered live reload when watch mode is active.
  34. ---
  35. ## The Problem
  36. 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.
  37. **Breaking changes ship.**
  38. 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.
  39. The agent needs a **knowledge graph** — not more text.
  40. ---
  41. ## How Axon Solves It
  42. 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.
  43. A 12-phase pipeline runs once over your repo. After that:
  44. - `axon_impact("validate")` returns all 47 affected symbols, grouped by depth (will break / may break / review), with confidence scores — in a single call
  45. - `axon_query("auth handler")` returns hybrid-ranked results grouped by execution flow, not a flat list of name matches
  46. - `axon_context("UserService")` returns callers, callees, type references, community membership, and dead code status — the full picture
  47. **Three benefits:**
  48. 1. **Reliability** — the context is already in the tool response. No multi-step exploration that can miss code.
  49. 2. **Token efficiency** — one tool call instead of a 10-query search chain. Agents spend tokens on reasoning, not navigation.
  50. 3. **Model democratization** — even smaller models get full architectural clarity because the tools do the heavy lifting.
  51. **Zero cloud dependencies.** Everything runs locally — parsing, graph storage, embeddings, search. No API keys, no data leaving your machine.
  52. ---
  53. ## TL;DR
  54. ```bash
  55. pip install axoniq # 1. Install
  56. cd your-project && axon analyze . # 2. Index (one command, ~5s for most repos)
  57. axon ui # 3. Explore visually at localhost:8420
  58. ```
  59. **For AI agents** — add to `.mcp.json` in your project root:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "axon": {
  64. "command": "axon",
  65. "args": ["serve", "--watch"]
  66. }
  67. }
  68. }
  69. ```
  70. **For developers** — explore the graph yourself:
  71. ```bash
  72. axon ui # Interactive dashboard (standalone or attaches to running host)
  73. axon ui --watch # Live reload on file changes
  74. axon host --watch # Shared host: UI + multi-session MCP
  75. ```
  76. ---
  77. ## What You Get
  78. ### Explore your codebase visually
  79. **Web UI**
  80. A full interactive dashboard — no terminal or extensions required. One command:
  81. ```bash
  82. axon ui # Launch at localhost:8420
  83. axon ui --watch # Live reload on file changes
  84. axon ui --port 9000 # Custom port
  85. axon ui --dev # Dev mode (Vite HMR on :5173)
  86. ```
  87. | View | What It Shows |
  88. |------|--------------|
  89. | **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. |
  90. | **Analysis** | Health score, coupling heatmap, dead code report, inheritance tree visualization, branch diff, and aggregate stats — your codebase health at a glance. |
  91. | **Cypher Console** | Query editor with syntax highlighting, preset query library, results table, and query history. |
  92. **Extras:** Command palette (`Cmd+K`), keyboard shortcuts, graph minimap, flow trace and impact ripple animations, SSE-powered live reload when watch mode is enabled.
  93. The UI is backed by a FastAPI server with a full REST API — see [API Endpoints](#api-endpoints) below.
  94. ### Find anything — by name, concept, or typo
  95. **Hybrid Search (BM25 + Vector + Fuzzy)**
  96. Three search strategies fused with [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf):
  97. - **BM25 full-text search** — fast exact name and keyword matching via KuzuDB FTS
  98. - **Semantic vector search** — conceptual queries via 384-dim embeddings (BAAI/bge-small-en-v1.5)
  99. - **Fuzzy name search** — Levenshtein fallback for typos and partial matches
  100. 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.
  101. ### Know what breaks before you change it
  102. **Impact Analysis with Depth Grouping**
  103. 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:
  104. - **Depth 1** — Direct callers (will break)
  105. - **Depth 2** — Indirect callers (may break)
  106. - **Depth 3+** — Transitive (review)
  107. Every edge carries a confidence score (1.0 = exact match, 0.8 = receiver method, 0.5 = fuzzy) so you can prioritize what to review.
  108. ### Find what to delete
  109. **Dead Code Detection**
  110. Not just "zero callers" — a multi-pass analysis that understands your framework:
  111. 1. **Initial scan** — flags symbols with no incoming calls
  112. 2. **Exemptions** — entry points, exports, constructors, test code, dunder methods, `__init__.py` symbols, decorated functions, `@property` methods
  113. 3. **Override pass** — un-flags methods overriding non-dead base class methods
  114. 4. **Protocol conformance** — un-flags methods on Protocol-conforming classes
  115. 5. **Protocol stubs** — un-flags all methods on Protocol classes (interface contracts)
  116. ### Understand how code runs, not just where it sits
  117. **Execution Flow Tracing**
  118. Detects entry points using framework-aware patterns:
  119. - **Python**: `@app.route`, `@router.get`, `@click.command`, `test_*` functions, `__main__` blocks
  120. - **JavaScript/TypeScript**: Express handlers, exported functions, `handler`/`middleware` patterns
  121. Then traces BFS execution flows from each entry point through the call graph, classifying flows as intra-community or cross-community.
  122. ### See your architecture without reading docs
  123. **Community Detection**
  124. Uses the [Leiden algorithm](https://www.nature.com/articles/s41598-019-41695-z) (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.
  125. ### Find hidden dependencies git knows about
  126. **Change Coupling (Git History)**
  127. Analyzes 6 months of git history to find dependencies that static analysis misses:
  128. ```
  129. coupling(A, B) = co_changes(A, B) / max(changes(A), changes(B))
  130. ```
  131. 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`.
  132. ### Always up to date
  133. **Watch Mode**
  134. Live re-indexing powered by a Rust-based file watcher (watchfiles):
  135. ```bash
  136. $ axon watch
  137. Watching /Users/you/project for changes...
  138. [10:32:15] src/auth/validate.py modified -> re-indexed (0.3s)
  139. [10:33:02] 2 files modified -> re-indexed (0.5s)
  140. ```
  141. File-local phases (parse, imports, calls, types) run immediately on change. Global phases (communities, processes, dead code) batch every 30 seconds.
  142. ### Structural diff, not text diff
  143. **Branch Comparison**
  144. Compare branches at the symbol level using git worktrees (no stashing required):
  145. ```bash
  146. $ axon diff main..feature
  147. Symbols added (4):
  148. + process_payment (Function) -- src/payments/stripe.py
  149. + PaymentIntent (Class) -- src/payments/models.py
  150. Symbols modified (2):
  151. ~ checkout_handler (Function) -- src/routes/checkout.py
  152. Symbols removed (1):
  153. - old_charge (Function) -- src/payments/legacy.py
  154. ```
  155. ### Clean call graphs
  156. **Noise Filtering**
  157. 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()`.
  158. ---
  159. ## The Pipeline
  160. Axon builds deep structural understanding through 12 sequential analysis phases:
  161. | Phase | What It Does |
  162. |-------|-------------|
  163. | **File Walking** | Walks repo respecting `.gitignore`, filters by supported languages |
  164. | **Structure** | Creates File/Folder hierarchy with CONTAINS relationships |
  165. | **Parsing** | tree-sitter AST extraction — functions, classes, methods, interfaces, enums, type aliases |
  166. | **Import Resolution** | Resolves import statements to actual files (relative, absolute, bare specifiers) |
  167. | **Call Tracing** | Maps function calls with confidence scores. Noise filtering skips 138 language builtins |
  168. | **Heritage** | Tracks class inheritance (EXTENDS) and interface implementation (IMPLEMENTS) |
  169. | **Type Analysis** | Extracts type references from parameters, return types, and variable annotations |
  170. | **Community Detection** | Leiden algorithm clusters related symbols into functional communities |
  171. | **Process Detection** | Framework-aware entry point detection + BFS flow tracing |
  172. | **Dead Code Detection** | Multi-pass analysis with override, protocol, and decorator awareness |
  173. | **Change Coupling** | Git history analysis — finds files that always change together |
  174. | **Embeddings** | 384-dim vectors for every symbol, enabling semantic search. Skip with `--no-embeddings` |
  175. ---
  176. ## MCP Integration
  177. Axon exposes its full intelligence as an MCP server. Set it up once, and your AI agent has structural understanding of your codebase forever.
  178. ### Setup
  179. **Claude Code** — add to `.mcp.json` in your project root (or run `claude mcp add axon -- axon serve --watch`):
  180. ```json
  181. {
  182. "mcpServers": {
  183. "axon": {
  184. "command": "axon",
  185. "args": ["serve", "--watch"]
  186. }
  187. }
  188. }
  189. ```
  190. **Cursor** — add to your MCP settings:
  191. ```json
  192. {
  193. "axon": {
  194. "command": "axon",
  195. "args": ["serve", "--watch"]
  196. }
  197. }
  198. ```
  199. Optional new feature:
  200. ```bash
  201. axon host --watch
  202. ```
  203. This starts a shared host for the UI and multiple MCP clients. `axon setup --claude` / `axon setup --cursor` still prints the standard config.
  204. The `--watch` flag enables live re-indexing — the graph updates as you edit code.
  205. ### Tools
  206. | Tool | What the agent gets |
  207. |------|-------------|
  208. | `axon_query` | Hybrid search (BM25 + vector + fuzzy) with results grouped by execution flow |
  209. | `axon_context` | 360-degree view — callers, callees, type refs, confidence tags, dead code status |
  210. | `axon_impact` | Blast radius grouped by depth — direct (will break), indirect (may break), transitive |
  211. | `axon_dead_code` | All unreachable symbols grouped by file |
  212. | `axon_detect_changes` | Map a `git diff` to affected symbols and execution flows |
  213. | `axon_list_repos` | All indexed repositories with stats |
  214. | `axon_cypher` | Read-only Cypher queries against the knowledge graph |
  215. Every tool response includes a **next-step hint** guiding the agent through a natural investigation workflow:
  216. ```
  217. query -> "Next: Use context() on a specific symbol for the full picture."
  218. context -> "Next: Use impact() if planning changes to this symbol."
  219. impact -> "Tip: Review each affected symbol before making changes."
  220. ```
  221. ### Resources
  222. | URI | Description |
  223. |-----|-------------|
  224. | `axon://overview` | Node and relationship counts by type |
  225. | `axon://dead-code` | Full dead code report |
  226. | `axon://schema` | Graph schema reference for Cypher queries |
  227. ---
  228. ## API Endpoints
  229. The web UI is backed by a FastAPI server. All endpoints are under `/api`:
  230. | Endpoint | Description |
  231. |----------|-------------|
  232. | `GET /api/graph` | Full knowledge graph (paginated) |
  233. | `GET /api/node/{id}` | Node detail with callers, callees, type refs |
  234. | `GET /api/overview` | Aggregate node/edge counts |
  235. | `GET /api/search` | Hybrid search (BM25 + vector + fuzzy) |
  236. | `GET /api/impact/{id}` | Blast radius analysis by depth |
  237. | `GET /api/dead-code` | Dead code report |
  238. | `GET /api/communities` | Community listing with members |
  239. | `GET /api/coupling` | Change coupling heatmap data |
  240. | `GET /api/files/{path}` | Source file content with syntax context |
  241. | `POST /api/cypher` | Execute read-only Cypher queries |
  242. | `GET /api/diff` | Structural branch comparison |
  243. | `GET /api/processes` | Execution flow listing |
  244. | `GET /api/events` | SSE stream for live reload events |
  245. | `POST /api/reindex` | Trigger a full re-index (watch mode only) |
  246. Cypher queries are validated server-side — write keywords (`CREATE`, `DELETE`, `DROP`, etc.) are rejected after comment stripping.
  247. ---
  248. ## How It Compares
  249. | Capability | grep / ripgrep | LSP | Context window stuffing | Axon |
  250. |-----------|---------------|-----|------------------------|------|
  251. | **Interactive graph UI** | **No** | **No** | **No** | **Yes (full web dashboard)** |
  252. | Text search | Yes | No | Yes | Yes (hybrid BM25 + vector) |
  253. | Find all callers | No | Partial | Hit-or-miss | Yes (full call graph with confidence) |
  254. | Type relationships | No | Yes | No | Yes (param/return/variable roles) |
  255. | Dead code detection | No | No | No | Yes (multi-pass, framework-aware) |
  256. | Execution flow tracing | No | No | No | Yes (entry point -> flow) |
  257. | Community detection | No | No | No | Yes (Leiden algorithm) |
  258. | Change coupling (git) | No | No | No | Yes (6-month co-change analysis) |
  259. | Impact analysis | No | No | No | Yes (depth-grouped with confidence) |
  260. | AI agent integration | No | Partial | N/A | Yes (full MCP server) |
  261. | Structural branch diff | No | No | No | Yes (node/edge level) |
  262. | Watch mode | No | Yes | No | Yes (Rust-based, 500ms debounce) |
  263. | Works offline | Yes | Yes | No | Yes |
  264. ---
  265. ## Supported Languages
  266. | Language | Extensions | Parser |
  267. |----------|-----------|--------|
  268. | Python | `.py` | tree-sitter-python |
  269. | TypeScript | `.ts`, `.tsx` | tree-sitter-typescript |
  270. | JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | tree-sitter-javascript |
  271. ---
  272. ## Installation
  273. ```bash
  274. # With pip
  275. pip install axoniq
  276. # With uv (recommended)
  277. uv add axoniq
  278. # With Neo4j backend support
  279. pip install axoniq[neo4j]
  280. ```
  281. Requires **Python 3.11+**. The web UI (frontend + backend) is included — no Node.js or extra install needed.
  282. ### From Source
  283. ```bash
  284. git clone https://github.com/harshkedia177/axon.git
  285. cd axon
  286. uv sync --all-extras
  287. uv run axon --help
  288. ```
  289. To rebuild the frontend after making changes (requires Node.js 18+):
  290. ```bash
  291. cd src/axon/web/frontend
  292. npm install && npm run build
  293. ```
  294. ---
  295. ## CLI Reference
  296. ```
  297. axon analyze [PATH] Index a repository (default: current directory)
  298. --full Force full rebuild (skip incremental)
  299. --no-embeddings Skip vector embedding generation (faster indexing)
  300. axon status Show index status for current repo
  301. axon list List all indexed repositories (auto-populated on analyze)
  302. axon clean Delete index for current repo
  303. --force / -f Skip confirmation prompt
  304. axon query QUERY Hybrid search the knowledge graph
  305. --limit / -n N Max results (default: 20)
  306. axon context SYMBOL 360-degree view of a symbol
  307. axon impact SYMBOL Blast radius analysis
  308. --depth / -d N BFS traversal depth (default: 3)
  309. axon dead-code List all detected dead code
  310. axon cypher QUERY Execute a raw Cypher query (read-only)
  311. axon watch Watch mode — live re-indexing on file changes
  312. axon diff BASE..HEAD Structural branch comparison
  313. axon host Shared host for UI + HTTP MCP (default: localhost:8420)
  314. --port / -p PORT Port to serve on (default: 8420)
  315. --watch / --no-watch Enable live file watching
  316. --dev Dev mode — proxy to Vite dev server for HMR
  317. --no-open Don't auto-open browser
  318. axon ui Launch the web UI (default: localhost:8420)
  319. --port / -p PORT Port to serve on (default: 8420)
  320. --watch / -w Enable live file watching with auto-reindex
  321. --dev Dev mode — proxy to Vite dev server for HMR
  322. --no-open Don't auto-open browser
  323. --direct Force standalone mode even if a shared host exists
  324. axon setup Print MCP configuration JSON
  325. --claude For Claude Code
  326. --cursor For Cursor
  327. axon mcp Start the MCP server (stdio transport)
  328. axon serve Start the MCP server
  329. --watch, -w Enable live file watching with auto-reindex
  330. axon --version Print version
  331. ```
  332. ---
  333. ## Example Workflows
  334. ### "I need to refactor the User class — what breaks?"
  335. ```bash
  336. # See everything connected to User
  337. axon context User
  338. # Check blast radius — grouped by depth
  339. axon impact User --depth 3
  340. # Find files that always change with user.py
  341. 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"
  342. ```
  343. ### "Is there dead code we should clean up?"
  344. ```bash
  345. axon dead-code
  346. ```
  347. ### "What are the main execution flows?"
  348. ```bash
  349. axon cypher "MATCH (p:Process) RETURN p.name, p.properties ORDER BY p.name"
  350. ```
  351. ### "Which parts of the codebase are most tightly coupled?"
  352. ```bash
  353. 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"
  354. ```
  355. ---
  356. ## Knowledge Graph Model
  357. ### Nodes
  358. | Label | Description |
  359. |-------|-------------|
  360. | `File` | Source file |
  361. | `Folder` | Directory |
  362. | `Function` | Top-level function |
  363. | `Class` | Class definition |
  364. | `Method` | Method within a class |
  365. | `Interface` | Interface / Protocol definition |
  366. | `TypeAlias` | Type alias |
  367. | `Enum` | Enumeration |
  368. | `Community` | Auto-detected functional cluster |
  369. | `Process` | Detected execution flow |
  370. ### Relationships
  371. | Type | Description | Key Properties |
  372. |------|-------------|----------------|
  373. | `CONTAINS` | Folder -> File/Symbol hierarchy | -- |
  374. | `DEFINES` | File -> Symbol it defines | -- |
  375. | `CALLS` | Symbol -> Symbol it calls | `confidence` (0.0-1.0) |
  376. | `IMPORTS` | File -> File it imports from | `symbols` (names list) |
  377. | `EXTENDS` | Class -> Class it extends | -- |
  378. | `IMPLEMENTS` | Class -> Interface it implements | -- |
  379. | `USES_TYPE` | Symbol -> Type it references | `role` (param/return/variable) |
  380. | `EXPORTS` | File -> Symbol it exports | -- |
  381. | `MEMBER_OF` | Symbol -> Community it belongs to | -- |
  382. | `STEP_IN_PROCESS` | Symbol -> Process it participates in | `step_number` |
  383. | `COUPLED_WITH` | File -> File that co-changes with it | `strength`, `co_changes` |
  384. ### Node ID Format
  385. ```
  386. {label}:{relative_path}:{symbol_name}
  387. Examples:
  388. function:src/auth/validate.py:validate_user
  389. class:src/models/user.py:User
  390. method:src/models/user.py:User.save
  391. ```
  392. ---
  393. ## Architecture
  394. ```
  395. Source Code (.py, .ts, .js, .tsx, .jsx)
  396. |
  397. v
  398. +----------------------------------------------+
  399. | Ingestion Pipeline (12 phases) |
  400. | |
  401. | walk -> structure -> parse -> imports |
  402. | -> calls -> heritage -> types |
  403. | -> communities -> processes -> dead_code |
  404. | -> coupling -> embeddings |
  405. +----------------------+-----------------------+
  406. |
  407. v
  408. +-----------------+
  409. | KnowledgeGraph | (in-memory during build)
  410. +--------+--------+
  411. |
  412. +------------+------------+
  413. v v v
  414. +---------+ +---------+ +---------+
  415. | KuzuDB | | FTS | | Vector |
  416. | (graph) | | (BM25) | | (HNSW) |
  417. +----+----+ +----+----+ +----+----+
  418. +------------+------------+
  419. |
  420. StorageBackend Protocol
  421. |
  422. +-----------+-----------+
  423. v v v
  424. +----------+ +----------+ +----------+
  425. | MCP | | Web UI | | CLI |
  426. | Server | | (FastAPI | | (Typer) |
  427. | (stdio) | | + React)| | |
  428. +----+-----+ +----+-----+ +----+-----+
  429. | | |
  430. Claude Code Browser Terminal
  431. / Cursor (developer) (developer)
  432. ```
  433. ### Tech Stack
  434. | Layer | Technology | Purpose |
  435. |-------|-----------|---------|
  436. | Parsing | tree-sitter | Language-agnostic AST extraction |
  437. | Graph Storage | KuzuDB | Embedded graph database with Cypher, FTS, and vector support |
  438. | Graph Algorithms | igraph + leidenalg | Leiden community detection |
  439. | Embeddings | fastembed | ONNX-based 384-dim vectors (~100MB, no PyTorch) |
  440. | MCP Protocol | mcp SDK (FastMCP) | AI agent communication via stdio |
  441. | Web Backend | FastAPI + Uvicorn | REST API for the web UI, SSE for live updates |
  442. | Web Frontend | React + TypeScript + Vite | Interactive dashboard with Tailwind CSS |
  443. | Graph Visualization | Sigma.js + Graphology | WebGL graph rendering with ForceAtlas2 layout |
  444. | CLI | Typer + Rich | Terminal interface with progress bars |
  445. | File Watching | watchfiles | Rust-based file system watcher |
  446. | Gitignore | pathspec | Full `.gitignore` pattern matching |
  447. ### Storage
  448. Everything lives locally:
  449. ```
  450. your-project/
  451. +-- .axon/
  452. +-- kuzu/ # KuzuDB graph database (graph + FTS + vectors)
  453. +-- meta.json # Index metadata and stats
  454. ```
  455. Add `.axon/` to your `.gitignore`.
  456. A global registry at `~/.axon/repos/` is automatically populated on `axon analyze`, enabling `axon list` to discover all indexed repositories across your machine.
  457. The storage layer is abstracted behind a `StorageBackend` Protocol — KuzuDB is the default, with an optional Neo4j backend available via `pip install axoniq[neo4j]`.
  458. ---
  459. ## Development
  460. ```bash
  461. git clone https://github.com/harshkedia177/axon.git
  462. cd axon
  463. uv sync --all-extras
  464. # Run tests
  465. uv run pytest
  466. # Lint
  467. uv run ruff check src/
  468. # Run from source
  469. uv run axon --help
  470. # Frontend development (React + Vite with HMR)
  471. cd src/axon/web/frontend
  472. npm install
  473. npm run dev # Vite dev server on :5173
  474. # In another terminal:
  475. uv run axon ui --dev # Backend on :8420, proxies to Vite
  476. ```
  477. ---
  478. ## License
  479. MIT
  480. <!-- portfolio-link -->
  481. ---
  482. **[Read the case study →](https://harshkedia.com/work/axon/)** — the design decisions, the trade-offs, and what broke along the way.
  483. Built by [Harsh Kedia](https://harshkedia.com).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.