desago

Codebase graph analyzer with a Claude Code MCP integration.

desago scans a project's source code, builds a graph of files, functions, classes, and their relationships (imports, calls, extends, implements), and exposes that graph to Claude Code via MCP so it can navigate a codebase without grepping or reading whole files. It also ships two browser-based graph viewers so you (not just Claude) can explore the same graph.

Supported languages: JavaScript/TypeScript, Java (with Spring Boot annotation awareness — @RestController/@Service/@Autowired/HTTP mapping annotations), PHP, Python.

Install

npm install -g desago

Getting started (step by step)

1. Go to your project and analyze it once. This scans the codebase and writes .desago-graph/graph.json + .desago-graph/graph.html.

   cd your-project
   desago analyze

2. Look at the graph. Pick whichever fits your codebase's size:
   • Small/medium project → just open the file that was written: .desago-graph/graph.html
   • Large project (thousands of files) → run the live viewer instead, which loads progressively so it stays fast:

     desago run

     then open the URL it prints (defaults to http://localhost:7826)
3. Connect it to Claude Code, in two terminals:

   # Terminal 1 — leave this running
   desago serve
   
   # Terminal 2 — registers the graph with Claude Code and launches it
   desago claude

   From then on, Claude Code can query the graph (search_nodes, get_node, etc.) instead of grepping or reading whole files, and a Stop hook keeps the graph refreshed after every response automatically.
4. Keep working as normal. Re-run desago analyze (or just keep desago serve running) whenever you want the graph re-synced with the latest code — step 3's hook already does this for you after every Claude Code response.

That's the whole workflow: analyze (or run) to see it, serve + claude to give Claude Code access to it.

Command reference

desago analyze [rootDir] [options]   # Scan a project, write graph.json + graph.html
desago run [rootDir] [options]       # Serve a live, progressively-loading graph viewer in the browser
desago serve [rootDir] [options]     # Serve the graph over MCP (HTTP). Run this first, in its own terminal.
desago claude                        # Connect Claude Code to an already-running "desago serve", then launch it
desago --version, -v                 # Print the installed desago version

Run desago analyze --help for analyze-specific options.

MCP tools

Once connected, Claude Code has access to:

• graph_stats — summary counts of the analyzed graph
• search_nodes — find functions/classes/variables by name
• get_node — full detail for a node, including its edges
• get_neighbors — one-hop traversal (calls, imports, extends, implements, contains)
• get_file_symbols — symbols defined in a given file
• refresh_graph — re-analyze after edits so the graph reflects the latest code

Viewing the graph: graph.html vs. desago run

Both viewers share the same interface and controls (see below) — the only difference is where the data comes from:

• graph.html (written by desago analyze) has the entire graph embedded in one self-contained file. No server, no dependencies — just open it in a browser, even offline. Nothing beyond the current layer is ever laid out or rendered, so it stays fast regardless of project size. To pick up code changes, just re-run desago analyze.
• desago run starts a live local server and fetches each layer from it on demand. To pick up code changes without restarting the server or reloading the browser tab, press r in the terminal running desago run — see Terminal shortcuts below. (The browser's own r shortcut just re-arranges the current layout — it doesn't touch the underlying data.)

Both read the same .desago-graph/config.json for node colors.

Navigating the graph

The graph is a drill-down tree, not one giant hairball: it opens showing only your project's top-level folders, and clicking into something replaces the view with what's directly inside it — nothing beyond that is ever loaded.

• Click a node once to see its details (type, file, lines, incoming/outgoing edges) in the right-hand panel.
• Double-click a folder, file, class, interface, enum, or trait to open it.
• Home / Back / Forward (top-left) retrace your drill-down history like a browser.
• Search (top bar) looks across the entire project, not just the current layer — results are ranked modules first, then files, then everything else. Click a result to jump straight to it, drilling through whatever layers stand in between.
• View Code — select a node (or, while browsing inside a file/class, use the top-bar button) to open its source in a popup, with one-click copy for both the file path and the code.
• Files / Details panels — drag their edge to resize, or click the top-bar buttons to hide/show them.
• Minimap (bottom-right of the canvas) shows where you are in the current layer; click it to jump around.
• + / − buttons (top-right of the canvas) or the scroll wheel to zoom; drag the background to pan.
• ⟳ button (top-left of the canvas) re-arranges the current layer's layout if it looks cramped.
• ? button (top-right of the header) opens an in-app About/Shortcuts guide.

Keyboard shortcuts (in the browser)

| Key | Action | | --- | --- | | ← / → | Back / Forward | | h | Home | | d | Toggle details panel | | t | Toggle files panel | | r | Refresh (re-arrange) layout | | + / - | Zoom in / out | | Ctrl/Cmd + Space | Focus search | | ? | Show the help popup | | Esc | Close whatever popup is open |

Terminal shortcuts

While desago run or desago serve is running, the terminal itself accepts single-key shortcuts (only in an interactive terminal, not when piped/backgrounded):

| Key | desago run | desago serve | | --- | --- | --- | | q | Quit | Quit | | c | Clear the terminal | Clear the terminal | | r | Re-analyze and reload (same port, no restart needed) | Force an immediate re-analysis | | o | Open the viewer in your browser | — | | h | Show shortcuts | — | | u | Print the URL | — |

Styling

.desago-graph/config.json is created with default node colors on first analyze (or run) and never overwritten afterward — edit it to taste. Both viewers read from it.

Claude Code guidance

desago claude writes the MCP usage guidance to .desago-graph/CLAUDE.md (gitignored, fully regenerated each run) and ensures your project's own root CLAUDE.md has a one-line @.desago-graph/CLAUDE.md import so Claude Code still picks it up automatically — your root CLAUDE.md is never otherwise modified.

License

MIT