When an AI coding agent needs to change one method, it usually reads the whole file first. Then the next file. Then it greps, and reads a few more.
Most of those tokens are spent on finding the way, not on the task.
I built callgraph to give the agent a map instead: the structure of a file, every call labelled by kind, who calls a method across the project, and only then the one method body it actually needs.
What the agent sees
Take a 400-line Laravel service. Instead of reading all of it, the agent asks for the outline:
$ callgraph.sh app/Services/OrderService.php
class OrderService L30-412
constants (1):
MAX_ITEMS = 100
properties (7):
OrderRepository $orders [readonly]
PaymentService $payments [readonly]
…
updateOrders() L44-109
framework_use Illuminate\Support\Facades\DB::transaction
internal_helper updateOrder
model_use App\Models\Order::query
static_call App\Values\OrderUpdateResult::make
💬 A single-order update keeps the old values of empty optional fields.
…
Every method with its line range, and every call grouped by what it is: ORM / model use, framework facade, internal helper, static call. The comments that explain intent stay. If the agent needs the code of one method, it asks for exactly that: callgraph.sh app/Services/OrderService.php::updateOrders --body.
"Who calls this?"
Before changing updateOrders, the agent wants to know what depends on it:
$ callgraph.sh app --grep '(^|::|\.|->)updateOrders$'
app/Http/Controllers/OrderController.php
class OrderController L18-80
update() L45-66
L52 │ $result = $this->orderService->updateOrders($request->orders, $request->toDto());
The caller, its line, and the call itself — no file read needed. --depth 2 follows the chain one level further (impact analysis), and calls through interfaces, traits and parent classes are found too.
"Where do I start?"
For a task description, locate takes the names and words from it and ranks the few files worth opening first, each with the reason:
$ callgraph.sh locate CheckoutController applyCoupon coupon
1. app/Http/Controllers/CheckoutController.php ★★★
class CheckoutController L16-74 ← "CheckoutController" (exact class)
apply() L38 calls CouponService::applyCoupon ← "applyCoupon" (call)
2. resources/js/types.d.ts ★
interface Coupon L120-131 ← "coupon" (exact interface)
…
And for an unfamiliar project, callgraph.sh profile describes the architecture in about 15 lines: which folder holds which layer (controllers, services, models, Vue components, stores…), the patterns in use, and the direction the layers call each other.
How it works
- AST analysis, not regex: PHP (Laravel, Yii), JavaScript / TypeScript, Vue, Rust and Swift, plus CSS / SCSS, JSON and Markdown outlines.
-
A project map in
.callgraph/, updated file by file, so "who calls this?" across a large project is answered from one read. - Local and read-only. Your code never leaves your machine. No PHP, Node or Rust toolchain needed: it is one static binary for macOS, Linux and Windows.
- Three ways to use it: a Claude Code skill, plain CLI from any terminal, or an MCP server for Cursor, VS Code, Claude Desktop and any MCP client.
- Honest about gaps: a file with a syntax error is still outlined up to the broken part, and the output says so instead of silently returning nothing.
Try it
# download the package for your OS from https://callgraph.eu/ , unzip, then:
bash callgraph/install.sh
bash ~/.claude/skills/callgraph/callgraph.sh --version
The installer can also register the MCP server for Claude Code. Setup recipes for Cursor, VS Code and Claude Desktop are on callgraph.eu/mcp.
Free and open source (MIT): github.com/GeRiY/callgraph
How does your agent find its way around a large codebase today? I'd love to hear what works for you — and which languages or frameworks you'd want next.
Top comments (12)
Agreed on where the tokens go: 412 lines read versus a 12-line outline is the right trade. The catch I'd watch is staleness, since once the agent edits OrderService mid-session the line ranges in the map drift. Does callgraph re-index on file change, or on each query?
Good catch — staleness is the first thing that bites with any code map. Both, actually:
callgraph.sh refreshdoes the whole project after a git pull.A file with a syntax error mid-edit is still outlined up to the broken part, and the output says so ("⚠ syntax error at L…") instead of silently returning stale or empty results.
Checking mtime + size per query instead of a full rescan is the right trade. The one case it can miss: a restore that keeps timestamps (rsync -t, cp -p, tar) or a same-size rewrite inside the filesystem's 1 s granularity. Do you fall back to a content hash anywhere, or is the post-pull refresh enough in practice?
Fair point. Two details: the stamp is the nanosecond mtime plus size (on ext4, APFS and NTFS, so the 1 s window mostly doesn't apply), and there's no content hash yet — so a timestamp-preserving restore that keeps the same size is exactly the case it would miss. In practice that's rare in an agent session, and deleting .callgraph/ rebuilds the map quietly on the next query. A cheap content-hash check for files whose stamp matches but that were touched by a restore is a good idea — I've noted it.
Thanks, the nanosecond stamp settles the 1 s worry. One cheap step before a content hash: add ctime to the stamp, since cp -p, rsync -t and tar can put mtime back but setting it bumps ctime, which userland can't set back (Linux and macOS at least; on Windows ctime means creation time). Have you seen branch switches in big repos trigger a lot of re-analysis?
Thanks, the nanosecond stamp closes most of the gap I had in mind. For the restore case there may be an option cheaper than hashing: ctime. On ext4 and APFS the kernel sets it on every write or metadata change, and tools like cp -p or rsync -t can restore mtime but cannot set ctime, so storing it next to mtime and size flags those restores without reading the file. Would that fit how the stamp is stored today?
Thanks, everyone, for the comments. Several of these requests made it into callgraph v0.7.0, released today:
rsync -t,cp -p,tar) is now detected. Windows keeps mtime + size, since its ctime is the creation time. I left out a content hash for now, because ctime covers that case.--signaturesflag prints the parameters and the return type on the method line (PHP, Rust, Swift, and TS/Vue now too), and the api view also shows the PHP DocBlock@return/@paramshapes. Python and Go are on the list; they need a new language analyzer, so I won't promise a date yet.protect <pattern>line in.callgraphignore(e.g.protect migrations/): a protected file stays visible and searchable, but gets a 🔒 marker, and the agent instructions say to read it, not edit it.Update with
callgraph.sh update. If anything doesn't behave the way you expected, tell me.The low-effort version that works for me is a short map file in the repo: one line per folder saying what lives there, plus where the shared helpers are. The agent reads that first and only opens the files it points to. Keeping it to a page matters, because a long map gets skimmed just like a long codebase.
That works well — and it's close to what
callgraph.sh profilegenerates: about 15 lines with which folder holds which layer, the patterns in use and the call direction. The difference is it's computed from the code, so it can't drift when someone moves a folder and forgets the map file. A hand-written note on top (the "why" a folder exists) is still worth keeping.Computed beats hand-written for the what, agreed. The part I'd still keep by hand is the short do-not-touch list: generated folders, vendored code, migrations that must never be edited. A code map can tell the agent where things live, but not which parts it should leave alone, and that's where most surprise edits come from.
Extracting an AST outline instead of dumping whole source files cuts token bloat dramatically. Where we see agents struggle with compact outlines is dynamic dispatch and generic repository wrappers: if an outline lists
updateOrders()calling$orders->update(), the agent knows the call exists but lacks the parameter shape or return type.Without that local contract in the outline, the model frequently guesses the payload structure before invoking
--body. In our document ingestion and pipeline agents, pairing the method entry with its concise type signature (or DocBlock return shape) gives the agent enough context to decide if it even needs the method implementation.Python and Go support would be great additions next, especially given how common AST inspection is across CLI tools and microservices.
Agreed — the call edge alone isn't enough to decide whether you need the body. Part of this already exists:
--format apiprints the full signature with parameter and return types for PHP, e.g.updateOrders(array $ids, OrderDto $dto, bool $notify = false): array L4, so the agent can check the contract without the body.Two gaps you've made me notice: TypeScript return types aren't shown there yet, and a DocBlock
@return array{...}shape isn't surfaced at all — both are going on the list, along with an option to put the compact signature right on the outline line. Python and Go are the most requested next languages; noted.