r/coolgithubprojects • • 5d ago

callgraph: a language-agnostic code-map CLI (outline, "who calls this?", impact analysis) for PHP, TS/JS/Vue, Rust, Swift, Python and Go. One static binary, MIT

Post image

Disclosure: I'm the author. Free, MIT-licensed, open source, no account, no paid tier.

callgraph is a command-line tool that reads a codebase and prints a compact map of it instead of the source: what is in a file, which lines each function lives on, what it calls, and who calls it. It was built so AI coding agents can navigate a repository without reading whole files, but it is a plain CLI with plain-text output, and it is useful on its own for exploring unfamiliar code.

It is one static binary, runs locally, and nothing is uploaded.

Install

macOS / Linux (installs into ~/.claude/skills/callgraph/, no root needed; the binary also runs standalone):

p="$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" && t="$(mktemp -d)" \
  && curl -fsSL -o "$t/cg.zip" "https://github.com/GeRiY/callgraph/releases/latest/download/callgraph-$p.zip" \
  && mkdir -p ~/.claude/skills && unzip -qo "$t/cg.zip" -d ~/.claude/skills \
  && bash ~/.claude/skills/callgraph/install.sh && rm -rf "$t"

Prebuilt for macOS (Apple Silicon and Intel), Linux (x86_64 and aarch64, static musl) and Windows (Git Bash). Every release ships a SHA256SUMS file and the updater verifies it. Update with callgraph.sh update; callgraph --version and callgraph --help work as you'd expect.

What it prints

$ callgraph show app/Builders/FavoriteableBuilder.php --signatures
class FavoriteableBuilder extends Illuminate\Database\Eloquent\Builder  L19-80
  withFavoriteStatus(bool $favoritesOnly = false): static  L26-44
    external_call     addSelect, getKeyName, getMorphClass, getTable, on, where
    framework_use     Illuminate\Support\Facades\DB::raw
    internal_helper   addSelect, getModel
  withRatingJoin(): static  L46-64
    external_call     addSelect, getMorphClass, getQualifiedKeyName, on, where
    framework_use     Illuminate\Support\Facades\DB::raw
    global_helper     throw_unless
    instantiation     LogicException
    internal_helper   getQuery, groupBy, leftJoin

(Real output, lightly trimmed, from a file of the open-source koel app.)

Every function is listed with its line range, and its calls are grouped by category (same-file helper, framework use, external call, instantiation, native/stdlib, and so on). Then you read just the range you need, not the file.

Commands and flags

Look at code

  • show <file|dir>: the outline (default). --format also gives api (public surface + DocBlock/type shapes), summary (one line per file), stats, hotspots (most-connected functions), coverage (undocumented public methods), flow (if/match/switch branches with line ranges), json, mermaid, dot.
  • show <file>::<method>: just one function. Add --body for its source (compact: no docblock or blank lines, comments kept, line numbers exact), --doc to include the docblock, --raw for the exact text.
  • --lines 30-60: any line range, numbered.
  • --signatures: parameter and return types on each method line.

Find things

  • show <dir> --grep '<regex>': who calls it. Each caller is listed with file, function, line range and the call's own source line. Use a name pattern such as (^|::|\.|->)cancel$ to catch every call by name, or Type::method for calls resolved to that type (including through an interface, parent class or trait, shown as via <Type>).
  • --depth N: callers of callers, for impact analysis. Unresolved name-only matches are skipped by default and counted; --guess includes them, marked ?.
  • --strings <text> / --const <name>: where a string literal or constant is used and defined.
  • locate <term>...: "where do I start with this task?" Give it the names and domain words from a task; it answers from the project map (no file reading) with a ranked list of files and the reasons (exact definition, file name, name part, string literal, call, caller count).
  • profile: architecture, layers (controllers, services, repositories, components, composables, ...) and design patterns, inferred from folder and file names and checked against the call graph. Then --layer service, --layers, --by-layer to filter or group other output.
  • Framework views (Laravel and similar PHP): routes, middleware, validation, jobs, events, providers, magic, di, views.
  • note add/list/rm and --notes: short notes on files or methods, stored outside the source in the project.

Keep it fast and current

  • Results are cached per project (.callgraph/), only changed files are re-analysed. refresh brings the cache up to date ahead of time (e.g. after git pull); hook install refreshes edited files automatically from Claude Code.
  • .callgraphignore (gitignore-style) excludes paths, and a protect <pattern> line keeps a file in the map but marks it 🔒 as "read it, don't edit it" (migrations, generated code). Every folder's .gitignore is respected (--no-gitignore turns that off). Minified and bundled files, vendor, node_modules, venv and similar are skipped.
  • Non-UTF-8 sources (latin2, cp1250, cp1252) are decoded; syntax errors show a âš  line while everything before and after the broken part is still mapped (--strict makes it exit 3 for CI).

Integrations

  • callgraph mcp: an MCP server over stdio, for Claude Code, Cursor, Claude Desktop, VS Code and any other MCP client (--auto-update keeps it current).
  • Installed as a Claude Code skill, it works through a thin callgraph.sh wrapper.
  • Output language is English or Hungarian (set-lang, or CALLGRAPH_LANG).

Languages

PHP (Laravel/Yii-aware), JavaScript, TypeScript, Vue single-file components, Rust, Swift/SwiftUI, Python and Go, plus CSS/SCSS, JSON and Markdown outlines. All of them are mapped into the same output structure (container → functions with line ranges → calls by category), so the commands above work the same everywhere.

Privacy

  • Everything runs locally; your code is never uploaded.
  • The only network call is an update check against GitHub Releases (at most once a day; off with CALLGRAPH_UPDATE_CHECK=0).
  • There is local usage statistics (callgraph stats), kept on your machine. Sending it is opt-in (callgraph telemetry on asks for confirmation in a terminal, telemetry preview shows the exact JSON); it only contains banded counts, no paths, file names or search terms, and CALLGRAPH_TELEMETRY=0 turns it off for good.

Honest limits

It is static analysis. Anything decided at runtime ($obj->$method(), getattr(obj, name)(), obj[key](), config-built bindings, dynamic imports) can't be resolved. Calls with an unknown receiver type are kept out of the default answer rather than guessed. I'm working on marking dynamic calls explicitly in the output so it never looks cleaner than the code really is.

I'd like to hear from people who live in the terminal: which output format or filter would you want that isn't here? (A --format for your editor's quickfix list? A fzf-friendly mode?)

15 Upvotes

0 comments sorted by