Context Graph

Seven tools that read a codebase without cloning it.

Prerequisites

• A codebase indexed in the project’s Context Graph section — see Run an ingest.
• Admin or Developer role.

Unlike the code tools, these need no executor, no configuration and no feature flag. They are always available.

What they read

The Context Graph is a map of a codebase plus a semantic search over it, built ahead of time by ingesting the repositories. These tools query it.

Start with context_graph_apps

Every other tool takes an optional application_id, and can skip it only when the project has exactly one indexed codebase. Category: Data Pull.

Takes nothing. Returns the indexed codebases, their repositories, and the commit each one is currently analysed at — which is also how an agent cites when an answer was true.

context_graph_overview

A compact, budgeted map of one codebase: what kinds of things it contains and how they connect. Category: Data Pull.

• The agent fills: application_id, focus (centre the map on one area), char_budget
• Optional: version_id — defaults to the latest

Use it to orient before searching, so later queries name things that actually exist. The service never silently truncates: if the map will not fit the budget, it says so.

context_graph_search

Find where something is handled, by meaning rather than exact text. Category: Data Pull.

• The agent fills: query — natural language, e.g. “where is the order total calculated”
• Optional: top_k, hops, repo_alias, language, max_content_chars

Each hit comes back as code with a repo/path:start-end citation, and with the surrounding graph when hops is above zero. This is the main way to turn a bug report into a place in the code.

context_graph_slice

Everything within N hops of a node — what calls it, what it calls, what it reads and writes. Category: Data Pull.

• The agent fills: roots (node ids, file paths or names), depth, direction, edge_types
• Optional: max_nodes, version_id

direction is the useful knob: out follows what these depend on, in what depends on them, both either.

Use it after a search hit, to understand what a symbol is connected to before proposing a change.

context_graph_impact

What breaks if this changes — the blast radius, by following dependents backwards. Category: Data Pull.

• The agent fills: nodes, max_depth
• Optional: application_id, version_id

There is no equivalent among the code tools. It is also how an agent judges whether a vulnerability is serious in this codebase rather than in the abstract.

context_graph_read_file

Read the real source of an indexed file, as it was at the analysed commit. Category: Data Pull.

• The agent fills: path, start_line, end_line
• Optional: repo_alias — needed only when several repositories hold the same path, and the tool says so if it is

Search returns fragments, and a fragment is often not enough to be sure. This is the step before concluding anything about behaviour.

context_graph_changes

Which files were added, modified or removed between two indexed versions — that is, between the commits those versions pin. Category: Data Pull.

• The agent fills: from_version, to_version
• Both default sensibly, so “what changed in the latest ingest” needs no arguments

When a bug is recent, what changed is usually where to look first.

Context Graph or code tools?

They are complementary, and the division is clean.

Analysis and planning → Context Graph. No clone, no executor, semantic search, and impact analysis the file tools cannot do.

Writing, testing and releasing → the code tools. They must see the working copy including the edits an agent has made, which the graph cannot.

Common issues

• context_graph_apps returns nothing — No codebase is indexed yet. See Run an ingest.
• A tool asks which application — The project has more than one indexed codebase. Pass application_id.
• Results do not reflect a recent change — The graph is pinned to an indexed commit. Re-ingest, or use the code tools for the working copy.
• A file read asks for a repository — Several repositories in the application hold that path. Pass repo_alias.
• A search returns nothing useful — Describe the behaviour rather than naming a symbol. These tools match meaning, so “where do we capture payment” beats CaptureAsync.