Agent Graph Work Tree
For Claude Code, Codex, Cursor and GitHub Copilot

A code graph your agent can actually ask

Generated into your work tree from the source, with no language model in the loop. Agents run one command to learn who calls a method, what extends a class or what a change touches, instead of opening dozens of files.

InstallView on GitHubRead the evaluation
./install.sh --repo ~/code/my-project
Source files go through extractors to claims, then a graph, then the kg command and notes for agents

What it gives an agent

Three things a grep loop does badly, each one command.

Precise answers

Callers, dependents, routes and tests, each with a file and line to open. Java call links match compiled bytecode on 13,380 of 13,380 high-confidence claims.

Whole hierarchies

kg subclasses returns every subclass or implementer at any depth, optionally filtered to those that override a method.

Honest labels

Every line is tagged [high] or [medium], and agents are told the source wins when a generated line is wrong.

Examples from real repositories

The diagrams below are drawn from the actual graph.json of each project, and the terminal output is what kg printed. Long package names are shortened with an ellipsis.

Routes, the controllers that handle them and the repository they use. Every edge in the diagram is [high]: written in the source.

Java example diagram generated from the real graph
Diagram drawn from the real graph.json of Spring Petclinic.
$ kg routes owner
route:GET /owners  -> …owner.OwnerController#processFindForm  view=owners/findOwners [high] view=owners/ownersList [medium] redirect=redirect:/owners [high] redirect=redire…
route:GET /owners/find  -> …owner.OwnerController#initFindForm  view=owners/findOwners [high]  …/owner/OwnerController.java:89
route:GET /owners/new  -> …owner.OwnerController#initCreationForm  view=owners/createOrUpdateOwnerForm [medium]  …/owner/OwnerController.java:72
route:GET /owners/{ownerId}  -> …owner.OwnerController#showOwner  view=owners/ownerDetails [high]  …/owner/OwnerController.java:178
$ kg callers findByLastNameStartingWith
  [medium] calls method:…owner.OwnerController#findPaginatedForOwnersLastName  …/owner/OwnerController.java:145)
  [medium] calls method:…owner.OwnerControllerTests#processFindFormByLastName  …/owner/OwnerControllerTests.java:193)
  [medium] calls method:…owner.OwnerControllerTests#processFindFormIgnoresSurroundingWhitespace  …/owner/OwnerControllerTests.java:202)
$ kg tests OwnerController
  [high] tests type:…owner.OwnerControllerTests  …/owner/OwnerControllerTests.java:60

Knowing what to trust

A graph that is sometimes wrong is only useful if the agent knows which parts. Each fact carries a tag, and the installer's instruction block tells agents how to treat each one.

[high]

Written in the source: a declaration, an import, an annotation, a literal path, a config entry.

[medium]

Derived by a fixed rule, such as a call target resolved from a declared type. Open the cited line before relying on it.

[low]

Reserved for claims written by a model. The format supports it; the installer never produces it.

Why it matters: on a repository whose code had drifted from its notes, unlabelled generated notes misled agents in 8 of 24 runs. With a tag or the trust-the-source instruction it was 1 of 108.

Install

Needs git and Python 3.10 or newer. Run it once per repository, then commit the result.

  1. Copies the generator to ~/.local/share/agent-graph with its own virtual environment.
  2. Generates .agent-knowledge/ for the repository.
  3. Adds a marked block to AGENTS.md, CLAUDE.md, .github/copilot-instructions.md and a Cursor rule.
  4. Installs git hooks that keep the graph fresh.
$ git clone https://github.com/meabs/AgentGraphWorkTree
$ cd AgentGraphWorkTree
$ ./install.sh --repo ~/code/my-project
# Windows PowerShell
.\install.ps1 --repo C:\code\my-project

# remove everything it added
./install.sh --repo ~/code/my-project --uninstall

Staying fresh

The graph is a snapshot, so it has to follow the code. Two layers, both optional and both reversible.

Git hooks (default)

The installer adds post-merge, post-checkout, post-rewrite and pre-commit hooks. The graph refreshes after a pull, a branch switch or a rebase, and a commit that touches source files carries its updated graph. Existing hooks are kept. Skip with --no-hooks.

GitHub Actions (--ci)

--ci check fails a pull request when the committed graph is stale. --ci sync regenerates it on pushes to main and commits it only when the claims changed. Both modes were run end to end on a test repository.

Evidence, without the gloss

The graph is accurate and agents use it. Whether it saves tokens depends on the repository and the agent.

Bar chart: tokens per question with the graph as a percentage of no graph. Java 42 percent for Codex; Python and TypeScript rows mostly near or above 100 percent.
QuestionResult
Are the facts correct?Java: 13,380 of 13,380 high and 8,947 of 8,957 medium call links match bytecode. Python: 87% of call edges whose caller ran were seen at runtime. TypeScript: 32 of 32 sampled edges correct.
Do agents use it?Yes. Claude Code, Codex, Cursor and the Copilot CLI all found and used kg from the generated instructions. 192 controlled runs gave correct answers in every arm, and a later 36-run trial added Cursor and Copilot.
Does it save tokens?It depends on the question and the agent. On a large Java repository, yes: Codex used 398k tokens against 953k. On Python and TypeScript, one-hop lookups cost the same or more. On a multi-level question (callers up to three levels away, with kg callers --depth 3), 8 runs per arm on Click: Codex 95k tokens against 255k (0.37x), Cursor 122k against 358k (0.34x), Copilot 178k against 158k (no gain). kgen route turns such results into per-agent advice.
How accurate is a repository's graph?kgen audit checks any repository against its own source text. Click: every sampled call edge is real, and 98% of bare and self. calls have an edge. Express: every sampled edge is real, but only 55% of bare and this. calls have one, and calls through untyped values such as res.send(...) in example code are missed.
Small samples (two to eight runs per cell), three or four agents and a handful of repositories. Read differences under about 20% as noise. Method, data and threats to validity are in the full evaluation.