Getting started
Install
npm install -g @nodesify/astria
Requires no Rust toolchain on supported platforms — ships prebuilt native binaries via napi-rs. Node.js >= 22. Keep optional dependencies enabled. See installation lifecycle for supported targets, upgrades and removal.
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 databasegraph.json— full graph exportgraph_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 --scope project # Install integrations in this project
astria doctor # Verify runtime and setup
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
Indexing does not run token benchmarks automatically. The historical v0.8.0 benchmark compared 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×. Run the explicit retrieval-quality workflow in the repository to measure grounded file and declaration retrieval.
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.