Codebase Graph

Interactive filesystem graph for any repository — expand folders in place, hide nodes, pan/zoom, and edit notes or files in the side panel. Optional code-review-graph (CRG) integration adds impact analysis, callers/callees, and smarter AI context.

Stack

• React + Vite — app shell and inspector
• SVG graph — in-place expand (camera preserved)
• generate.py — one-shot tree index → workspaces/<slug>/data.json
• server.py — static files + sandboxed APIs + CRG bridge
• code-review-graph — structural index (calls/imports/tests) via .venv

Quick start

# Index a repo (writes workspaces/<slug>/data.json; other repos stay put)
python generate.py --root /path/to/repo

# Optional: structural graph (recommended for large repos)
python -m venv .venv
# Windows:
.\.venv\Scripts\pip install code-review-graph tree-sitter-language-pack
# macOS/Linux:
# .venv/bin/pip install code-review-graph tree-sitter-language-pack

# API + static (port 8765)
python server.py

# UI (dev) — proxies /api and data.json to the Python server
npm install
npm run dev

Open the URL Vite prints (usually http://127.0.0.1:5173). Settings → Workspace → Scanned repo lists known roots and Open switches without swapping files. In Settings → Indexing, click Build graph (first build of a huge monorepo can take minutes). Optional: Semantic backend (CRG Embed or claude-context) and Serena refine — see docs/USAGE.md.

Production-style

npm run build
python server.py
# open http://127.0.0.1:8765

Usage

Day-to-day reference: docs/USAGE.md.
Progress / roadmap on this branch: docs/STATUS.md.

• Double-click a directory to focus it — the graph compacts to that subtree (parent stub + children), so deep navigation stays readable.
• Drag nodes to rearrange; use Stretch / Depth sliders to space the layout; Reset positions clears manual placement.
• Drag the background to pan; scroll to zoom; Pack frames the view; Up / Root change focus.
• Hide / Unhide from the inspector (or Unhide all in the toolbar).
• Impact / Relations tabs (files) — CRG blast radius, callers, callees, tests.
• AI — chats can include a short CRG structural blurb for the active file.
• Notes — edit title/body and Save note (SQLite via the API).
• Files — when a file is selected, view/edit contents and Save file (writes into the scanned repo root from data.json).

API

Method	Path	Purpose
GET	/api/meta	Root path / stats / active workspace
GET	/api/workspaces	Current + known scanned repos
POST	/api/workspaces/open	Activate a repo (regenerate rebuilds the tree)
GET/PUT	/api/notes	Load/save notes object
GET/PUT	/api/file?path= / body {path,content}	Load/save UTF-8 file under repo root
GET/PUT	/api/chats	Path-scoped AI threads
POST	/api/llm/chat	Proxied LLM completion
GET	/api/crg/status	CRG ready / node counts
POST	/api/crg/build	Full CRG build for root_path
POST	/api/crg/update	Incremental CRG update
GET	/api/crg/impact?path=	Blast radius for a file
GET	/api/crg/query?pattern=&symbol=	callers_of / callees_of / …
GET	/api/crg/relations?path=	One-hop file edges for overlay
GET	/api/crg/context?path=	Compact AI context string

Paths are sandboxed to root_path in the active workspace data.json. Graph, notes, chats, and branch caches live under workspaces/<slug>/ in this tool folder (one folder per scanned repo). CRG stays in each repo’s .code-review-graph/.

Later (deferred)

See docs/STATUS.md for what’s done on feature/notes-agents and what’s next (locked docs notes, git branch workflows). Also: CodeGraph as CRG alternate, RPG/ZeroRepo Plan mode — docs/USAGE.md.

Layout modes for the tool itself

See generate.py --help for --root, embedded codebase-graph/ parent detection, and ./repo attach.