Auryn turns any codebase into a queryable codegraph in FalkorDB.
Your agent traverses it over MCP and answers from real structure, with file and line citations, instead of grepping and guessing.
Quickstart · Connect your agent · Languages · Docs · Website
WORKS WITH
Claude Code · Codex · Cursor · Windsurf · GitHub Copilot · VS Code Copilot Chat · Gemini CLI · Antigravity · Aider · any agent that reads AGENTS.md or connects over MCP
Claude Code on Django, hard structural questions (transitive closure and impact), with and without Auryn:
| Without Auryn | With Auryn | Change | |
|---|---|---|---|
| Accuracy (key facts covered) | 22% | 92% | 4x |
| Run time per task | 208s | 70s | -66% |
| Cost per task | $0.72 | $0.38 | -47% |
| Tokens per task | 466k | 355k | -24% |
The agent stops reading its way through the tree. It asks the graph who calls a function, what a change reaches, or how a request gets from a button to a table, and gets an answer it can cite.
flowchart LR
Y([You]) -- plain-language question --> A[Your coding agent]
A -- MCP tools --> M[Auryn]
M -- read-only queries --> F[(FalkorDB codegraph)]
R[[Your repo<br/>16 languages + SQL]] -- ingest / incremental resync --> F
- Parse. Auryn reads every file and builds a codegraph of functions, types, tables and endpoints, plus the edges between them (
CALLS,EXTENDS,READS/WRITES,DEPENDS_ON). - Store. The codegraph lives in FalkorDB, on your machine or a server you run.
- Query. Your agent traverses it through MCP and cites file and line for every claim.
Two commands, zero infrastructure. You'll be looking at a real graph in about a second.
pip install falkordb-auryn
auryn quickstartThis boots FalkorDB embedded (in-process, no daemon), ingests a small payments API that ships inside the package, and opens the viewer at http://127.0.0.1:8080.
Your own project is the same command with a path:
auryn quickstart path/to/your/repoFind a path between any two symbols and the viewer shows every hop, with the edge it followed:
The codegraph persists at <path>/.auryn/graph.db, so re-running reuses it.
Requirements: Python ≥ 3.12.
falkordb-aurynincludes every plugin out of the box; for a custom install, see Choose your plugins. The in-process database is fetched automatically on firstauryn quickstarton macOS and Linux (recent glibc). On native Windows or older-glibc Linux, point at a remote FalkorDB withauryn install --backend remote. Add live-DB drivers with"falkordb-auryn[all]". For an isolated tool install, include the DB up front:uv tool install "falkordb-auryn[embedded]". From a clone:uv sync, thenuv run auryn quickstart.
The viewer is a one-shot look. The real payoff is your agent querying the graph itself. Install once:
auryn installThis asks for a FalkorDB backend, local (bundled server, starts on demand) or remote (host, port, credentials), and how to keep the graph fresh (manual, on commit, or on save). It then registers the auryn MCP server and skill with every agent it detects. It writes only to ~/.auryn and the agent's own config. Nothing is written to your repositories.
Restart your agent and ask:
You: What breaks if I change the signature of
charge_card?
● auryn_status() → no graph for this repo yet
● index_repository(path=".") → indexed: functions, calls, endpoints, inheritance
● locate(name="charge_card") → Function app/billing.py:9 id: python://…charge_card(...)
● impact_of(id="python://…charge_card(...)", edge_types=["CALLS"])
→ create_charge (app/api.py) -[EXPOSES_ENDPOINT]-> POST /charges
Agent: One direct caller:
create_chargeinapp/api.py, which handles POST /charges, so the endpoint's contract changes with it.charge_carditself callsget_account,_guard_limitandConnection.execute. None of them are affected by a signature change. Updatecreate_chargeand the/chargesrequest shape together. (citesapp/api.py:15,app/billing.py:9)
No raw Cypher, no file dumps, no guessing. One hop, id-backed. Each repo gets its own graph.
The tools your agent gets
| Tool | What it does | |
|---|---|---|
auryn_status |
read | Is there a graph yet, and what's in it? Called first. |
index_repository / ingest_repository |
write | Build or update the graph for a local dir or git repo. |
locate |
read | Find symbols by name. The entry point: other tools take the id it returns. |
search_code |
read | Semantic (vector) search by meaning when you don't know the name. On by default — the vector index builds automatically in the background. |
get_context |
read | One node's properties, source, and 1-hop neighbours. |
who_calls / callees |
read | Inbound callers / outbound callees within N hops. |
find_path |
read | Shortest path between two nodes: does X reach Y, and how. |
impact_of |
read | Blast radius over CALLS/DEPENDS_ON/READS/WRITES. |
trace_entrypoint |
read | Full call closure of an entry point, plus every table it touches. |
get_schema / run_cypher |
read | The meta-model, and arbitrary read-only Cypher. |
list_graphs / use_graph switch between multiple graphs on one instance.
| Question | grep | Auryn |
|---|---|---|
| Who calls this? | every textual match, no callers of callers | exact inbound edges, N hops deep |
| What breaks if I change it? | you read and hope | traversal with file:line citations |
| Does this endpoint touch that table? | unanswerable | one path query |
| How does a request get from the UI to the database? | open files one by one | one path, across languages |
| Is the answer current? | always re-read | incremental resync on every commit |
One query traces a change across languages. Changing OrderController.Submit (C#):
flowchart LR
A["SubmitOrderButton<br/>TypeScript component"] -- CALLS --> C(["OrderController.Submit<br/>C# method"])
B["NightlyReorderJob<br/>C# scheduled job"] -- CALLS --> C
C -- DISPATCHES_TO --> D["PKG_ORDERS.SUBMIT<br/>PL/SQL procedure"]
D -- WRITES --> E[("ORDER_LINES<br/>Oracle table")]
Blast radius: the two callers on the left. Closure: everything it reaches on the right.
- Stored in a graph database. The graph lives in FalkorDB and stays loaded, so caller and impact lookups are a query, not a file scan.
- Incremental resync. On a commit or branch switch, Auryn re-parses only the changed files and the code they affect. On Django that is about 150x faster than a full re-ingest. See ADR 0002.
- Two levels of analysis. Every language gets a fast structural pass. Python (Jedi) and C# (Roslyn) also get a deep semantic pass, inline or in the background, so calls land on the code that actually runs.
- Search plus structure. Semantic search is on by default — embeddings build in the background after each ingest, off the critical path, so the graph is queryable immediately while the vector index fills in. Semantic search finds the code; the graph returns what that code calls, imports and depends on.
- Cross-repo references. When code points at a symbol in another repository, Auryn records it and links it once that repo is ingested. See ADR 0004.
- One vocabulary for every language. Every ingestor writes the same node and edge types, so a single query follows a request from a TypeScript button, through a C# API, to the PL/SQL procedure and table it writes.
Note
Parsing runs locally. The graph lives on your machine or on a FalkorDB server you run, with no hosted service in the path and no telemetry. Read tools issue only GRAPH.RO_QUERY, so an agent cannot write to your graph, and install touches nothing but ~/.auryn and your agent's config. auryn uninstall --purge also deletes ~/.auryn, including config and graphs.
Sixteen languages plus live SQL and Oracle schemas, all auto-detected by auryn ingest in a single pass. Live databases are read with auryn run <name>. With a custom install (see Choose your plugins), only the installed plugins run. A missing plugin for one of the 15 programming languages is installed the first time its files are found (unless AURYN_AUTO_INSTALL=0). The others are never installed automatically: name them on the core, e.g. auryn-core[oracle] for PL/SQL files (.pks, .pkb, .sql, …), auryn-core[sql] for live SQL databases, and auryn-core[http,orm,grpc,events] for the cross-language links.
All sources and engines
| Source | Plugin | Engine |
|---|---|---|
| Python | python |
tree-sitter → Jedi (deep) |
| TypeScript / JavaScript | typescript |
tree-sitter |
| C# | csharp |
Roslyn (deep), tree-sitter fallback |
| Java · C · C++ · CUDA | java c cpp cuda |
tree-sitter |
| Go · Rust · PHP · Julia | go rust php julia |
tree-sitter |
| Ruby · Kotlin · Swift · Bash | ruby kotlin swift bash |
tree-sitter |
| PL/SQL files | oracle |
vendored ANTLR |
| Oracle (live DB) | oracle-live |
oracledb + ANTLR |
| SQL schema (live DB) | sql sql-all |
SQLAlchemy, any dialect |
| Cross-language links | http orm grpc events |
HTTP call → endpoint, ORM model → table, gRPC call → handler, publisher → subscriber |
The deep C# engine needs the .NET SDK on PATH. Without it, C# falls back to tree-sitter automatically.
pip install falkordb-auryn installs every plugin above. For a custom install, name the plugins on the core instead:
pip install falkordb-auryn # everything
pip install "auryn-core[python,http]" # core + only the plugins you name
pip install auryn-core my-auryn-plugin # core + your own pluginOptional extras on either package: [embedded] (the in-process FalkorDB), [oracle-live] and [sql-all] (live-DB drivers); [all] adds both drivers (auryn-core[all] also adds every plugin, the same as falkordb-auryn[all]).
auryn ingest dir /path/to/repo --project-name MyApp # auto-detect every language
auryn ingest repo https://github.com/you/repo.git --ref main
auryn sync # incremental resync of a repo's graph
auryn view # open the viewer against the configured backend
auryn serve | stop # run/stop the local FalkorDB daemon explicitly
auryn uninstall [--purge] # reverse installOmit --host/--port and it uses the backend from auryn install. Full reference: docs/cli.md, or auryn <command> --help. Runnable walkthroughs live in demo/.
| Architecture | Plugin discovery, the ingest pipeline, delta-sync, backends. |
| Graph model | Labels, edges, ids, provenance, cross-repo linkage, and what each ingestor extracts. |
| CLI reference | Every command and flag. |
| Adding a language | A worked, line-by-line new ingestor. |
| Docs index | Everything, including the ADRs. |
uv sync --group dev
uv run pytest --cov=auryn --cov-report=term-missingTests run against embedded FalkorDB by default, with no server and no Docker. Set AURYN_TEST_BACKEND=server for a real one. New language ingestors are very welcome: start at CONTRIBUTING.md. Issues and pull requests are welcome too.
If Auryn helps your agent, a ⭐ helps other developers find it.
Built by FalkorDB · falkordb.com/products/codegraph-auryn

