code-flow

Code-comprehension and visualization tool. Indexes a repo's structural graph (symbols, references, call edges) and history (commits, authors, churn), then serves the result to humans through a React dashboard and to AI agents through a read-only MCP server.

Install

git clone https://github.com/derekkinzo/code-flow
cd code-flow
cargo build --release

Requires Rust 1.85+. The dashboard requires pnpm 9 and Node.js 22+ (cd dashboard && pnpm install && pnpm build).

Use

code-flow index /path/to/repo       # walk source and build the structural graph
code-flow serve                     # localhost dashboard (token-gated)
code-flow serve --mcp               # stdio MCP server for agents

code-flow serve serves the built React dashboard as a single-page app and the JSON API under /api/*. The static shell (HTML/JS) is public; /api/* is bearer-token-gated. The dashboard bundle is resolved in this order: --dashboard-dir <path> flag, then [server] dashboard_dir in .code-flow/config.toml, then the bundled dashboard/dist. If no bundle is found, the server logs a warning and serves the API only — build it first with cd dashboard && pnpm build.

serve and mcp also background-index the workspace on launch when the graph is missing, empty, or stale (suppress with --no-index-on-start), so code-flow index is a convenience rather than a hard prerequisite — the first queries on a cold repo may briefly race the background index.

See code-flow --help for the full subcommand surface (index, index_at_commit, serve, mcp, status, export, bench, watch, forget, unregister-repo, version). code-flow export --format jsonl|graphml writes the graph for external tools.

Cross-repo workspace scope

The MCP server can federate a query across several indexed repos. Each repo is registered in a per-machine registry (~/.code-flow/repos.db) via the register_repo tool; thereafter the graph-traversal tools (callers_of, callees_of, references_of, search_symbol, nodes_in_file) accept scope="workspace" and UNION their results across every registered peer, resolving each target by its SCIP symbol inside that peer. search_text is also workspace-aware: it runs a cross-repo bm25 full-text search ranked globally across peers (the highest-value cross-repo query when a target language's call graph is sparse). Cross-repo rows carry {symbol, repo, node} plus a registry_health envelope. unregister-repo drops only the registry row; forget also deletes the repo's graph.db.

Claude Code plugin

code-flow ships as a Claude Code plugin that exposes its workflows as slash commands. Install it from this repository's bundled marketplace:

/plugin marketplace add derekkinzo/code-flow
/plugin install code-flow

/plugin marketplace add also accepts a local checkout path or any git URL, so /plugin marketplace add https://github.com/derekkinzo/code-flow works without a clone. The plugin drives the same code-flow binary, so build it first (see Install) and index a repo before running the graph-dependent commands.

The commands all share the code-flow: namespace:

Command	Argument	Purpose
/code-flow:index	[path]	Index a workspace into .code-flow/graph.db (run this first).
/code-flow:explain	<symbol>	Curated single-symbol explanation grounded in the graph.
/code-flow:chat	<question>	Free-form Q&A that chains the appropriate MCP tools.
/code-flow:onboard	[path-prefix]	Contributor tour: shape, hotspots, co-changes, truck factor.
/code-flow:diff	<ref-a>..<ref-b>	Structural AST-level diff between two git refs.
/code-flow:domain	[path-prefix]	Business-domain entities and flows from the graph.
/code-flow:knowledge	[path-prefix]	Markdown knowledge-base inventory (READMEs, ADRs, docs).
/code-flow:dashboard	[--port P] [--host H]	Open the dashboard in a browser via code-flow serve.
/code-flow:enrich	<symbol-or-file>	Agent-driven Tier-4 enrichment proposing new edges.

License

MIT — see LICENSE.