What is a Code Graph (and why your AI needs one)

A code graph is a structured map of your project's symbols and the relationships between them — who calls whom, what depends on what, which files always get edited together. It is the kind of mental model a human builds before refactoring. For an AI agent still doing grep -r to find anything, it is the missing layer.

Here is why that matters in practice.

A small disaster

Last week I added a new slash command to Cockpit. Code change was four lines. I tested it. Worked. Committed. Pushed.

Next morning a teammate messaged: "I can't see it in the autocomplete menu though?"

The new command had to be registered in two files. One for the prompt expansion, one for the menu listing. They don't import each other. They don't share a function. They just have to stay in sync — a convention nobody documents, that the codebase enforces nowhere.

Before I made that change, I had asked the agent: "If I change this function, what else needs updating?" It ran grep, found five callers, summarized them confidently. The menu file wasn't a caller. grep couldn't see the relationship. Neither could the agent.

Why grep is the agent's ceiling

When an AI agent is just driving grep, it inherits grep's blind spots:

• Relationships are invisible. grep knows the string createOrder shows up 12 times. It does not know which of those are calls and which are comments, tests, or unrelated strings.
• Conventions are invisible. Two files with the same constant — one defines it, one mirrors it — look like two unrelated occurrences. grep cannot encode "these must stay in sync."

Most AI exploration runs on grep because most code questions are simple lookups. The 10% that aren't are exactly where you needed the help most.

What a code graph gives the agent

/cg is the slash command. Type it in any Cockpit chat:

/cg if I rename createOrder, what breaks?

You did not learn a new tool. You did not install anything. You typed three letters. The agent now answers as if it had just spent an hour reading the codebase.

Six question shapes get sharper answers:

The last one is the one that would have saved me.

The story, replayed

I redo the change with /cg:

"If I add a new slash command in this file, what else do I need to touch?"

The agent ran the usual call-graph queries, then ran one more — "what files commonly get edited together with this one?" — and came back with:

"Direct callers are five chat routes; signature is stable. One caveat: commands.ts in the same module gets edited together with this file in most recent commits. If your change adds a new command verb, you probably need to register it in commands.ts too — looks like a parallel menu list."

Three lines. The whole future-bug fix.

Code Map for your eyes, CodeGraph for the agent

If you have used Cockpit's Code Map, you have already seen the human side of this. Code Map renders the same project structure as clickable chips — function callers on the left, callees on the right — so you can walk the call graph in five clicks.

CodeGraph is the same idea, made queryable. Same tree-sitter index, same call graph, same git history. Code Map serves it to your eyes; CodeGraph serves it to your agent.

Same fact, two consumers.

What it doesn't do

/cg is not a fixer. It does not reach into config files, JSON, or unstructured docs — for those, regular grep is still the right tool. And if you already know which file to edit, just Edit it; you don't need an exploration mode.

But the moment your question contains the words "what else" or "who depends on" — that is when the gap between grep and a code graph shows up.

Try it

In any Cockpit chat:

/cg

That is the entire onboarding. Try it on a function whose impact you don't fully understand. The agent will tell you something you would not have found on your own.

---

npm i -g @surething/cockpit · GitHub · Try Online