CoGraph
Read your codebase like a metro map — functions are stations, calls are the lines between them. Python, TypeScript, JavaScript, Java, and C++. Click to jump to code. No configuration required.
When AI writes the code, humans need a better way to understand it. CoGraph is the situational-awareness layer for agentic development: a real-time, multi-dimensional map of what is being built in your project.
Opening this repository: the folders bloom open, src/mcp zooms in with its call lines and the
counts of calls leaving each file, hovering relPath shows what it is and what calls it, then the
same graph settling live and in the Global engine.
Watch the full 36-second version at full quality — the animation above is a shortened, lower-frame-rate cut.
Install
Quick start (30 seconds)
- Open any Python, TypeScript, JavaScript (Vue and Svelte included), Java, C, or C++ project folder in VS Code.
- Open the Command Palette (
Ctrl+Shift+P / Cmd+Shift+P).
- Run
CoGraph: Visualize Project.
The graph opens in a side panel. Click a node to jump to its definition; use the
toolbar to toggle overlays.
Features
- Static analysis, zero config — maps every function and the calls between them using each language's native tooling: Python's built-in
ast, the TypeScript compiler API, java-parser for Java, and web-tree-sitter with the official grammars for C and C++. No runtime instrumentation, no setup.
- Two layout engines — Shelf packs every open folder into its own non-overlapping frame with a slot per file and simulates only what is open (the default, and what keeps large repositories navigable); Global is the classic single force-directed graph. Dynamic | Static picks whether the layout keeps settling or is frozen where it was placed. Shelf simulations run in background workers.
- Interactive graph — zoom, pan, drag nodes and frames, and filter by function name.
- A readable default — only the calls that stay inside a file are drawn, so a folder shows its structure instead of a hairball (
cograph.display.sameFileEdgesOnly, on by default; turn it off to draw every call). Function names appear when you hover one, and on every match while you filter. A function whose calls all leave its file carries a dashed ring, and each file name shows how many calls leave it — auth.py · 6 ↗44 — so nothing looks unconnected when it is not.
- Click-to-navigate — click any node to open the file and jump to the function definition.
- Function source popup — click a node to open a draggable, resizable popup showing syntax-highlighted source code; multiple popups can be open simultaneously.
- OOP class overlay — visualize class hierarchies, fields, and methods; toggle with the Class button.
- Folder/file structure overlay — hierarchical grouping by directory with drag/resize support; toggle with the Folder button.
- Git integration — color nodes by their git status (modified, new, deleted, staged); toggle with the Git button.
- Language coloring — color nodes by file/language; toggle with the Language button.
- Library node clustering — external library calls are grouped into collapsed cluster nodes (e.g.
numpy (7)) to prevent visual clutter; click a cluster to expand it.
- Detail / Complexity slider — progressively cluster low-connectivity nodes to keep large projects navigable.
- Save Layout — persist node positions to ; reopen the same graph and pick up where you left off.
Graph Intelligence (AI features)
AI features are off by default. Nothing is sent to an AI provider until you turn on cograph.graphIntelligence.enabled. They run the Claude Code or OpenAI Codex CLI that is already installed and signed in on your machine, so requests go through your own account; CoGraph has no server of its own.
- Annotate Graph — a one-sentence summary of what every folder and file is responsible for, shown when you hover it.
- By default CoGraph sends only a locally built digest: file paths, function and class names with their signature lines, import names and the leading comment of each file. No function bodies are sent, and with Claude Code the AI cannot open files. Turn on
cograph.graphIntelligence.annotate.readSource to let it read source files (read-only) for better summaries. The Codex CLI can always read files in the workspace.
- You confirm an estimate before anything is sent, see the running cost, and the run stops at
cograph.graphIntelligence.annotate.maxRunBudgetUsd (default $2) and keeps what is done. As a guide, a 180-path repository cost about $0.09 with Claude haiku.
- Editing a file only marks its summary "outdated". Nothing is re-sent until you click Update, which re-annotates just the outdated and missing paths.
- Summaries are stored locally in
.cograph/annotations/ and are not committed.
Use CoGraph from your AI agent (MCP)
CoGraph ships a local MCP server, so the agent you already use can ask the graph instead of grepping:
| Tool | Answers |
|---|
find_symbol | Which functions match this name, and what are their ids? |
get_symbol | Where is it, what does it look like, who calls it and what does it call? |
callers / callees | Who calls this, or what does it call, up to 5 levels deep? |
impact | What breaks if I change this function, file or folder, including which tests and entry points reach it? |
overview | What is in this workspace or folder (with AI summaries if annotated), and where are the entry points and hot spots? |
Set up: run CoGraph: Connect an AI Agent (MCP)… from the Command Palette, or click the plug icon in the CoGraph sidebar, and choose:
- Claude Code: just me. This copies a
claude mcp add cograph -- node <server> --workspace <folder> command.
- Claude Code: whole team. This adds the server to the workspace's
.mcp.json.
- Cursor or Claude Desktop. This copies the config snippet.
On VS Code 1.101 and later, agent mode (Copilot) sees CoGraph without any setup.
What it does and does not do:
- It is local and read-only. It reads
.cograph/graph-cache.json, .cograph/annotations/ and your source files (for get_symbol slices) inside the workspace. It writes nothing, opens no network connection, runs no AI model and needs no API key.
- It answers from CoGraph's last analysis. Open the project in CoGraph once to create it. Every answer says how old the analysis is and whether files have changed since.
- The graph comes from static analysis, so calls made through dynamic dispatch, callbacks or reflection can be missing. An empty
callers result is a hint, not proof that nothing uses the function.
Requirements
- VS Code 1.75+
- Python projects: Python 3.x available (via
python3, a virtual environment, or the VS Code Python extension)
- TypeScript / JavaScript projects: Node.js — no additional configuration needed.
.vue and .svelte single-file components are analyzed through their <script> blocks (lang="ts" goes to the TypeScript analyzer, plain JavaScript to the JavaScript one) and inherit the TypeScript / JavaScript colour
- Java projects: no extra runtime — the analyzer ships with a pure-JS parser
- C and C++ projects: no extra runtime — the analyzers ship with tree-sitter WebAssembly grammars
- Pull requests in the sidebar (optional): the GitHub CLI (
gh), signed in with gh auth login
Usage
- Open a Python, TypeScript, JavaScript, Java, C, or C++ project folder in VS Code.
- Open the Command Palette (
Ctrl+Shift+P / Cmd+Shift+P) and run CoGraph: Visualize Project.
- The graph opens in a side panel.
- Use the search bar to filter functions by name (
Ctrl+F / Cmd+F focuses it).
- Hover a function to see its name, signature and first lines; click it to navigate to its definition, or open its source in a popup.
- Toggle Git or Language coloring with the buttons in the top-left.
- Toggle the Class button to overlay OOP class hierarchy and field information.
- Toggle the Folder button to overlay the directory/file structure as collapsible groups.
- Use the Complexity slider to collapse less-connected nodes on large graphs.
- Click Save Layout to persist the current node positions.
- Open the Settings panel (gear icon) to adjust layout and display options.
Troubleshooting
- The graph is empty. Make sure the open folder actually contains source files in a
supported language. For Python, confirm a
python3 interpreter is resolvable (a
virtual environment or the VS Code Python extension is enough).
- Python projects show nothing on Linux. If VS Code is installed as a snap, its
bundled runtime can interfere with analyzers — a deb/tarball install of VS Code avoids
this. (CoGraph's bundled analyzers are pure-JS/WASM specifically to minimize this.)
- A large repo feels heavy. Since 1.3.0 the Shelf engine packs each folder
into its own frame and only simulates open folders, so size hurts far less (it opens
in Static motion by default — click Dynamic to let it settle live). If needed,
use the Detail slider or the search filter — or switch the engine toggle to
Global for the classic layout (
cograph.layout.defaultEngine /
cograph.layout.defaultMode set the startup combination). The Shelf engine's
simulations run in background workers (cograph.layout.workers: auto | on | off,
default auto; off simulates on the UI thread), and when zoomed far out labels, call
lines and function dots are dropped until you zoom back in.
- I cannot see any calls between files. That is the default: CoGraph draws only the calls
that stay inside a file, because on most projects the cross-file lines cover everything else
(on a sample of twelve repositories they are between 26 % and 93 % of all calls). A function
whose calls all leave its file carries a dashed ring, and each file name shows how many
calls leave it (
auth.py · 6 ↗44). Hover a function to see its own cross-file calls, or turn
off cograph.display.sameFileEdgesOnly to draw them all.
- Function names are not shown. They appear when you hover a function, while you drag one,
while its source popup is open, and on every match while you filter. Labels scale with the
zoom, so drawn at rest they overlapped each other at every zoom level rather than separating
as you zoomed in.
- Some calls are missing. Dynamic dispatch,
eval, and computed/runtime-generated
calls are not statically resolvable — see Limitations.
Limitations
- Dynamic dispatch and runtime-generated functions are not tracked.
- Calls are resolved by name. When a called name has more than 8 definitions in the workspace, only those in the caller's file, then directory, then top-level package are linked; if more than 8 still remain the call is left unresolved (the CoGraph output channel reports how many).
- Cross-package call edges (into installed libraries) are intentionally excluded — external calls are surfaced through library cluster nodes instead.
- TypeScript / JavaScript analysis covers static call sites; dynamic patterns (e.g.
eval, computed property calls) are not tracked.
- Vue and Svelte components: only the
<script> blocks are analyzed. Calls made inside the template (@click="save()", {handler()}, on:click={inc}) are not edges, <script src="…"> and blocks in other script languages (lang="coffee") are ignored, and a </script> inside a string or comment ends the block early. The parse-free folder view guesses TypeScript for a component until the analyzer reports the real language.
- Java and C++ analysis covers statically resolvable calls; macro-heavy or template-heavy C++ code may produce a partial graph.
- C analysis covers function definitions, header prototypes and direct calls. A function handed on as a callback (passed as an argument, stored in a variable or struct initializer, assigned, returned) is linked from the function that hands it on; the later call through the pointer (
fp(x), (*fp)(x), ops->open(x)) is not, nor are macros, function tables at file scope, or calls into third-party libraries. Calls into the C standard library appear as library nodes named by header (stdio, string, …).
- A
.h file is analysed as C when its directory holds .c files and no C++ source (.cpp, .cc, .cxx, .c++); otherwise as C++.
- Very large projects may require the Complexity slider or search filter to navigate comfortably.
Contributing
Contributions are welcome! See CONTRIBUTING.md for local setup,
build/test instructions, and the PR process. Please also review our
Code of Conduct. For bugs and ideas, use the
issue tracker; for questions and sharing,
use Discussions.
Security
Found a vulnerability? Please report it privately — see SECURITY.md.
License
MIT © Bela Thrän
