The codegraph for your coding agents
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
Results
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.
How it works
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.
Quickstart
Two commands, zero infrastructure. You'll be looking at a real graph in about a second.
pip install falkordb-auryn
auryn quickstart
This 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/repo
Find 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.
Connect your agent
The viewer is a one-shot look. The real payoff is your agent querying the graph itself. Install once:
auryn install
This 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.
Why a graph
| 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.
Under the hood
- 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.
Your code stays yours
What it can read
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.
Choose your plugins
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 plugin
Optional 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]).
CLI
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 install
Omit --host/--port and it uses the backend from auryn install. Full reference: docs/cli.md, or auryn <command> --help. Runnable walkthroughs live in demo/.
Documentation
| 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. |
Contributing
uv sync --group dev
uv run pytest --cov=auryn --cov-report=term-missing
Tests 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
Metadata
Release files for falkordb-auryn 0.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| falkordb_auryn-0.8.2.tar.gz | 4.1 MB | Without provenance | Details for falkordb_auryn-0.8.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| falkordb_auryn-0.8.2-py3-none-any.whl | Python 3 | none | any | Details for falkordb_auryn-0.8.2-py3-none-any.whl |
Total release size: 4.2 MB
Release files / falkordb_auryn-0.8.2.tar.gz
| Download URL | falkordb_auryn-0.8.2.tar.gz |
|---|---|
| Size | 4.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e82f05924449a3c963f01299cf0cd7f31dd7a41d62d6f9e2813ef85469ef01cb
|
|
BLAKE2b-256 checksum How to use checksums |
86a4aef2cd747c8f952dd0c12a24aa4fa28b56090611a96ba80929c52a50c341
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / falkordb_auryn-0.8.2-py3-none-any.whl
| Download URL | falkordb_auryn-0.8.2-py3-none-any.whl |
|---|---|
| Size | 8.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d4dd0af1c0af5e56d7e51d88c04892fca51e75f5dbd55d3bc5e9c51c02578f0
|
|
BLAKE2b-256 checksum How to use checksums |
12c25cb279778c5d29bdab8668cedf9a6b2e6a806c2c3bfdfe654d8e9bda8c62
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for falkordb-auryn 0.8.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.