Using the App

Implemented

jigspec app is the interactive entry point — a single local process that hosts your run list, your pipeline editor, and a live execution viewer at one URL. Reach for jigspec run when you want a headless, script-friendly execution; reach for jigspec app when you want to look at things, edit pipelines visually, or watch a run unfold in real time. Hash routing means the three views all live under the same server: one URL, three views.

Starting the app

The same command opens whichever view you want, depending on the args:

# Run list — every run discovered in your cwd tree
jigspec app

# Editor — open this pipeline file directly
jigspec app pipeline.pipe.yaml

# Viewer — jump straight to a specific run
jigspec app --run abc123

The CLI picks an open port (default 4400), launches the server, and opens your browser. For the full flag list — --port, --host, --no-open, --json — see jigspec app in the CLI reference.

One process, many pipelines

The app is process-wide, not pipeline-wide. One running server can serve every run in your repo, every pipeline file you open, and every armed trigger across all your .pipe.yaml files. You don't start a new server per pipeline.

The run list

http://127.0.0.1:4400/#/

The root view is a table of every run JigSpec can find under your current working directory. It walks the tree looking for .jigspec/runs/ directories — so any run you've executed anywhere in your repo shows up here, not just runs at the top level.

Each row shows:

Column	What it means
Pipeline	The pipeline name (or run ID if the name isn't recorded)
Status	Pill: LIVE (running right now), done, failed, running, interrupted, or unknown
Duration	Wall-clock duration if completed
Cost	Total USD spent on AI calls during the run
Started	Relative time since the run began

Live runs are sorted to the top and pulse green; everything else is sorted most-recent first. The list polls every 3 seconds, so a run you kicked off in another terminal will show up without a refresh.

Click a row to open the viewer for that run.

The editor

http://127.0.0.1:4400/#/edit/<file>

Opening a .pipe.yaml lands you in the visual editor. The layout is three panes:

• Sidebar — file browser, registry browser (drag a community pipeline in to extend yours), and pipeline-level config (input schema, secrets, default model)
• Canvas — a node graph of your steps, with edges showing data flow between them
• Config panel — slides in from the right when you click a step, with a form-driven editor for that step's fields

Each step renders as a node. Drag from a sidebar action (ai, code, …) to add a step; click a step's node to edit it; delete a step from its config panel. Edges are inferred from your {{ step.field }} references — when you reference an earlier step's output, the editor draws the wire for you.

Above the canvas, the toolbar gives you:

• + New — start over from the template picker (with an unsaved-changes prompt)
• Open — pick a different .pipe.yaml from your repo
• → LR / ↓ TB — toggle graph layout direction
• Test Run — execute the pipeline from inside the editor; opens a drawer with input prompts and live output
• Save — write the YAML back to disk (Cmd/Ctrl+S also works)

Validation as you type

The editor revalidates against the JigSpec schema about every 50ms while you edit. Errors are mapped onto the offending step's node and surface inline in the config panel — no need to switch to a terminal to run jigspec validate. Pipeline-level errors (missing name, malformed input, etc.) appear in a global banner.

Save without fixing all errors

Save still writes the file even when validation fails — you'll get a "Saved (with warnings)" indicator. The file is on disk, but jigspec run will reject it until the errors are gone.

Unknown fields are preserved

If your YAML has fields the editor doesn't know about (custom annotations, comments-as-fields, future spec extensions), they're preserved on save. A banner tells you how many unknown fields are in the file so you know they're being kept.

The run viewer

http://127.0.0.1:4400/#/run/<id>

The viewer shows a single run — either still executing or finished. It has two surfaces:

• The graph — every step as a node, colored by status. Nodes pulse blue while running, turn green when done, red on failure.
• The detail panel — slides in from the right when you click a step. Shows that step's status, duration, cost, token counts, prompt (for ai steps), inputs, outputs, and a timeline of trace events.

Live runs stream over Server-Sent Events: as the runtime fires step.start and step.complete events, the graph reshapes itself in real time. You can leave the tab open during a long run and watch each step land. For finished runs, the SSE stream replays the recorded events on connect, so the graph fills in instantly.

The toolbar shows the run ID, a Running / Complete badge, an All runs link back to the list, and a layout-direction toggle. On mobile the graph is replaced with a vertical step list — tap a step to drill into the same detail panel full-screen.

The triggers panel

http://127.0.0.1:4400/#/triggers

The triggers panel is a single table listing every armed trigger across every pipeline the server knows about. One process, many pipelines, one place to see what's armed.

Each row shows:

Column	What it means
Pipeline	The pipeline name the trigger belongs to
Type	manual, file, cron, conversational, or ambient
Pattern	The cron expression, glob, or trigger-specific pattern
Timezone	Timezone for cron triggers
Concurrency	skip, queue, or allow — how overlapping fires are handled
Last fired	Timestamp of the most recent fire
Last run	Click-through link to the run viewer for the most recent fire
Next run	For cron triggers, the computed next-fire timestamp

When a trigger fires, a new run appears in the run list and you can click through from this panel directly into its viewer. For the trigger spec — what types exist, how to declare them, and how concurrency works — see the Triggers reference.

Empty panel?

If the panel says "No triggers declared," none of your .pipe.yaml files have a triggers: block. Add one to a pipeline and reload — the server picks up triggers from any pipeline file in your cwd tree.

Bug reporter

Anywhere in the app, a small floating "Report a bug" button appears in the bottom-right corner. Clicking it opens a panel that captures a DOM snapshot, recent console logs, and the current Zustand store state, then writes them as a bug report into a .bugs/ directory next to your pipelines.

There's an opt-in toggle inside the panel: Run bug-fix pipeline. When enabled, submitting a report kicks off a debugging pipeline against the captured state — useful for reproducing UI bugs you hit while watching a run go sideways. Watch your dev terminal for the bug-fix pipeline's progress.

Tips

Expose on your LAN. The server binds to 127.0.0.1 by default. To browse from your phone or another laptop on the same network:

jigspec app --host 0.0.0.0 --port 8080

Script the URL. --json writes the URL and port as one JSON line on stdout (and disables the auto-open). Useful when you want to launch the app from another tool:

URL=$(jigspec app --json | jq -r .url)
echo "Server at $URL"

Ctrl+C is safe for in-flight runs. The server handles SIGINT and SIGTERM gracefully. Any pipelines that are mid-execution when you shut down keep running in detached child processes — they finish on their own and their results show up in the run list next time you start the app. You don't have to babysit a long pipeline just because the viewer is open.

One server, many tabs. Because routing is hash-based, you can open the same http://127.0.0.1:4400/ URL in multiple tabs and put each on a different view. One tab on #/ to watch new runs appear, one on #/run/<id> to follow a slow run, one on #/edit/<file> to keep editing — all served by the same process.

Next steps

• CLI reference — every flag for jigspec app
• Triggers — declare cron, file, and other trigger types
• Pipeline reference — the YAML spec the editor is reading and writing