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:
- Big steps, one after another. Fresh contexts keep a long project from filling one session.
- A plan you may change. When a task fails, patch the running graph instead of starting over.
- Parts that can run at once, for example one PR per package.
- Work another agent should check. A loop task puts a reviewer on the result every round.
Before you start
- Agree on the plan first. See Reviewing plans with SimpleEdit.
- Check Settings → Workflows:
- Workers at once sets how many workers run in parallel, per provider (1–16, default 4). Claude, Codex and OpenCode count separately, each with its own row. An OpenCode model always uses the OpenCode row. A local model always runs one at a time.
- Leads may start workflows: when it is off, nothing runs until you select Start. Keep it off until you trust the lead’s plans.
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:
- A plain task: one worker does it.
- A loop: a worker does the task, and a fresh reviewer agent checks the result every round. See Loops: agents check each other.
- A fan-out (map): one earlier task reports a list, such as packages to migrate. The lead’s template runs once per item, in parallel.
- An integrate task: a worker combines the branches of earlier tasks into one PR, a stack, or one PR per branch.
- A review gate (⛩): no worker. You review the work before it. See step 5.
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
- Open the lead’s Workflow tab. In the sidebar, the lead’s session also offers Open the workflow.
- Read the Goal and each task card. Select a card to read its Brief and what Done means.
- 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:
| Card | Meaning |
|---|---|
| ○ Queued | Waits 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. |
| ▶ Running | A worker is on it. |
| ● Waiting on you | The worker asked a question. |
| ◆ Waiting on the lead | The lead must decide something first. |
| ✓ Done | The worker reported its result. |
| ✕ Cancelled | The task was cancelled. |
| ✕ Failed, ✕ Worker stopped | The task did not finish. The lead gets a judgment to decide what to do. |
A loop task has its own states:
| Card | Meaning |
|---|---|
| ▶ Round n of m · working | A worker is on the task. From round 2 on, it reads “A fresh worker fixes round n findings”. |
| ◇ Round n of m · in review | A fresh reviewer checks the worker’s result. |
| ✓ Clean after n rounds | The reviewer found nothing more. The loop is done. |
| ◆ Didn’t converge · needs the lead | The last round still had findings. The lead decides what happens next. |
| ✓ Accepted · n open findings | The lead accepted the work with the findings still open. |
| ✕ Reviewer failed | The 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.
- A worker does the task on its own branch and reports done.
- A fresh reviewer reads the branch and reports “clean” or a list of findings.
- 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.
- 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.
- 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”.
- Review the stack in the Review Room. See Reviewing a PR stack.
- Submit the review. A gate’s review goes to the lead only. It never posts to GitHub.
What happens next depends on your verdict:
- You asked for changes: the lead adds fix tasks and reworks the gate. The card shows “Lead reworking”. When the fixes are done, the gate opens the next round of the review.
- You approved: select Accept on the gate, then Confirm accept. The tasks after the gate start.
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.