Skip to main content
Version: Next

Agent integration

The graph is most useful when your AI assistant reaches for it automatically. There are four integration surfaces, all local: the MCP server, skill-file installers, git hooks, and an editor-side guard.

MCP server​

astria mcp [--graph .]

Runs the MCP stdio server — ten tools for querying and assessing the graph from any MCP-capable agent. The full tool list, arguments, and example calls are in the MCP tools reference. Add it to your agent's MCP config:

{
  "mcpServers": {
    "astria": { "command": "astria", "args": ["mcp"] }
  }
}

Skill files (install)​

astria install [--platform claude] [--all]
astria uninstall [--platform claude] [--all] [--scope project|user]

Supported platforms: claude, codex, gemini, cursor, copilot, aider, opencode, kiro, trae, zcode, vscode, windsurf, cline, roo, amp, pi. --all installs (or removes) every platform in one run — multi-tool users don't need to know the flag per tool.

install writes the platform's skill files and injects an always-on ## astria instruction block into AGENTS.md / CLAUDE.md — telling agents to query the graph before grepping and to run update after edits. The instruction block names both access paths: MCP tools when the astria server is connected, or the astria CLI from any agent.

Most platforms get the astria MCP server registered automatically. Project-scoped JSON configs: zcode (.zcode/config.json), claude (.mcp.json — Claude Code asks you to approve it once), cursor (.cursor/mcp.json), gemini (.gemini/settings.json), vscode (.vscode/mcp.json — native workspace MCP, what Copilot inside VS Code uses), trae (.trae/mcp.json), windsurf (.windsurf/mcp.json), kiro (.kiro/settings/mcp.json — Kiro's documented workspace-scope config), and opencode (.opencode/opencode.json; the OpenCode freshness plugin drops into the auto-discovered .opencode/plugins/). The Copilot coding agent has no committed MCP config file — repository-level MCP for it is JSON pasted into the repository's Settings on github.com, so install --platform copilot writes the skill and instructions only. pi installs an auto-discovered extension (.pi/extensions/astria.mjs (project scope; user scope uses ~/.pi/agent/extensions/)) that registers the graph as native pi tools (astria_query, astria_map, astria_explain, astria_path, astria_affected) — pi's own philosophy is registered CLI-backed tools over MCP definitions, which also costs far less context — plus graph-refresh after write/edit and an /astria guidance command. Users of the pi-mcp-adapter extension additionally get the standard .mcp.json tools it reads. Codex project setup uses .codex/config.toml; --scope user selects ~/.codex/config.toml. Installation appends a managed [mcp_servers.astria] table in the selected scope — never touching a hand-written one. The ten tools (repo_map, query_graph, explain, get_neighbors, shortest_path, affected, god_nodes, list_communities, graph_stats, health) then appear natively in every session for that project. Setup preserves unrelated configuration. uninstall removes integrations in its selected scope and retains shared resources needed by other recorded platforms. See installation lifecycle for scopes, diagnostics, upgrades, backups and removal.

Rerun install in the same scope after upgrading to refresh managed instruction blocks. Customized standalone files are retained and require manual resolution before proceeding.

Install just the skill (skills.sh)​

npx skills add Nodesify/astria

The repo's canonical skill - skills/astria/SKILL.md - is indexed on skills.sh, so any coding agent can pick it up without astria being installed. The skill is self-contained: on first use it checks for the CLI (astria --version); if it is missing but .astria/ exists, it answers from the exported report and wiki as plain files; if there is no graph either, it offers the npm install -g @nodesify/astria install before doing any graph work - it never installs unprompted. astria install (below) remains the richer path for CLI users since it also wires MCP configs, hooks, and AGENTS.md blocks per platform.

Claude Code plugin​

In Claude Code, install the bundled MCP server, graph-first skill, slash commands and architect subagent:

/plugin marketplace add Nodesify/astria
/plugin install astria@nodesify

The plugin includes /astria and /astria-risk; its MCP configuration runs the installed astria mcp CLI. See the repository's plugin manifest and MCP Registry metadata.

Docker and HTTP MCP​

Build the repository's container image, then analyze or query a mounted checkout:

docker build -t astria .
docker run --rm -v "$PWD":/workspace astria run /workspace
docker run --rm -v "$PWD":/workspace astria query "auth flow" --graph /workspace

To serve MCP over HTTP on port 8620, set ASTRIA_MCP_TOKEN to your access token and pass it to the server:

docker run --rm -p 8620:8620 -v "$PWD":/workspace \
  astria mcp --http --host 0.0.0.0 --token "$ASTRIA_MCP_TOKEN" --graph /workspace

Binding a non-loopback address requires a token. Command flags, client authentication and origin settings are documented in the CLI reference.

Git hooks​

astria hook install|uninstall|status

Installs post-commit, post-checkout, and post-merge hooks. Relevant changes run update . --quiet; the hooks do not apply a time-based skip. Post-merge checks the complete ORIG_HEAD..HEAD range, so a fast-forward pull includes changes from every incoming commit. Changed graph inputs, including project configuration, can trigger a refresh. Indexing does not run token benchmarks automatically. Errors never break the Git operation. Re-run astria hook install after an upgrade to refresh the installed scripts.

Who should install them: anyone whose AI assistant queries this repo's graph — that's the workflow where staleness silently produces wrong answers. Casual CLI users can skip them without losing anything; status still flags a stale graph, and a deliberate astria update . refreshes on demand. Hooks are per-machine and per-checkout (only runs on machines where you ran astria hook install), and uninstall removes them cleanly.

Editor guard (hook-guard)​

astria hook-guard <mode>    # search | read | gemini

The editor-side companion to git hooks: a PreToolUse hook installed into .claude/settings.json that nudges agents toward query before raw searches. Modes:

  • search — intercepts grep-style calls (the Grep tool, or grep/rg/ag/git grep in Bash) and injects a mandatory nudge to check the graph first
  • read — additionally watches source-file reads: when a file is newer than the graph build, it warns that the graph is stale and to run update before trusting answers
  • gemini — compatibility mode for Gemini CLI, whose BeforeTool hook only understands allow decisions — there the guard installs but cannot nudge

Strict mode (opt-in, via --strict or ASTRIA_HOOK_STRICT=1) additionally denies one un-indexed read per session until the agent orients with a graph query (query/explain/path); after that, reads proceed uninterrupted for ASTRIA_HOOK_STRICT_TTL seconds (default 1800 — 30 minutes). The guard always fails open: any error means the tool call proceeds untouched. See Environment variables.

The intended loop​

  1. install once per repo — agents learn the graph exists.
  2. Agents query/explain/affected instead of grepping (see MCP tools reference).
  3. Git hooks (or watch) keep the graph fresh after edits.
  4. Repeated queries compound into learned edges — see Memory and learning.