Most code tools either show the human the architecture, or feed context to the agent. DeepFlow does both at the same time. Tree-sitter parses your JS/TS and Python files locally, and an MCP bridge lets any agent open a workspace, query the graph, and animate the viewer as it edits, so you can actually watch your agent navigate the codebase in real time. Try the live demo.
The agent doesn't just edit files. It shows the architecture moving.
DeepFlow was built during OpenAI Build Week using the $100 promotional API credits.
Ideation to prototype in a single session. Codex was the main environment from day one. Rather than sketching ideas in a doc and then coding, I described the concept ("a graph where the agent's edits animate the architecture in real time") and Codex produced a working physics layout with SSE streaming within the same session. That collapsed what would normally be a multi-day spike into an afternoon.
Visual iteration on the layout engine. The force-directed layout, signal-mode particle bursts, and nested folder frames all went through many visual iterations. Because Codex keeps code context live, I could say "the nodes drift too far apart on dense graphs" and get a targeted tweak to the alpha decay and repulsion constants rather than describing a whole file. The animation system (public/app.js) went through roughly 15 rounds of this kind of tight loop.
Scoping with the Devpost plugin. The Devpost plugin inside Codex helped anchor the work to what the hackathon was actually asking for. When I started drifting toward a full IDE plugin, the plugin flagged the scope and I re-focused on the MCP bridge as the agent-integration surface, which turned out to be the right call.
Concrete decisions driven by Codex sessions:
- Chose Tree-sitter (over Babel / AST-grep) for language-agnostic parsing after Codex produced a side-by-side benchmark inside the same chat
- Chose SSE over WebSockets for the change stream after Codex explained the reconnect semantics difference on ephemeral cloud hosts like Render
- Settled on a hash-based deep-link scheme (
#path=...&module=...&mode=...) so the viewer URL is shareable without a backend session (Codex proposed and implemented it in one pass)
GPT-5.6 drove the sustained coding loop across the full build:
| Mode | Where it was applied |
|---|---|
| Medium reasoning | Architecture discussions: MCP stdio protocol design, Tree-sitter grammar selection, edge type taxonomy (calls / imports / dataflow / events) |
| High reasoning | Precise multi-file edits: AST extraction in src/repository-graph.js, path sandbox hardening in mcp-server.js, minimap viewport sync, constellation layout |
| Goal mode | Large refactors without stopping: the full rework of focus-rearrange physics (15 commits), the MCP audit hardening pass (P0-P2 issues in a single goal run) |
Key technical decisions made with GPT-5.6:
- Graph schema: GPT-5.6 proposed the
{ nodes, edges, roots, diagnostics }wire format after reviewing what an agent actually needs to answer "what does this file touch?" That format is now the contract betweenrepository-graph.js,graph-insights.js, and the MCP tools. - MCP sandbox: When GPT-5.6 ran the P0 audit, it found that path traversal was possible through unsanitized
rootarguments. It rewrote the sandbox checks inmcp-server.jsand added tests in the same pass. - Constellation layout: The "focus pull" that brings traced nodes into a readable frame while leaving unrelated islands still was designed collaboratively. I described the desired behaviour, GPT-5.6 proposed the physics approach (one-shot bake + linger shadow), and we iterated on it across several high-reasoning passes until the landing was stable.
Explore the live interactive fixture map: DeepFlow Live Demo
(Hosted on Render's free tier. If the instance has been inactive, it may take ~50 seconds to spin back up on your first click.)
Paste this into any agent chat (Cursor, Claude, Codex, Antigravity, etc.) and it will install, start, and wire DeepFlow automatically.
Setup DeepFlow (local codebase visualizer + MCP):
1. Clone and Bootstrap:
git clone https://github.com/vanshksingh/DeepFlow.git && cd DeepFlow && bash scripts/agent-bootstrap.sh
(Installs deps, starts viewer on http://127.0.0.1:4317, generates config in .deepflow.mcp.generated.json)
2. Connect: Merge generated config into your IDE's MCP settings. Verify via `deepflow_status`.
3. Usage in any repo:
- Connect workspace: `deepflow_open_workspace {"root": "<ABS_PATH>"}`
- Sync writes: `deepflow_after_edit {"paths": ["rel/path/to/edited"]}`
- Trace/Explain: `deepflow_jump_to`, `deepflow_impact`, or `deepflow_summary`
- Keep `npm run dev` running in the DeepFlow checkout.
One-liner:
bash scripts/agent-bootstrap.shManual:
npm install
npm run dev # viewer on http://localhost:4317
# in a second terminal or IDE MCP config:
# node /absolute/path/to/DeepFlow/mcp-server.js| Feature | Description |
|---|---|
| Live agent loop | deepflow_after_edit refreshes the graph and triggers animations the moment an agent writes a file |
| Nested frames | Folder frames wrap file frames wrap function frames, like Figma for your codebase |
| Trace focus | Pin any node; unrelated rows dim and wires follow calls and imports |
| Signal animations | Particle bursts, fire embers, heart blooms, and typewriter effects on every edit |
Keyboard: Cmd+K / Ctrl+K to search, double-click a function to open source, Esc to collapse, drag to pan, scroll to zoom.
Deep link example: #path=apps/gateway/src/routes.ts&module=startIngest&mode=signal
The viewer (npm run dev) needs to be running for tools that animate the UI. Analysis tools work headless too and return JSON.
| Tool | What it does |
|---|---|
deepflow_status |
Health check: viewer, root, connected browsers |
deepflow_open_workspace |
Connect a repo and start the FS watcher (call this first) |
deepflow_summary |
Compact brief: languages, entrypoints, orphans, hot files |
deepflow_find |
Search files and modules by substring |
deepflow_explain |
One node: region, modules, typed edges with evidence |
deepflow_impact |
Upstream and downstream static impact for a path |
deepflow_path_between |
Directed path between two files |
deepflow_entrypoints |
Detected entry files |
deepflow_orphans |
Unreferenced code, highlighted in viewer |
deepflow_diagnostics |
Unresolved imports, parse issues, TODOs |
deepflow_after_edit |
Refresh map and trigger edit animation after a write |
deepflow_jump_to |
Focus a file or path::module, enter signal path, pulse |
deepflow_open_flow |
Code-flow overlay: upstream, focus, downstream + snippets |
deepflow_explain_flow |
Structured flow story for agents, optionally opens overlay |
deepflow_close_flow |
Close the code-flow overlay |
deepflow_highlight_paths |
Multi-select highlight and pin |
deepflow_clear_highlights |
Clear pins, return to rails |
deepflow_set_mode |
Force rails / outline (alias) or signal mode |
deepflow_set_edges |
Toggle calls / imports / dataflow / events |
deepflow_share_link |
Hash URL for the current focus |
deepflow_file_diff |
Local git diff for one path (includes untracked via --no-index) |
deepflow_pr_diff |
Unified diff for a branch/PR range (base...head, defaults to main/master) |
deepflow_analyze_workspace |
Full graph JSON |
deepflow_setup_help |
MCP config block + sample workspace roots |
Paths may use file.ts::moduleName (or #) on explain / impact / jump / flow tools. viewerUrl must be loopback (127.0.0.1 / localhost).
deepflow_status
deepflow_open_workspace { root }
deepflow_summary { root }
...edit files...
deepflow_after_edit { root, paths: ["..."] }
deepflow_jump_to { root, path, module?, pin: true }
deepflow_explain_flow { root, path, module? }
deepflow_impact { root, path }
| Path | Use |
|---|---|
fixtures/atlas-workspace |
Messy TS monorepo, default boot target |
fixtures/python-mini |
Tiny Python import and call graph |
Any JS/TS/Python repo works via deepflow_open_workspace. Cross-language HTTP edges are not inferred; each language's own imports and calls are tracked separately.
| Command | Action |
|---|---|
npm run dev |
Viewer + API on :4317 |
npm run mcp |
Stdio MCP server |
npm test |
Graph and insight tests |
npm run bootstrap |
Same as bash scripts/agent-bootstrap.sh |
- Node.js 18+ (20+ recommended)
- A native build toolchain only if
tree-sitterneeds to compile on your platform (standardnpm installis enough on macOS and Linux) - A browser open to the viewer for live animations
- Git (optional, enables diff badges on file nodes)
Everything runs locally. No source code or graph data is ever uploaded. The browser folder picker builds a static snapshot on your machine. Live watching, Git integration, and agent sync all go through MCP deepflow_open_workspace pointing at your disk.
| File | Role |
|---|---|
server.js |
HTTP viewer + SSE + track API |
mcp-server.js |
MCP tools (stdio JSON-RPC) |
src/repository-graph.js |
Tree-sitter polyglot graph builder |
src/graph-insights.js |
Summary / find / impact / flow helpers |
public/ |
Signal map UI |
fixtures/ |
Sample workspaces |
AGENTS.md |
Agent contract |