# SeeFlow

> Architecture diagrams that actually run, generated by AI agents.

![SeeFlow](./demo.gif)

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

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

Requires Bun ≥ 1.3 (or Node with npx). The studio scans `$(pwd)/flow.json` on start and auto-registers that flow if present. The studio's registry persists under `~/.seeflow/` across restarts.

<details>
<summary>Prefer Docker? (not recommended)</summary>

> ⚠️ **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.

```bash
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/flow.json` on start.

</details>

### 2. Install the plugin

**Skill installer (recommended):**

```bash
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.

### `/seeflow-lookup` — consult an existing flow

Once a flow is registered, agents can read it back as architectural ground truth:

```
/seeflow-lookup list                                    # catalog of registered flows
/seeflow-lookup flow <id>                               # nodes + connectors (no detail content)
/seeflow-lookup node <flowId> <nodeId>                  # single node with detail/html inlined
/seeflow-lookup flow <id> --full                        # everything inlined
/seeflow-lookup node <flowId> <nodeId> --with-scripts   # adds play.ts / status.ts bodies
```

Read-only. JSON output. Start cheapest (`list`) and drill in.

## Component nodes

The `component` node type turns a canvas node into a json-render-powered reactive UI driven by a small catalog of shadcn-styled primitives (Card, Button, Input, Chart, Markdown, etc.). The spec lives at `<project>/nodes/<id>/spec.json` — declaring an element tree, optional initial state, and a typed action vocabulary — while `flow.json` carries only the `type: 'component'` tag. Two action kinds are supported: `set` actions mutate local state via JSON Pointer paths, and `script` actions POST to `/api/flows/:id/nodes/:nodeId/actions/:name` which spawns the matching script under `nodes/<id>/` (e.g. `nodes/<id>/actions/<name>.ts`) and merges the JSON response back into state.

## 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](https://hub.docker.com/r/tuongaz/seeflow). See Quick Start above for the basic `docker run`.

### Configuration

| Variable            | Default                 | Description                                |
| ------------------- | ----------------------- | ------------------------------------------ |
| `SEEFLOW_PORT`      | `4321`                  | Port the studio listens on                 |
| `SEEFLOW_FLOW`      | `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:

```dockerfile
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:**

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

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

```json
{
  "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.

## MCP Apps

On hosts that support the [MCP Apps](https://github.com/modelcontextprotocol/mcp-apps) spec (Claude Desktop today), `seeflow-mcp` renders the live React Flow canvas inline in the chat — no second window, no `localhost:4321` tab. You author, navigate, and edit the flow from the same conversation that produced it.

**Install in Claude Desktop** — add an entry to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

When launched this way, `seeflow-mcp` boots an embedded studio on a loopback ephemeral port (the same Hono backend used by `seeflow start`) and serves the iframe canvas as the `ui://seeflow/canvas` resource. One process, one install, no separate studio to run.

**The 5 canvas-bearing tools** open the canvas inline:

| Tool                     | Renders                                                |
| ------------------------ | ------------------------------------------------------ |
| `seeflow_get_flow`       | The flow's canvas (read view).                         |
| `seeflow_get_flow_graph` | Same canvas, with the topology focused.                |
| `seeflow_get_node`       | The canvas with the requested node selected + opened.  |
| `seeflow_register_flow`  | The newly-registered flow in edit mode + "Just created" highlight. |
| `seeflow_create_project` | The new project's canvas in edit mode.                 |

The remaining 18 tools stay JSON-only — their mutations propagate to any open canvas via the studio's SSE channel, no re-render needed.

**Model-notify split.** Edits inside the canvas reach the model through two channels:

- `sendMessage` — structural edits the model should react to (node added / deleted, connector added / deleted, node renamed, Play / Status pressed). Bursts within 200ms are coalesced.
- `updateModelContext` — silent navigation telemetry (selection, hover, drag-in-progress, viewport pan/zoom). Debounced 250ms, throttled to at most 1/sec.

**Non-Apps hosts are unaffected.** The `_meta` payload is additive: hosts that don't grok `openai/outputTemplate` ignore it and continue to receive the same JSON tool responses they've always received. The existing `claude mcp add seeflow …` flow above keeps working unchanged on Claude Code, Cursor, Windsurf, etc.

See [`docs/plans/2026-05-25-mcp-apps-for-seeflow-design.md`](./docs/plans/2026-05-25-mcp-apps-for-seeflow-design.md) for the full design — architecture, bidirectional channels, CORS / per-process-token model, and lifecycle.

## Develop

```bash
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`](./LICENSE).
