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.

Complete your first change investigation

Start with structural indexing; it needs no API key:

astria run . --backend none
astria status
astria query "where is request authentication implemented"

Take an exact node ID from the answer, then run astria explain <node-id> and astria affected <node-id> before editing its implementation. Open the cited source to verify the behavior. After editing, run astria update ..

Each query node includes a retrieval reason in text and retrievalReason in structured CLI/MCP output. This describes selection evidence, not a probability that the answer is correct. Relationship confidence describes a separate fact: RESOLVED is name-derived binding; INFERRED requires additional source review. An absent relationship does not establish that no runtime dependency exists.

For compiler-backed precision, generate a SCIP index using your language's indexer, then run astria add --scip <index-file>. Run astria status after source changes: stale compiler indexes require regeneration and reimport; structural updates alone cannot restore compiler evidence. JSON status includes recommendations for automation. See the CLI reference for graph selection.

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 --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.