Axon: a precomputed code knowledge graph for MCP agents and a local web UI

The problem Axon targets: agents that grep for callers and miss the indirect ones

The README frames the failure mode concretely. An agent edits UserService.validate() without knowing that, in the project's own illustration, 47 functions depend on that return type, three execution flows pass through it, and payment_handler.py changes alongside it 80 percent of the time. The stated cause is that agents operate on flat text: they grep for callers, miss indirect ones, and have no model of how code is connected. The README also notes that LSPs do not expose call graphs, so the usual editor-side answer does not transfer to an agent working through tool calls. Axon's audience is therefore narrow and specific: developers running an MCP-capable agent against a codebase where a change to one symbol can break code three hops away. If your agent already succeeds at that with ripgrep and a large context window, the graph adds cost without adding information.

A 12-phase index pipeline that precomputes structure instead of retrieving it

The mechanism is a single indexing pass the README calls a 12-phase pipeline. The sample terminal output enumerates the phases in order: walking files, parsing code, tracing calls, analyzing types, detecting communities, detecting execution flows, finding dead code, analyzing git history, generating embeddings. In the example run the counters read 142 files parsed, 847 calls resolved, 234 type relationships, 8 clusters, 34 processes, 12 unreachable symbols, 18 coupled file pairs and 623 vectors stored, finishing in 4.2 seconds. Those numbers are the README's illustration of one repository, not a benchmark, and the project publishes no cross-repository performance data that I can see. The architectural consequence matters more than the counts. Because structure is resolved at index time, an MCP tool call like axon_impact("validate") is described as returning all affected symbols grouped by depth (will break, may break, review) with confidence scores in one response, and axon_context("UserService") as returning callers, callees, type references, community membership and dead code status together. The trade is clear: you pay an indexing pass up front and accept that the graph is only as fresh as the last analysis, in exchange for tool responses that do not require the agent to chain ten searches. Storage and search run locally, including the embeddings, which the README states uses 384-dimension vectors from BAAI/bge-small-en-v1.5.

Hybrid search: BM25, vectors and Levenshtein fused with Reciprocal Rank Fusion

Search is the part of the pipeline with the most visible engineering detail. Three strategies run and are fused using Reciprocal Rank Fusion, with a link to the original RRF paper. BM25 full-text matching runs through KuzuDB's FTS support, which tells you the graph store is KuzuDB. Semantic search uses the 384-dimension embeddings. A Levenshtein fallback handles typos and partial names. After fusion, results are reweighted: test files are down-ranked by 0.5x and source functions and classes boosted by 1.2x, then grouped by execution flow rather than returned as a flat list. Those two constants are the kind of thing worth knowing before you trust a ranking, because they encode an opinion that a match inside a test file is half as interesting as a match in source. That is usually right and occasionally wrong, for example when you are deliberately hunting for the test that covers a symbol. The grouping by execution flow is the more consequential choice: it means a single query response can carry architectural context, which is exactly what the README claims saves tokens, but it also means the response shape is not a simple relevance list and an agent has to be able to read the nested structure.

Getting it running: pip install axoniq, one analyze pass, then MCP or the UI

Installation is a single PyPI package, and the name does not match the project name: the package is axoniq while the command and repository are axon. The README's quickstart is pip install axoniq, then cd your-project && axon analyze . to index, then axon ui to open the dashboard at localhost:8420. The UI accepts axon ui --watch for live reload on file changes, axon ui --port 9000 for a different port, and axon ui --dev for Vite HMR on port 5173. There is also axon host --watch, described as a shared host serving the UI plus multi-session MCP, which is the mode you want if more than one agent session or a browser and an agent need to read the same graph. For agent integration the README gives a .mcp.json block in the project root with an mcpServers entry named axon, command axon, and args ["serve", "--watch"]. Note that the MCP path uses axon serve and the browser path uses axon ui, and that watch mode appears in both, which implies the graph is re-analyzed as files change rather than being a one-shot artifact. The README states the UI is backed by a FastAPI server with a REST API, and it points to an API Endpoints section for the routes, but that section is not included in the material I have, so I cannot list the endpoints.

