SeeFlow

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)/flow.json on start and auto-registers that flow if present. The studio's registry persists under ~/.seeflow/ across restarts.

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

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.

/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.

Icon packs

Cloud vendor icons (AWS, GCP, Azure) install on demand into a local cache. Icon ids encode the vendor as a prefix — aws:lambda, gcp:cloud-run, azure:functions, iconify:logos:google-cloud — while unprefixed names continue to resolve against the bundled Lucide set.

CLI

seeflow icons list                 # JSON summary of installed + available packs
seeflow icons add aws              # download + extract + index the AWS pack
seeflow icons add azure --accept-terms   # Microsoft requires explicit acceptance
seeflow icons add gcp --pack-url <url>   # override the default download URL
seeflow icons update aws           # re-install (re-downloads from upstream)
seeflow icons remove aws           # drop the pack from cache + index

Packs install under ~/.seeflow/icons/<vendor>/<version>/ with a shared index.json. Installs are serialized per vendor — a second seeflow icons add aws while the first is running waits rather than racing.

In the studio

Open any icon picker on a canvas node, click Browse packs in the picker footer, then Install on the vendor row. Azure prompts for license acceptance; AWS and GCP proceed directly. A progress toast tracks bytes downloaded, persists across popover close, and refreshes the picker's vendor tabs the moment the pack is indexed. Vendor tabs (Bundled · AWS · GCP · Azure · Logos) appear above the icon grid; uninstalled vendors render disabled with an inline Install affordance.

Docker reference