Getting started

Install

npm install -g @nodesify/astria

Requires no Rust toolchain — ships prebuilt native binaries via napi-rs. Node.js >= 22.

Build your first graph

Drop into any project folder and run:

astria run .

This runs the full pipeline — detect → extract → build → cluster → analyze → report — and creates a .astria/ directory containing:

• db.sqlite — the graph database
• graph.json — full graph export
• graph_report.md — report with hub nodes, communities, surprising connections

Combine building with a wiki export or embeddings in one step:

astria run . --wiki    # ...also export a markdown wiki to .astria/wiki
astria run . --embed   # ...also compute local embeddings (similar_to edges + semantic query recall)

Keep it fresh

astria update <path>                    # Incremental rebuild (only changed files; regenerates an existing wiki)
astria watch <path> [--debounce 3000]   # Watch for file changes, auto-rebuild

update only re-extracts files that changed since the last run, so large repos rebuild in seconds.

Query it

astria explain <node>                  # Explain a node and its connections
astria query "where does auth live"    # BFS traversal with a token budget
astria path <A> <B>                    # Shortest path between two concepts
astria affected <node>                 # Blast radius - what breaks if you change this node
astria map                             # PageRank-ranked repo map with top symbols

See the CLI reference for every command and flag.

Use it from AI agents

astria mcp          # Run MCP stdio server - query the graph from any AI agent
astria install      # Install skill files for AI coding assistants

mcp exposes the graph over the Model Context Protocol, so any MCP-capable agent (Claude Code, Codex, Cursor, …) can query it — see the MCP tools reference for the tool list. install writes skill files for your assistant of choice; the full setup (platforms, git hooks, the editor guard) is on Agent integration.

Supported platforms: claude, codex, gemini, cursor, copilot, aider, opencode, kiro, trae, zcode.

Git hooks can keep the graph fresh automatically:

astria hook install|uninstall|status

Health, memory, and many repos at once

Three more loops worth knowing about (full flags in the CLI reference):

astria diagnose                        # read-only graph integrity report (--json for tooling)
astria health                          # code-health heuristics and staleness score
astria risk                            # impact of the current git diff
astria save-result "Q" --answer "A"    # curate a settled Q/A into graph memory
astria reflect                         # aggregate memory outcomes into LESSONS.md
astria run . --global --as myrepo      # merge this repo into the cross-repo global graph

diagnose is the first stop when a graph looks wrong (see Troubleshooting); health scores code-health heuristics, and risk assesses changed files before a PR. The memory loop (save-result → update → reflect) turns settled questions into graph nodes — curated, on top of the automatic learned edges (see Memory and learning). The global graph merges many repos into one queryable store, unifying shared external symbols across repos.

Excluding files

Place a .astriaignore file in your project root (gitignore syntax) to exclude files from the graph.

Where the token savings come from

Every run and update prints a size comparison: corpus tokens (from the file manifest) versus the tokens a graph query returns, measured over five fixed questions. The historical v0.8.0 run measured about 333,000 corpus tokens versus 3,000 per query on this repository. That ratio describes delivered text size; it does not measure savings against targeted source search or establish answer correctness. On tiny corpora it may be below 1×.

Numbers vary per run and per corpus. See Benchmarks and evidence for the historical measurements and Retrieval validation for paired file recall, symbol retrieval, budget, and latency results.