Coding agents tend to enter an unfamiliar repository the same way.
It lists the root. Reads the README. Searches for framework markers. Opens an entry point. Searches a service name. Opens three more files. By the time it understands the subsystem, a lot of unrelated text has passed through the context window.
Source files are the final authority, so this isn’t inherently bad. It is still a wasteful opening for questions the project graph can answer first. Scry gives the agent a graph report before it starts opening likely-looking files.
Build the map before the session
Scry’s graph builder reads the repository’s existing code, git, schema, HTTP, and coverage indexes. It creates typed nodes and edges in BadgerDB, then computes a report.
The report includes:
- High-degree nodes, which are functions or files with many graph connections
- Architectural communities found through Louvain clustering
- Cross-domain relationships that may be worth inspecting
- Suggested queries based on the graph currently available
No LLM reads the repository to produce this report. That would be slower, cost money on every rebuild, and make it difficult to tell why two nodes were connected.
Structural analysis produces clunky labels sometimes. That is fine. The report only needs to route an agent toward the right part of the repository.
Communities provide a rough architecture
A directory tree reflects how files are organized. A graph community reflects which nodes are densely connected.
Those often overlap, but not always. A feature may span an HTTP handler, a service, a queue worker, two tables, and tests across several directories. If those nodes call, query, and test one another more than the rest of the repository, community detection can group them.
Scry labels communities conservatively from their nodes and path prefixes. On some repositories the result is a recognizable subsystem. On others it is “internal/memory” or simply a file cluster. I would rather have an awkward deterministic label than ask a model to invent a clean architecture name the code doesn’t support.
The agent can inspect the nodes and decide what the cluster means.
High degree doesn’t mean important
Graph reports call the most connected nodes “god nodes,” borrowing a common graph-analysis term. The name is a little dramatic.
A high-degree node may be central application logic. It may also be a registry, generated file, test helper, or dependency manifest that touches everything for mechanical reasons.
The report is a lead, not a severity score. An agent should ask why the node has a high degree before recommending a refactor.
The report includes the edge types behind the degree. Ten call edges mean something different from ten co-change edges, especially when deciding whether a file is central or merely edited often.
Paths narrow the files worth reading
Once the report identifies the likely subsystem, the agent can ask for a path between two named nodes.
For a code-to-schema question:
scry graph path OrderController orders
For an unfamiliar symbol, it can use references or callers directly. For a historical question, it can inspect intent and co-change. For a runtime failure, it can start from captured requests.
The path isn’t a substitute for opening the implementation. It gives the agent a reason to open two files instead of guessing at eight.
Large models can hold a lot of code, but I still see better edits when the context contains the two relevant files instead of eight plausible ones.
Hooks can nudge, but not decide
Scry can install a pre-search hook in Claude Code. Before a broad Glob or Grep operation, the hook checks whether a graph report exists and returns a short reminder that graph context is available.
The hook doesn’t block search. It doesn’t try to rewrite the agent’s tool call. It gives the model a chance to use the index it otherwise forgets exists.
Global agent instructions provide the rest of the routing:
- Use Scry first for named symbols and relationships.
- Use graph reports when entering an indexed repository.
- Use text search for strings, comments, documentation, and index gaps.
- Check repository status before interpreting an empty result.
Tool availability alone didn’t change behavior consistently. Agents need a small amount of repeated guidance about which questions the tools answer.
Index health belongs in the answer
Graph-first exploration becomes dangerous if a missing index looks like an empty graph.
Scry reports four meaningful states. A ready index matches the repository’s current commit. A stale index was built against an earlier commit. An empty indexer completed but produced no symbols for a detected language. A partial index means one language failed while others succeeded.
These states are derived from the stores and repository at query time. They aren’t optimistic flags written during an earlier successful build.
An agent that sees partial can use the working domains and fall back to source search for the missing language. It shouldn’t conclude that the missing references don’t exist.
Read the relevant part deeply
Graph-first work isn’t about avoiding source code. It changes when source enters the session.
The agent first gets a small structural view, identifies the relationship it cares about, and then reads the implementation with a concrete question. That usually produces better edits than loading a broad slice of the repository and hoping the model notices the right connection.
There are still tasks where the graph contributes almost nothing. Editing copy, tracing a dynamically generated configuration key, or understanding a novel algorithm may begin with normal search and reading.
Scry makes the common reconnaissance path cheaper. Copy edits and dynamically generated configuration still begin with normal search, and that is fine.