forgev0.19
Docs pages

forge-ui

forge-ui is an optional page on your own machine that shows runs as they happen. It answers two questions at a glance: where is this run, and why did that task pass or fail?

Opening it

At the start of every new run forge asks "Open forge-ui to watch this run? [y/N]" and never opens it without a yes. Or open it any time:

forge ui open            # the list of runs
forge ui open "$PLAN"    # one run
forge ui status
forge ui stop

It's one small server on 127.0.0.1:8765 that every run shares, and it stops after four idle hours. If it can't start, the run carries on. Offline, the 3D view can't load its library and the page switches to 2D. Both themes are finished; your system decides.

To look around before your first run, open it on made-up runs from a checkout of forge:

python3 ui/tools/demo_runs.py /tmp/forge-demo
(cd ui && python3 -m forge_ui --no-registry --root /tmp/forge-demo --open)

What it shows

The map
Every run as a block, grouped by repository, with a lamp per task. Filter by state, repository, model, age or verdict.
The run cloud
Every run at once, full screen in 3D, in five layouts: helix, sphere, galaxy, timeline and constellation. Drag runs anywhere; it remembers.
A run's plate
Tasks as blocks in their planned waves with dependency cables, ending in integration, verification and the final review. Findings stand over their block, shaped by severity. Choose a task to light its route.
Execution
The same run on the clock: one block per attempt in the lane it ran in, failed ones in red, with the critical path named.
Files
A heatmap of which task planned, touched or drifted into which file, wave by wave.
Diffs
Any diff of a task, or exactly the diff one reviewer read, with every finding pinned under the line it names.
Conversations
What each dwarf and reviewer said, ran (with exit codes) and changed, read from its CLI's own log, live while it runs.
Models
A leaderboard of your models on your runs: first-attempt pass rate with a confidence interval, retries, escalations, time and tokens.
Projects
One page per repository: its runs, every finding of every review, and what its memory gives each role.
Worktrees and disk
Every worktree forge created and its state, and what forge takes on disk, each with the command that safely removes it.

The lamps mean one thing everywhere: amber running, green merged, red failed, unlit pending. Every state also has a text label.

Where a task stands

A running task names the model at work, the command it's running and for how long, and flags a log that has gone quiet. A waiting task says what it waits on: another task, a free slot, a drain, or a paused provider with a countdown. The task inspector opens on its goal, acceptance criteria and links, then an attempt trail saying why each attempt ran, then its summary and its brief questions with answer boxes.

Changing a run from the page

forge-ui reads everything and changes things only by calling forge's own commands, so the page and the terminal share one set of rules and one log. Every change asks you to confirm. Start it with FORGE_UI_READONLY=1 forge ui open to make it watch-only; it then shows each command to copy instead of a button.

  • Worktrees: select finished or failed worktrees, or all of them, and remove them in one go. A dry run says first what goes and what's skipped and why; one in use, dirty or still needed can't be selected.
  • Memories: on a project's Memories tab, select learnings and forget them. The confirm lists what memory.md loses.
  • Disk: compact one run or all of them, with the space it frees shown first.
  • A waiting task: answer its question in the task panel.

Privacy and sharing

Everything stays on your machine. Any local program can read what the page shows; changes need a token the server makes at each start, and it checks where requests come from. A run can be exported as one HTML file that opens without forge-ui, with prompts, diffs and local paths left out unless you include them.

Full reference Every flag and edge case: docs/forge-ui.md