Svarupa for Agents: Give Your Coding Agent a Verified Map

Ask a coding agent how authentication reaches the database in a repo it has never seen. Watch what it does: grep, glob, read a file, grep again, read three more files. Ten tool calls later it assembles an answer from fragments — and if the fragments were misleading, the answer is wrong with complete confidence. Nothing in the loop distinguishes "I verified this" from "this looks plausible."

The first two parts of this series covered the evidence contract and using svarupa yourself. This part is about the reader I actually built the knowledge graph for: the agent. Svarupa already produces a verified graph of the repository — every node and edge anchored to a source line. The setup below hands that graph to your agent, so its architecture answers come with citations instead of confidence.

The setup

Three commands, in order:

uv tool install svarupa        # pipx / pip work too
svarupa .                      # build .svarupa/ from the repo (graph.json inside)
svarupa setup skill            # install the agent skill into .claude/skills/svarupa/

The skill teaches the agent when to regenerate the report and how to consult it. The graph itself is served two ways, depending on how your agent connects:

svarupa mcp .svarupa                                # stdio — local agent integration
svarupa mcp .svarupa --transport streamable-http    # http — shared or remote setups

For an MCP client, the config shape is the usual one (shown as an example — check your client's docs for the exact file location):

{
  "mcpServers": {
    "svarupa": {
      "command": "svarupa",
      "args": ["mcp", ".svarupa"]
    }
  }
}

That is the whole integration. No daemon to babysit, no account, no hosted service — the server reads the artifact directory you generated.

Seven functions, by agent moment

The MCP server exposes the same seven query functions as the CLI. What changes is who calls them and when. This is how I map them onto the moments an agent actually hits:

A coding agent querying the verified svarupa knowledge graph over MCP, with the grep-and-guess path blocked — The agent reaches the 7 query functions over MCP (stdio or streamable-http); answers return with file:line citations — grep-and-guess stays blocked.
Read diagram description
A coding agent connects to the svarupa MCP server over stdio or streamable-http. The query layer of 7 graph query functions matches labels exactly and lists ambiguity rather than guessing, reading the verified knowledge graph in graph.json where every node and edge carries file:line evidence. The answer returns to the agent with citations attached. The alternative path — grep-and-guess producing a fluent but unverifiable answer — is shown as blocked. This is an illustrative sketch, not a deployment topology.
View full-size diagram(opens in a new tab)

Explore it live: adaptive-rag — diagram report · graph · document-extraction-pipeline — diagram report · graph

graph_stats — orientation. First contact with an unfamiliar repo: how many nodes, edges, modules. The agent learns the size of the territory before wandering it.
get_node — evidence on demand. One node, with the exact file:line references that back it. This is the citation the agent pastes into its reply.
get_neighbors — local structure. What does this module touch, one or two hops out (--depth), optionally filtered by --relation.
shortest_path — "how does X reach Y?" The question grep answers worst. The graph answers it as a path, with evidence per edge.
affected — blast radius, before editing. Three hops by default. This is the call I care about most: the agent checks what breaks before it changes the function, not after the tests fail.
god_nodes — hotspots. Highest fan-in/fan-out. Where a change is expensive, where the architecture is load-bearing.
query_graph — the budgeted answer. A natural-language-ish query with --budget in tokens, returning a subgraph sized for the context window. The agent spends its tokens on the task, not on re-reading the repo.

Two properties matter more than any single function. Labels match exactly — id, qualified name, or label — and ambiguous matches are listed, never guessed, so the agent cannot silently anchor on the wrong node. And every result carries evidence, so the agent's final answer can end with the lines that prove it.

A real workflow

Concretely, against the public adaptive-rag repo (268 nodes, 422 edges — the live report is here). The task: "change the retry behavior in the pipeline." A grep-driven agent starts searching for the word "retry". A graph-driven agent starts differently (commands shown as the CLI equivalent of the MCP calls; output abbreviated):

# 1. Find the node it means — exact or listed, never guessed
svarupa query .svarupa get_node "rag.pipeline"

# 2. Blast radius before touching anything
svarupa query .svarupa affected "rag.pipeline"
# api.routes, eval.runner, scripts.backfill — 3 hops, each with file:line

# 3. How the change surface connects to the outside
svarupa query .svarupa get_neighbors "rag.pipeline" --depth 2 --relation imports

Now the agent edits with the full impact surface in context, and its summary can say "this affects api.routes (evidence: app/api/admin.py:9)" — a claim you can click. The difference is not speed; it is that the answer is auditable.

Where I would not use it

If the repo moves and the graph doesn't. The graph is a snapshot, truthful about the moment it was generated. On a fast-moving repo, regenerate before trusting it — the installed skill exists partly to make that a habit. A stale verified map is still a map of the past.

If your code isn't Python or TypeScript/JavaScript. Two extraction languages today, with pinned grammars. A polyglot service gets a partial map — svarupa will say exactly how partial, but partial is partial.

If you want the agent to stop thinking. The graph answers structural questions with evidence. Judgment — whether the change is a good idea, whether the architecture should look like this — stays with the agent and with you. A verified map makes an agent more honest, not more wise.

If you try it

uv tool install svarupa, then svarupa . in a repo your agent works on
svarupa setup skill and confirm the skill lands in .claude/skills/svarupa/
Wire svarupa mcp .svarupa into your agent's MCP config
Give the agent one task that starts with affected — compare its answer to the grep-and-guess version
Put the regeneration step where the agent will trip over it (session start, pre-commit, CI)