agent-flow

Let your AI agent maintain a living flowchart of the project — so you never read 10,000-word status docs again.

🎮 Live Demo · 中文文档 · Report Issue

The Problem

If you build projects with AI agents (Trae, Cursor, Claude Code, ...), you know this loop:

• The agent writes 10,000-word Markdown progress docs — nobody reads them

• Half the terms it uses you don't understand, so trust erodes

• Weeks in, the project has drifted far from the original plan and nobody knows what's done, what's broken, and what's waiting on you

agent-flow flips this: the agent maintains a single flowchart (flow.json) as it works. You open one HTML file and see everything:

• How the project is decomposed and what connects to what

• Which features are done, in progress, or just planned — 7 color-coded states

• Where the bugs are and which nodes are waiting for your decision

No more reading. Just look.

Related MCP server: Overboard Studio

How It Works

You ──talk──> AI agent ──calls 14 MCP tools──> .flow/flow.json (single source of truth)
                                                    │
              You <──open in browser── .flow/flow.html (auto-rendered, zero deps)

1. Install once, register the MCP server in your AI tool

2. Talk normally: "add a payment module", "we shipped the login API" — the agent records it into the graph

3. Open flow.html anytime: zoom, drag, click nodes for details, double-click modules to drill into subgraphs

Live demo (no install): wysdshg.github.io/agent-flow/demo.html — drag nodes, click for details, double-click a module to enter its subgraph.

Quick Start

npm i -g @wysdshg/agent-flow-mcp   # install the CLI + MCP server globally
agent-flow init               # inside YOUR project: creates .flow/ and prints MCP config

git clone https://github.com/wysdshg/agent-flow.git
cd agent-flow && npm install && npm run build && npm link

Then add the MCP server to your AI tool (Trae / Claude Desktop / Cursor / any MCP client):

{
  "mcpServers": {
    "agent-flow": {
      "command": "agent-flow",
      "args": ["mcp"]
    }
  }
}

• Claude Code: claude mcp add agent-flow -- agent-flow mcp

• Cursor: put the JSON above in .cursor/mcp.json

• No MCP environment? Use the CLI fallback: agent-flow batch spec.json builds the whole graph from one JSON file and renders it.

Now just tell your agent: "Organize this project's progress into a flowchart" — and keep talking to it normally while it maintains the graph.

The 7-State System

Every node carries an honest, test-backed status. The agent is instructed (via the bundled SKILL.md) to only mark completed after tests pass:

Module nodes aggregate their children: all done → green; one unfinished state → that color; mixed states → the module shows all of them as color segments. Deprecated nodes are ignored — dead code shouldn't raise alarms.

22 Node Types

• Flow: start end process judge module

• Data: database table file sql (tables auto-attach to their database)

• AI apps: llm tool_call retrieval rerank assemble api embedding cache queue prompt agent human_loop checkpoint

module / llm / tool_call / agent / assemble support multi in/out ports. Layout is fully automatic (dagre, left-to-right) — the agent never deals with coordinates.

Human-in-the-Loop Editing

Drag nodes to rearrange (saved in your browser, never pollutes the JSON the AI reads). Right-click-drag to box-select and move groups. If you change a node's state or delete it in the viewer, it generates a small ops JSON — paste it back to your agent and it syncs the graph, always re-reading the latest file first.

Feature Docs (.flow/docs/)

Nodes can carry a doc field pointing to a single markdown file, e.g. doc: ".flow/docs/undo.md" — why it exists, how it works, how to extend it. The viewer's detail panel renders a click-to-open link: with agent-flow serve running it opens straight in your IDE; agent-flow validate warns about doc files that don't exist yet. One feature, one file; keep an index in .flow/docs/README.md.

Every doc carries a one-line status header, and the validator enforces it:

> 状态: completed | 建立: 2026-09-24 | 更新: 2026-09-30 | 上次验证: 2026-09-29（npm test 20/20）

completed requires verification evidence (test command or user confirmation) — no evidence, no green. validate catches four kinds of doc rot: missing headers, status drift between doc and graph, docs older than graph changes, and verifications older than 90 days. Docs grow with the feature: the why/what/how sections are written when work starts (while the design intent is fresh), code locations and evidence land before it's marked done.

CLI Reference

agent-flow init                 # init + print MCP config
agent-flow batch spec.json      # one-shot graph build (great for retrofitting old projects)
agent-flow apply ops.json       # run [{"tool":"add_node","args":{...}}, ...]
agent-flow render               # re-layout + refresh flow.html
agent-flow serve                # live preview: auto-reload browser when flow.json changes
agent-flow export               # export Mermaid text (.flow/flow.mmd) for README/GitHub
agent-flow status               # progress overview (JSON)
agent-flow validate             # graph sanity check
agent-flow mcp                  # start the MCP stdio server

Why Not Mermaid / draw.io?

Development

npm run build   # tsc
npm test        # smoke tests (tsx)

If agent-flow saves you from doc-hell, please give it a ⭐ — it helps other builders find it.