Skip to main content
Auryn

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


Python 3.12+ MCP FalkorDB PyPI version Forum

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
  1. 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).
  2. Store. The codegraph lives in FalkorDB, on your machine or a server you run.
  3. 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.

The quickstart viewer showing the sample app's call graph: endpoints, the charge_card billing path, and the Account class hierarchy.

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 viewer tracing a path from GB_uop__identity_fc32_int32.c to GB_nnz_full in 3 hops: INCLUDES, INCLUDES, DECLARES.

The codegraph persists at <path>/.auryn/graph.db, so re-running reuses it.

Requirements: Python ≥ 3.12. falkordb-auryn includes every plugin out of the box; for a custom install, see Choose your plugins. The in-process database is fetched automatically on first auryn quickstart on macOS and Linux (recent glibc). On native Windows or older-glibc Linux, point at a remote FalkorDB with auryn 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, then uv 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_charge in app/api.py, which handles POST /charges, so the endpoint's contract changes with it. charge_card itself calls get_account, _guard_limit and Connection.execute. None of them are affected by a signature change. Update create_charge and the /charges request shape together. (cites app/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.

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)

Source distribution for falkordb-auryn 0.8.2
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)

Table of built distributions (wheels) for falkordb-auryn 0.8.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page