@nodesify/astria

Turn any folder into a queryable knowledge graph.

Install

npm install -g @nodesify/astria

Requires Node.js >= 22. No Rust toolchain needed — ships prebuilt native binaries for macOS, Linux, and Windows.

Usage

astria run <path>                            # Full pipeline: detect → extract → build → cluster → analyze → report
astria update <path>                         # Reuse cached extraction; reconcile current corpus
astria watch <path> [--debounce 3000]        # Watch for file changes, auto-rebuild
astria explain <node> [--graph .]            # Explain a node and its connections
astria query <question> [--dfs] [--depth 2] [--budget 2000] [--graph .]  # BFS/DFS traversal
astria path <A> <B> [--graph .]              # Shortest path between two concepts
astria stats [--graph .]                     # Node/edge/community counts
astria export [--graph .] [--out graph.json] [--format json|html|graphml] [--mode standard|large] # Export graph; HTML defaults to standard
astria merge <pathA> <pathB> <outPath>       # Merge two graphs
astria diff <pathA> <pathB>                  # Compare two graphs
astria history [--limit 20] [--graph .]      # Show recent query history
astria install [--platform claude]           # Install skill files for AI coding assistants
astria hook install                          # Install git post-commit/post-checkout hooks

Running astria run . creates .astria/ with:

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

Retrieval and upgrades

Scoped code definitions survive semantic deduplication. JS/TS assigned functions retain binding names and bodies; Python implementations take precedence over overload declarations. Queries favor complete identifiers while honoring explicit requests for tests or documentation. Static receiver matching does not infer runtime types or aliases.

query --budget N caps the full query text using o200k_base, including metadata. CLI and MCP share that text budget; MCP transport JSON is excluded. Budgets must fit metadata and the next complete record or the query returns an error. Use the returned --cursor N for the next page of node and edge records.

After upgrading, run astria update . to refresh extraction and restore definitions removed by older deduplication. Discard old pagination cursors after an upgrade or graph rebuild.

HTML visualization modes

HTML export defaults to --mode standard, matching the original Graphify viewer's 5,000-node safety limit. Graphs above that limit require an explicit large-graph export:

astria export --graph . --format html --mode large --out graph-view.html

Large mode uses precomputed positions and disabled physics, starts with key nodes visible, and provides debounced search plus a “Show all nodes” toggle. The --mode option only affects HTML export; JSON and GraphML remain unchanged.

Supported languages

Python, JavaScript, TypeScript, Rust, Go, Java, C, C++, Ruby, Swift, Kotlin, Scala, PHP, C#, Lua, Haskell, Elixir, Bash, Dart, Zig, CSS, Terraform/HCL, PowerShell, Verilog/SystemVerilog, and Metal. See the generated language table for extensions and extraction details.

AI platform integration

astria install --platform claude   # or: codex, gemini, cursor, copilot, aider, opencode, kiro, trae, zcode

.astriaignore

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

License

MIT

Installation defaults to project scope: astria install --platform codex --scope project. Use --scope user explicitly for user-wide integrations. Run astria doctor after setup or upgrades. See the installation lifecycle guide for supported platforms, upgrade, backup/restore and complete removal.