What the dashboard actually shows, and where the documentation runs out

The web UI has three views. Explorer is a force-directed graph rendered with Sigma.js and WebGL, with a file tree sidebar, a symbol detail panel showing code preview, callers, callees, impact analysis and process memberships, and community hull overlays that draw architectural clusters as regions. Analysis collects health score, coupling heatmap, dead code report, inheritance tree, branch diff and aggregate stats. Cypher Console is a query editor with syntax highlighting, a preset query library, a results table and history. The presence of a Cypher console is the strongest signal about the storage layer: the graph is queryable in Cypher, consistent with the KuzuDB reference in the search section. Around those views the README lists a command palette on Cmd+K, keyboard shortcuts, a graph minimap, flow trace and impact ripple animations, and SSE-powered live reload when watch mode is active. This is where the documentation thins out. The health score in the Analysis view is named but never defined, so there is no way to know what inputs produce it or what a good value looks like. The branch diff view is listed without saying what it compares. The README's own overview text is truncated mid-sentence at impact analysis, so the description of how git coupling history feeds into impact ranking stops before explaining the mechanism. Treat the health score as a diagnostic prompt rather than a metric until you can read the formula in the source.

The licence is unstated, and that is a real adoption blocker

The repository metadata supplied here lists the licence as unknown. The README carries a License badge pointing at a LICENSE file in the repository and a PyPI licence badge for the axoniq package, but the badge images do not resolve to a licence identifier in the material I have. That means I cannot tell you whether Axon is permissively licensed, copyleft, or source-available under terms that restrict commercial use. For an individual developer experimenting locally this is a non-issue. For anyone embedding Axon in a product, in CI, or in a corporate environment with licence review, it is the first thing to resolve, and the answer is one click away in the repository's LICENSE file. I am not going to guess at it, and I would not treat the presence of a badge as evidence of a specific licence. On maintenance cost, the release history shows v0.2.4 in late February 2026, v1.0.0 in early March 2026, and v1.0.1 the following day, with the last push to the repository in August 2026. The gap between the 1.0.1 patch and the most recent push suggests active development continued without further tagged releases, which is common but means the tag history is not a reliable indicator of current state. Pin a version in CI rather than tracking main, because the MCP tool response shapes described in the README are the kind of surface that changes between minor versions.

When a knowledge graph is the wrong tool, and what a plain language server does differently

Axon's premise is that structure should be precomputed and served whole. The obvious alternative for a developer working in an editor is a language server: pyright or gopls or tsserver answering go-to-definition, find-references and rename requests against a live project. The difference in approach is not cosmetic. A language server computes on demand against the files as they are right now, so it is never stale, and it is already integrated into the editor you are using. Axon computes once and persists a graph, which is what lets it answer questions a language server does not expose, such as which symbols form a community, which execution flows pass through a function, which symbols are unreachable, and which files change together in git history. The cost of that persistence is staleness and an indexing step, and the README's reliance on --watch flags across analyze, serve and ui is an admission that the graph needs refreshing. So the honest split is this: if your question is where is this symbol defined or who calls it directly, a language server answers it faster and always correctly. If your question is what is the blast radius of changing this return type across the whole repository, including indirect callers and coupled files, that is the question Axon was built to answer, and it is the question an agent cannot answer by grepping. The wrong-tool case is a small or fast-moving repository where re-indexing costs more than the structural insight is worth, or a polyglot repository, since the topics list tree-sitter and TypeScript but the primary language is Python and the README never claims coverage beyond the languages it parses.

Editorial conclusion

Axon is worth installing if you already run an MCP-capable coding agent on a repository large enough that grep-based caller discovery keeps missing indirect dependents, and you want the graph to stay on your machine. It is the wrong choice if you need a published licence before procurement will approve it, if your codebase is not Python or TypeScript, or if you expect the MCP server to stay responsive on a very large tree without measuring it yourself. Before adopting, run axon analyze . on your actual repository, open the Cypher Console and check whether the call edges and community assignments match what you know about your architecture. That check takes minutes and tells you more than any feature list.

Official sources

1. harshkedia177/axon on GitHub
2. Issues
3. Project website
4. README
5. Releases