Project Story
AI writes code faster than humans can follow
AI agents can create and change dozens of files in minutes. The new bottleneck is not writing code. It is keeping an accurate mental model of what changed, where a flow starts, which files import or call one another, and how a small edit affects the wider system.
DeepFlow is a live architectural map for that problem. It turns a local repository into an explorable visual system: folders contain files, files expose modules, and animated traces reveal calls, imports, and dependency paths. When an agent edits code, DeepFlow updates the map so the developer can see the affected files and relationships instead of reconstructing them manually.
What it does
- Parses JavaScript, TypeScript, TSX, and Python locally with Tree-sitter.
- Maps folders, files, modules, calls, imports, events, and diagnostics.
- Lets developers trace upstream and downstream relationships from a file or module.
- Watches local edits and highlights changed files and updated relationships.
- Provides an MCP server so an agent can open a workspace, explain flows, surface impact, jump to an exact file or module, and trigger live visual updates after edits.
- Includes source inspection, pins, search, minimap navigation, Git diffs, themes, and animated trace signals.
Inspiration
We kept running into the same problem while working with coding agents: implementation was becoming dramatically faster, but understanding was not. A project could gain new files, abstractions, and dependency paths faster than a developer could build a reliable mental map.
As Peter Steinberger (@steipete) recently noted on Twitter regarding the shift in AI workflows:
"Are we still talking loops or did we shift to graphs yet?"
-- @steipete
The industry is moving toward "graph engineering", where understanding complex nodes and dependencies is critical.
Most existing tools solve only one half of that problem. They either visualize architecture for a human, or feed repository context to an agent. DeepFlow is designed to do both at once: it gives the developer a living architectural view while giving the agent a programmable MCP interface for understanding and updating that same view.
How we built it
DeepFlow is a local Node.js application with a browser-based architecture canvas.
Tree-sitter builds a semantic repository graph rather than relying on text matching. That graph is the shared contract between the parser, graph-insight layer, MCP tools, and visual viewer. The local server streams workspace changes to the browser through Server-Sent Events, allowing edits to appear immediately. The MCP bridge exposes workspace analysis, navigation, tracing, impact analysis, diffs, and edit notifications to Codex and other MCP-compatible agents.
The visual layer was built around one principle: hierarchy first, graph second. Folders, files, modules, and source remain understandable as nested code structure; traces overlay the calls and imports that matter. This keeps the interface useful as an architectural explorer rather than turning it into an unreadable dependency graph.
How we used Codex and GPT-5.6
DeepFlow was built during OpenAI Build Week using the promotional API credits, with Codex as the main development environment and GPT-5.6 driving the sustained implementation loop.
Codex helped turn the initial concept ("a graph where the agent's edits animate the architecture in real time") into a working prototype with a physics layout and SSE updates in a single session. It was then used for rapid visual iteration: refining trace routing, nested folder behaviour, focus states, animation timing, and readable map layouts through tight feedback loops.
GPT-5.6 was used for architecture decisions and precise multi-file changes, including:
- Choosing Tree-sitter over regex-based parsing so the map is grounded in semantic code structure.
- Designing the shared graph schema: nodes, edges, roots, and diagnostics.
- Building the MCP interface for workspace opening, graph queries, trace navigation, impact analysis, and live edit events.
- Auditing the MCP server for unsafe root-path handling, then hardening the sandbox checks and adding tests.
- Iterating on the constellation-style focus layout so traced files become readable without losing the user's spatial context.
This was not just code generation. Codex and GPT-5.6 were used as a design and engineering collaborator: comparing implementation approaches, making scoped changes, testing them, and helping us converge on the product's core interaction model.
Challenges we ran into
The difficult part was not drawing boxes and lines. It was making a dense repository understandable without turning it into visual noise.
We iterated heavily on stable layout, trace routing, nested expansion, endpoint placement, zoom behaviour, and live-edit feedback. The key lesson was that a useful architecture map must preserve spatial memory: a selected file should stay put, unrelated files should not steal attention, and a trace must clarify flow rather than create another layer of clutter.
The MCP server also required careful security work. A visualization tool that accepts a workspace path must not accidentally give agents unrestricted filesystem access. We constrained workspace roots, added validation, and tested the graph-building and insight layers against JavaScript, TypeScript, TSX, and Python fixtures.
Accomplishments that we're proud of
- A fully local, semantic codebase map with no source code uploaded to a service.
- A live agent-to-map loop: an agent can edit a file, notify DeepFlow through MCP, and the developer sees the affected architecture update.
- A single tool that serves both sides of agentic development: the human's evolving mental model and the agent's repository context.
- An MCP surface with tools for status, summaries, search, explanation, impact, paths, diagnostics, diffs, deep links, highlights, and viewer control.
What we learned
AI-assisted development needs new interfaces. Faster generation can reduce architectural visibility unless the developer has a way to continuously rebuild understanding.
We also learned that graph layout is not the product. The product is reducing cognitive load. The hierarchy, the trace, the source, and the live-change signal all have to work together to answer one question quickly: what is happening in this codebase now?
What's next for DeepFlow
We want to improve cross-language flow inference, add richer intent summaries, make saved architectural tours and annotations collaborative, and integrate the viewer more deeply into agent IDE workflows. The long-term goal is a shared, living architecture model that evolves alongside the code, whether changes come from a human or an agent.
Built With
- 5.6
- codex
- css
- git
- html
- javascript
- mcp
- node.js
- server-sent-events
- tree-sitter
Log in or sign up for Devpost to join the conversation.