--- title: "Code graphs for AI coding agents: why agents need one · Cork" description: "Why AI coding agents work better with a code graph: fewer file reads, exact callers before an edit, and a map that stays current as several agents edit." canonical: "https://corkcli.com/blog/code-graph-for-ai-coding-agents" last_updated: "2026-10-03" published: "2026-10-03" author: "Kevin Vera" --- # Code graphs for AI coding agents: why agents need one Why AI coding agents work better with a code graph: fewer file reads, exact callers before an edit, and a map that stays current as several agents edit. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 7 min read A code graph is a map of a codebase's symbols (functions, classes, types, modules) and the relationships between them: who calls what, who imports what, where each symbol is defined. AI coding agents need one because without it they rebuild that map by hand on every task, searching text and reading whole files to learn what a three-line answer would tell them, and they still miss callers that text search cannot see. With several agents on one repo, the graph also has to stay current while others are changing the code, or it becomes a confident map of a codebase that no longer exists. ## How agents find code today Most terminal coding agents explore a repository the way a new hire would with only a terminal: list files, search for a name, open the matches, follow imports, repeat. Claude Code's docs describe this loop directly. For "fix the failing tests," Claude might run the suite, read the error, "search for the relevant source files," read them, edit, and run the tests again. Its built-in tools for this are file operations and search (find files by pattern, search content with regex). That works, but every step costs something: - **Context.** Each file read lands in the context window. Claude Code's docs note that context fills up as you work and that older detail gets compacted away. - **Turns.** Finding every caller of a function by text search is several rounds of search, read, and search again. - **Accuracy.** Text search matches comments, strings, and unrelated symbols with the same name, and misses calls made through an alias, a re-export, or a method on an interface. A code graph answers the questions agents actually ask before an edit (where is this defined, what is its signature, who calls it, what breaks if I change it) without reading the files that merely contain the answer. ## What goes into a code graph You do not need a research project to get one. The building blocks are mature: - **Parsers.** Tree-sitter, in its own words, is "a parser generator tool and an incremental parsing library. It can build a concrete syntax tree for a source file and efficiently update the syntax tree as the source file is edited." Syntax trees give you definitions, signatures, and call sites per file. - **Language servers.** The Language Server Protocol "defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc." A language server resolves types and imports, so "find references" is semantic rather than textual. - **Edges.** Calls, imports, inheritance, and "defined in" links between the symbols the parser or language server found. The graph is only as useful as it is fresh. A graph built at 9am is wrong by 9:05 if an agent renamed something. ## Give your agent a graph today If you use Claude Code, the quickest step is a code intelligence plugin. These connect Claude Code to a language server through LSP, and the docs list what Claude gains: - **Diagnostics after edits**: Claude sees "a type error, missing import, or syntax error it introduced without running a compiler." - **Code navigation**: an `LSP` tool that "looks up symbols through the server instead of searching text for them." Install the language server binary first, then the plugin. For TypeScript, the docs give: ```bash npm install -g typescript-language-server typescript ``` Then, inside Claude Code: ```text /plugin install typescript-lsp@claude-plugins-official ``` Official plugins exist for C/C++, C#, Go, Java, Kotlin, Lua, PHP, Python, Ruby, Rust, Swift, and TypeScript/JavaScript, among others. Claude Code's cost guide recommends the same thing for a different reason: "A single 'go to definition' call replaces what might otherwise be a grep followed by reading multiple candidate files." Note that the docs say plugin language servers do not start in cloud sessions. Two more habits help regardless of tooling: 1. **Write the map down where agents read it.** A short architecture section in `CLAUDE.md` or `AGENTS.md` (key directories, entry points, naming rules) saves exploration on every session. Codex reads `AGENTS.md` from the repository root down to the working directory and stops adding files at 32 KiB by default, so keep it tight. 2. **Ask for callers before edits.** Prompting "find every caller of `chargeCard` before changing its signature" makes the agent do the graph walk deliberately instead of discovering breakage in the test run. ## Where a per-agent graph falls short A language server gives one agent an accurate view of the files on its own disk. With several agents, that is not the same codebase: - **Each worktree is its own world.** Agents in separate worktrees each see their own branch. If agent A renames `getUser` to `fetchUser` in its worktree, agent B's language server still reports the old name as correct. - **Uncommitted work is invisible.** Another agent's half-finished change is not in your graph until it is committed, pushed, and pulled. - **The graph does not say who is working where.** Knowing that `PaymentService.refund` has six callers is useful. Knowing that another agent is rewriting it right now is what prevents a collision. So for multi-agent work, a useful code graph has three properties beyond accuracy: it updates as any agent edits, it covers every agent's work rather than one checkout, and it is delivered to the agent before it starts searching rather than after. ## What to look for in a code graph for agents | Property | Why it matters for agents | |---|---| | Symbol level, not file level | Agents edit functions; "this file changed" is too coarse to act on | | Signatures and callers on demand | The two facts an agent needs before changing an interface | | Updates on every edit | A stale graph sends agents to code that moved | | Covers all agents' changes | Parallel agents need to see each other's renames before merge time | | Delivered up front | A briefing at the start of a task saves the search turns entirely | ## How Cork helps Cork maintains a live code graph of the repository (on cloud plans) and uses it so agents arrive informed instead of exploring. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. For this problem specifically: - **Briefing:** when an agent starts or gets a prompt, it is handed the exact signatures, callers and recent changes of the code it is about to touch, so it searches less. - **Live awareness:** when another agent renames a function or changes a signature yours depends on, your agent hears it on its next step. - **MCP tools:** `get_symbol` and `blast_radius` answer "what is this" and "what does changing it affect" for any MCP client. - **[Semantic lint](https://corkcli.com/blog/semantic-lint):** a teammate's rename or signature change becomes a lint rule your agents are checked against. Hooks in Claude Code, Codex and Cursor run this with no extra model calls. In Cork's benchmark (12 Claude Code agents at once on one repository, hard tasks), agents with Cork used 53% fewer tokens than the same agents without it. Install it once for every repo on the machine: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### What is a code graph in AI coding? A structured map of a codebase's symbols and their relationships (calls, imports, definitions) that an agent can query instead of searching and reading files to work out the same facts. ### Does Claude Code index my codebase? Out of the box, Claude Code explores with file and search tools as it works. Code intelligence plugins add language-server navigation (go to definition, find references) and diagnostics after edits. ### Is a code graph the same as embeddings or RAG? No. Embeddings find code that is similar in meaning to a query. A code graph records exact structural facts, such as which functions call which. They complement each other. ### Why does a code graph matter more with multiple agents? Because each agent's local view goes stale as soon as another agent changes shared code. A graph that updates with every agent's edits lets each one see renames and signature changes before they turn into broken builds. ## Sources - - - - - - ## Related reading - [Write gate: a check that holds an AI agent's edit before it lands](https://corkcli.com/blog/write-gate): A write gate checks each file edit an AI coding agent is about to make and holds or blocks it when it would collide with another agent's live work on that code. - [How to onboard an engineer when AI agents write half the code](https://corkcli.com/blog/onboard-engineers-ai-coding-agents): Onboard a new engineer on a codebase where AI agents write much of the code: agent instruction files, guardrails, ownership, and a first week plan that works. - [Blast radius in code: everything a change can break](https://corkcli.com/blog/blast-radius): The blast radius of a code change is the set of callers, dependents, tests and teammates' work that the change can affect, used to judge risk before editing. - [How to share context between Codex and Claude Code](https://corkcli.com/blog/share-context-codex-claude-code): Make Codex and Claude Code work from the same context: one AGENTS.md, shared MCP servers, handoff files, and live awareness when both edit the same repo. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/code-graph-for-ai-coding-agents