{"id":"397a28b0-ce8f-4cee-b710-624a0ab60c92","slug":"deepflow","kind":"mcp","name":"DeepFlow","summary":"Live architecture signal map for agentic coding. Tree-sitter + MCP bridge lets agents query, trace, and animate your codebase graph in real time.","owner":"vanshksingh","repoUrl":"https://github.com/vanshksingh/DeepFlow","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-19T18:57:28.000Z","addedAt":"2026-10-21T09:20:59.281Z","logoUrl":"https://avatars.githubusercontent.com/u/114809624?u=87cf9e803d9bd282a4472686fafd2ee42ab5b621&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities","communication","data-analytics"],"tags":["agent-tools","architecture","codebase-visualization","codex","developer-tools","openai-build-week","tree-sitter","signal-map"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T09:21:27.602Z","sample":false,"url":"https://conduits.dev/tools/deepflow","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n  <img src=\"./public/favicon.png\" width=\"100\" height=\"100\" alt=\"DeepFlow Logo\" />\n  <h1>DeepFlow</h1>\n  <p><strong>Live architecture signal map for agentic coding</strong></p>\n  <p>\n    <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT License\" /></a>\n    <img src=\"https://img.shields.io/badge/node-18%2B-brightgreen.svg\" alt=\"Node 18+\" />\n    <img src=\"https://img.shields.io/badge/tests-13%20passing-brightgreen.svg\" alt=\"13 tests passing\" />\n    <a href=\"https://deepflow-42li.onrender.com/#path=services&mode=signal\"><img src=\"https://img.shields.io/badge/demo-live-orange.svg\" alt=\"Live Demo\" /></a>\n    <img src=\"https://img.shields.io/badge/MCP-25%20tools-blueviolet.svg\" alt=\"25 MCP tools\" />\n    <img src=\"https://img.shields.io/badge/built%20with-Codex%20%2B%20GPT--5.6-black.svg\" alt=\"Built with Codex + GPT-5.6\" />\n  </p>\n</div>\n\n<img width=\"1376\" height=\"768\" alt=\"DeepFlow architecture map\" src=\"https://github.com/user-attachments/assets/cc5a1f5d-e9e5-4c56-b5c4-a665f7beb87b\" />\n\n<br/>\n\nMost 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 →](https://deepflow-42li.onrender.com/#path=services&mode=signal)\n\n> **The agent doesn't just edit files. It shows the architecture moving.**\n\n---\n\n## Hosted Demo\n\n**[DeepFlow Live Demo](https://deepflow-42li.onrender.com/#path=services&mode=signal)** — explore the interactive fixture map.\n\n> Hosted on Render's free tier. If the instance has been inactive, it may take ~50 seconds to spin back up on first load.\n\n<img width=\"1376\" height=\"768\" alt=\"DeepFlow Demo\" src=\"./public/hero.gif\" />\n\n---\n\n## Quick Start\n\nPaste this prompt into any agent chat (Cursor, Claude, Codex, Antigravity, etc.) and it will clone, install, start, and wire DeepFlow automatically:\n\n```text\nSetup DeepFlow (local codebase visualizer + MCP):\n1. Clone and Bootstrap:\n   git clone https://github.com/vanshksingh/DeepFlow.git && cd DeepFlow && bash scripts/agent-bootstrap.sh\n   (Installs deps, starts viewer on http://127.0.0.1:4317, generates config in .deepflow.mcp.generated.json)\n2. Connect: Merge generated config into your IDE's MCP settings. Verify via `deepflow_status`.\n3. Usage in any repo:\n   - Connect workspace: `deepflow_open_workspace {\"root\": \"<ABS_PATH>\"}`\n   - Sync writes:       `deepflow_after_edit {\"paths\": [\"rel/path/to/edited\"]}`\n   - Trace/Explain:     `deepflow_jump_to`, `deepflow_impact`, or `deepflow_summary`\n   - Keep `npm run dev` running in the DeepFlow checkout.\n```\n\n**One-liner bootstrap:**\n```sh\nbash scripts/agent-bootstrap.sh\n```\n\n**Manual setup:**\n```sh\nnpm install\nnpm run dev          # viewer on http://localhost:4317\n# in a second terminal or IDE MCP config:\n# node /absolute/path/to/DeepFlow/mcp-server.js\n```\n\n---\n\n## What it does\n\n| Feature | Description |\n|---------|-------------|\n| **Live agent loop** | `deepflow_after_edit` refreshes the graph and triggers animations the moment an agent writes a file |\n| **Nested frames** | Folder frames wrap file frames wrap function frames — like Figma for your codebase |\n| **Trace focus** | Pin any node; unrelated rows dim and wires follow calls and imports |\n| **Signal animations** | Particle bursts, fire embers, heart blooms, and typewriter effects on every edit |\n\n**Keyboard shortcuts:** `Cmd+K` / `Ctrl+K` to search · double-click a function to open source · `Esc` to collapse · drag to pan · scroll to zoom\n\n**Deep link example:** `#path=apps/gateway/src/routes.ts&module=startIngest&mode=signal`\n\n---\n\n## MCP Tools\n\n> The viewer (`npm run dev`) must be running for tools that animate the UI. Analysis tools work headless too and return JSON.\n\n| Tool | What it does |\n|------|-------------|\n| `deepflow_status` | Health check: viewer, root, connected browsers |\n| `deepflow_open_workspace` | Connect a repo and start the FS watcher — **call this first** |\n| `deepflow_summary` | Compact brief: languages, entrypoints, orphans, hot files |\n| `deepflow_find` | Search files and modules by substring |\n| `deepflow_explain` | One node: region, modules, typed edges with evidence |\n| `deepflow_impact` | Upstream and downstream static impact for a path |\n| `deepflow_path_between` | Directed path between two files |\n| `deepflow_entrypoints` | Detected entry files |\n| `deepflow_orphans` | Unreferenced code, highlighted in viewer |\n| `deepflow_diagnostics` | Unresolved imports, parse issues, TODOs |\n| `deepflow_after_edit` | Refresh map and trigger edit animation after a write |\n| `deepflow_jump_to` | Focus a file or `path::module`, enter signal path, pulse |\n| `deepflow_open_flow` | Code-flow overlay: upstream, focus, downstream + snippets |\n| `deepflow_explain_flow` | Structured flow story for agents, optionally opens overlay |\n| `deepflow_close_flow` | Close the code-flow overlay |\n| `deepflow_highlight_paths` | Multi-select highlight and pin |\n| `deepflow_clear_highlights` | Clear pins, return to rails |\n| `deepflow_set_mode` | Force `rails` / `outline` or `signal` mode |\n| `deepflow_set_edges` | Toggle calls / imports / dataflow / events |\n| `deepflow_share_link` | Hash URL for the current focus |\n| `deepflow_file_diff` | Local git diff for one path (includes untracked via `--no-index`) |\n| `deepflow_pr_diff` | Unified diff for a branch/PR range (`base...head`, defaults to main/master) |\n| `deepflow_analyze_workspace` | Full graph JSON |\n| `deepflow_setup_help` | MCP config block + sample workspace roots |\n\nPaths may use `file.ts::moduleName` (or `#`) on explain / impact / jump / flow tools. `viewerUrl` must be loopback (`127.0.0.1` / `localhost`).\n\n### Recommended agent loop\n\n```\ndeepflow_status\ndeepflow_open_workspace { root }\ndeepflow_summary { root }\n  ...edit files...\ndeepflow_after_edit { root, paths: [\"...\"] }\ndeepflow_jump_to { root, path, module?, pin: true }\ndeepflow_explain_flow { root, path, module? }\ndeepflow_impact { root, path }\n```\n\n---\n\n## Built with Codex and GPT-5.6\n\nDeepFlow was originally built with Codex and GPT-5.6 during OpenAI Build Week.\n\n---\n\n## Fixtures\n\n| Path | Use |\n|------|-----|\n| `fixtures/atlas-workspace` | Messy TS monorepo, default boot target |\n| `fixtures/python-mini` | Tiny Python import and call graph |\n\nAny 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.\n\n---\n\n## Scripts\n\n| Command | Action |\n|---------|--------|\n| `npm run dev` | Viewer + API on `:4317` |\n| `npm run mcp` | Stdio MCP server |\n| `npm test` | Graph and insight tests |\n| `npm run bootstrap` | Same as `bash scripts/agent-bootstrap.sh` |\n\n---\n\n## Requirements\n\n- **Node.js 18+** (20+ recommended)\n- A native build toolchain only if `tree-sitter` needs to compile on your platform — standard `npm install` is enough on macOS and Linux\n- A browser open to the viewer for live animations\n- Git *(optional — enables diff badges on file nodes)*\n\n---\n\n## Privacy\n\nEverything 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.\n\n| File | Role |\n|------|------|\n| `server.js` | HTTP viewer + SSE + track API |\n| `mcp-server.js` | MCP tools (stdio JSON-RPC) |\n| `src/repository-graph.js` | Tree-sitter polyglot graph builder |\n| `src/graph-insights.js` | Summary / find / impact / flow helpers |\n| `public/` | Signal map UI |\n| `fixtures/` | Sample workspaces |\n| `AGENTS.md` | Agent contract |\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n"}