All guides

Running a Workflow

A Workflow runs a plan with many agents. A lead agent splits the plan into tasks. SimpleEdit runs each task in a hidden worker session and shows progress as a live graph. You start the run, and you pass every review gate yourself.

The lead plans and decides; it doesn’t write code. Each worker does one task in a fresh context and reports a short result to the lead. Steer by changing the plan with the lead. Type into a worker’s terminal only to nudge one task.

Use a Workflow when you have:

Before you start

1. Ask the lead to create the workflow

In the session that holds the plan, ask the agent to turn the plan into a workflow. For example: “Create a workflow for this plan. One task per PR, then a review gate.”

The agent becomes the lead and writes a task graph. Each task has a brief, dependencies, and an agent and model. A task can be:

Ask for the shape in plain words: “Make the API task a loop with a Codex reviewer.” “One task per package.”

Once the workflow exists, you can compact the lead’s conversation (for example /compact in Claude Code). The workflow, briefs and plan doc hold what the lead needs, so later wake-ups start from a short context.

2. Review the graph

  1. Open the lead’s Workflow tab. In the sidebar, the lead’s session also offers Open the workflow.
  2. Read the Goal and each task card. Select a card to read its Brief and what Done means.
  3. Select Show patches (n) to see every change the lead made to the graph.

The graph is the first review gate. Tell the lead what is wrong; it patches the graph, and the patch shows as “since you approved”.

3. Start

Select Start. SimpleEdit starts a worker for each task whose dependencies are done, up to the worker limit. Workers don’t show in the sidebar.

If a worker stops at its provider’s folder-trust prompt (or Codex’s hook review) before its first turn, its card says it is waiting and shows Trust folder (or Trust Codex hooks), and the task appears in Needs you with the same button. Only your click answers the prompt; SimpleEdit changes no provider settings.

Task states:

CardMeaning
○ QueuedWaits for its dependencies.
Waiting for a worker slot (Claude 4/4)Ready, but all workers of that provider are busy. It starts when one is free.
▶ RunningA worker is on it.
● Waiting on youThe worker asked a question.
◆ Waiting on the leadThe lead must decide something first.
✓ DoneThe worker reported its result.
✕ CancelledThe task was cancelled.
✕ Failed, ✕ Worker stoppedThe task did not finish. The lead gets a judgment to decide what to do.

A loop task has its own states:

CardMeaning
▶ Round n of m · workingA worker is on the task. From round 2 on, it reads “A fresh worker fixes round n findings”.
◇ Round n of m · in reviewA fresh reviewer checks the worker’s result.
✓ Clean after n roundsThe reviewer found nothing more. The loop is done.
◆ Didn’t converge · needs the leadThe last round still had findings. The lead decides what happens next.
✓ Accepted · n open findingsThe lead accepted the work with the findings still open.
✕ Reviewer failedThe reviewer did not finish.

Select a card to open its worker’s terminal.

A worker stops when its task is done or failed, and a reviewer stops when it has given its verdict. Mid-turn, it stops when the turn ends or after 30 seconds; typing into it before then keeps it running. Its conversation is kept: select its card (“This worker stopped when its work was done.”) and Resume to continue it.

Loops: agents check each other

A loop is a task where a reviewer agent checks the worker’s result every round.

  1. A worker does the task on its own branch and reports done.
  2. A fresh reviewer reads the branch and reports “clean” or a list of findings.
  3. With findings, a fresh worker gets the brief, the branch and the findings, and fixes them. A fresh reviewer checks again.

Each round starts new sessions. The lead sets the rounds per loop: 1 to 5, 3 by default.

Cross-provider review. The reviewer can run on another provider than the worker, such as Codex reviewing Claude’s work. Workers and reviewers can run on Claude, Codex or OpenCode. Ask the lead: “Use a Codex reviewer for this loop.”

When a loop doesn’t converge. If the last round still has findings, the card shows ”◆ Didn’t converge · needs the lead”. The lead can give the loop more rounds (at most 10 in all) or accept the work as it is. It often finds the plan is the problem; then it asks you and you adjust the plan together.

Look inside a loop. Select the card to see its sessions: the current Worker, the Reviewer · round n, and earlier workers as “Worker · round n”. They stay listed until you dismiss the workflow. Select Resume on one to ask it something.

4. Answer when you are needed

The lead wakes only for judgments, such as a failed task or a loop that doesn’t converge. It answers by patching the running graph (a fix task, a new brief) and the run goes on. Every patch shows under Show patches (n). When something waits for you, the lead’s dot turns amber and the item shows under Needs you.

5. Pass the review gates

A review gate (⛩) stops the run until you review the work before it.

  1. When the tasks before the gate are done, the gate opens one review per PR stack the tasks made. The reviews open as tabs in the lead’s workspace.
  2. Select the stack’s row on the gate card, or Open review under Needs you. While your review is open, the card reads ”● Waiting on your review · n stack(s)”. A gate with no stacks reads ”● Waiting for you to accept”.
  3. Review the stack in the Review Room. See Reviewing a PR stack.
  4. Submit the review. A gate’s review goes to the lead only. It never posts to GitHub.

What happens next depends on your verdict:

Only you can pass a gate. The lead cannot.

If you discarded a review, select Re-request to open it again.

6. Finish

When all tasks are done, select Dismiss. This closes the workflow’s worker sessions and archives the workflow.

To stop a running workflow, select Cancel. The workers move to the sidebar as normal sessions, so no work is lost.

Usage

Each task card shows its worker’s tokens. The status line shows the total.

On the phone

The phone shows the graph and progress. You can Start a drafted workflow, open a gate’s review and Accept a gate there. Cancel and Dismiss are desktop only.

Workflowrecurring invoices
▶ Round 1 of 3 · working↻ 1/3
Recurring invoice schedule feat/recurring-invoices Claude
◇ Round 1 of 3 · in review↻ 1/3
Recurring invoice schedule feat/recurring-invoices Claude
▶ Round 2 of 3 · working↻ 2/3
Recurring invoice schedule A fresh worker fixes round 1 findings Claude
◇ Round 2 of 3 · in review↻ 2/3
Recurring invoice schedule feat/recurring-invoices Claude
✓ Clean after 2 rounds↻ 2/3
Recurring invoice schedule feat/recurring-invoices Claude
● Waiting for you to accept⛩ gate
Review before merge Accept
Worker · round 1:
Schedule model and next-run date are in.
Reviewer · round 1:
Two findings: the schedule skips month ends, and nothing tests it.
Worker · round 2:
Month ends handled, tests added.
Reviewer · round 2:
No findings.
Only you pass a gate. Nothing after it starts until you accept.