SeeFlow

Architecture diagrams that actually run, generated by AI agents.

Turn your static system architecture into a live control panel wired directly to your running application. Click a node, fire a real request, watch downstream services light up as your app emits events back.

Why

• Diagram drift — Confluence pages go stale. SeeFlow breaks loudly when your actual system changes.
• Onboarding friction — New engineers click through a live flow instead of reading six-month-old docs.
• Demo tedium — Script it once, replay it flawlessly. No more manually clicking through microservices for stakeholders.

Quick Start

The SeeFlow plugin reads your codebase, understands your architecture, and generates the full diagram and request scripts automatically. Works with Claude Code, Codex, Cursor, and Windsurf.

1. Start the studio

npx -y @tuongaz/seeflow@latest start
# then open http://localhost:4321

Requires Bun ≥ 1.3 (or Node with npx). The studio scans $(pwd)/.seeflow/flow.json on start and auto-registers that flow if present. Flows you create from the UI, plus the studio's registry, persist under $(pwd)/.seeflow/ across restarts.

⚠️ Heads up: Play and Status scripts run inside the container, so generated scripts that talk to services on your host — HTTP calls to localhost, host binaries like psql / redis-cli, your project's CLI — will not work. Interactive nodes are likely to fail. Use the native path above for full functionality.

docker run --rm -it -p 4321:4321 -v $(pwd):/workspace tuongaz/seeflow

The image ships with a pre-registered Order Pipeline demo so you can see the canvas immediately, and the studio scans /workspace/.seeflow/flow.json on start.

2. Install the plugin

Skill installer (recommended):

npx skills add tuongaz/seeflow

Then just ask:

/seeflow show me the shopping cart feature

The plugin scans your routes and database connections, generates flow.json, wires up demo scripts, and opens the canvas at localhost:4321.

Docker reference

⚠️ Docker is the non-preferred path. Play/Status scripts execute inside the container and cannot reach host services or host binaries, so interactive nodes generated against your local app will not work. Prefer npx -y @tuongaz/seeflow@latest start for the full experience.

The image is published on Docker Hub. See Quick Start above for the basic docker run.

Configuration

| Variable | Default | Description | | ------------------- | ----------------------- | ------------------------------------------ | | SEEFLOW_PORT | 4321 | Port the studio listens on | | SEEFLOW_FLOW | .seeflow/flow.json | Flow file path relative to the workspace | | SEEFLOW_WORKSPACE | /workspace | Workspace mount point inside the container |

Bake demos into a derived image

Ship a container that already contains your flow:

FROM tuongaz/seeflow
COPY ./my-demos /workspace
# docker build -t my-flow . && docker run --rm -it -p 4321:4321 my-flow

Tags

• :latest — newest stable release
• :<version> — pinned release (e.g. :0.1.18)
• :<major>.<minor> — latest patch on a minor line (e.g. :0.1)

MCP server

SeeFlow ships an MCP server so any MCP-aware editor can list, register, and edit demos directly. The studio must be running first.

Claude Code:

claude mcp add seeflow -- npx -y --package=@tuongaz/seeflow@latest seeflow-mcp

Via .mcp.json (Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "seeflow": {
      "command": "npx",
      "args": ["-y", "--package=@tuongaz/seeflow@latest", "seeflow-mcp"]
    }
  }
}

The MCP server talks to http://127.0.0.1:4321/mcp by default. Override with SEEFLOW_STUDIO_URL if needed.

Develop

git clone https://github.com/tuongaz/seeflow.git
cd seeflow && bun install
make dev   # Vite (5173) + Hono studio (4321), both hot-reloading

make help lists every target. Toolchain: Bun ≥ 1.3, Hono, React Flow, Zod, Biome.

Status

Early-stage. The schema is stable enough to author against, but expect changes. Issues, ideas, and PRs welcome.

License

MIT — see LICENSE.