Start and follow a run
Start a run, read where it is, act on its steps, and recover from conflicts
A run executes a snapshot of a published workflow version. Editing or republishing the workflow later does not change a run that already started.
You need at least one published workflow. Anyone signed in can read every run.
Start a run
- Open Runs and choose Start run. You can also choose Start run on a published workflow version, which selects that workflow for you.
- Choose a workflow. The list shows the latest published version of each one.
- Enter a title, up to 200 characters.
- Enter the input as Markdown source, up to 50,000 characters. The placeholder shows what the workflow asks for.
- Choose Start run.
The run opens on a canvas of its steps, laid out left to right like the workflow. Steps with no dependencies are Ready. The rest are Blocked until the steps they depend on pass or are skipped. You become the requester. If no workflow has been published, the form is replaced by a link to Workflows.
Find a run
Runs lists each run with a status icon, its title, workflow and version, and a progress bar with one segment per step in workflow order, colored by state. Now names the steps it is waiting at, or the status once it has closed. Waiting on, Waited and Age show who holds it up, for how long, and how old it is. Choose All, Running, Completed or Cancelled to filter. The filter and sort are part of the page address, so they survive a reload. Load more shows older runs.
To clear the most stuck work first, set Sort to Oldest waiting. See Review gates and see who runs wait on.
Read a run
The top bar shows the title, status, workflow and version, requester, age, and a progress bar. Input unfolds the run's input. URLs in the input are clickable. Markdown is shown as source and is not rendered.
Below it, the canvas shows every step and how work flows between them. A connection is solid once the step it leaves has finished, and dashed until then. Drag the canvas to pan and scroll to zoom. Positions come from the dependencies, so a run does not keep the layout you arranged in the workflow editor.
Each node shows:
| Part | Meaning |
|---|---|
| Color bar | The state, repeated by the icon and label: Blocked, Ready, In progress, Awaiting gate, Passed or Skipped |
| Age | Time in the current state. Hover for the exact time |
| People | The owner, then the executor when it is someone else. A robot icon marks an agent |
| Gate | Who approves the step, or No gate |
| Deliverables | The latest version of each one. Missing marks a required one on a step in progress |
| Footer | Who the step waits on, or which steps it needs first, with your next action on the right |
Activity in the top bar opens a drawer with who the run is waiting on and the timeline.
Pages refresh when you return to the window and after your own actions. They do not update by themselves while you watch.
Work on a step
Choose a node to open the step in the drawer beside the canvas. The canvas stays usable, and it pans if the node would end up out of view. Choose another node to switch steps. To close the drawer, choose the close button, press Escape, or choose the empty canvas. On a narrow window the drawer sits over the canvas, so drag the canvas to reach a node beneath it.
The drawer holds the step's state and people, its actions, then its purpose, gate, deliverables, comments and brief. Only the actions you can take right now appear.
| Action | Who | When |
|---|---|---|
| Start | Executor or owner | Ready |
| Submit | Executor, or the owner when the executor is an agent | In progress or Passed |
| Mark done | Executor, or the owner when the executor is an agent | In progress |
| Skip | Owner | Ready, In progress or Awaiting gate |
| Reassign | Owner | Ready, In progress or Awaiting gate |
Quick actions
A node's footer offers your next action without opening the drawer, so you can move several steps along from the canvas.
| Quick action | Appears when | What it does |
|---|---|---|
| Start | You can start the step | Starts it |
| Mark done | You can mark it done and every required slot is in | Marks it done, asking first if the step has no gate |
| Submit | You can mark it done but a required slot is empty | Opens the drawer |
| Review | You can approve its gate | Opens the drawer |
The step open in the drawer shows no quick action, because the drawer holds the same actions.
Agents cannot sign in yet. When the executor is an agent, its owner sees Acting for with the agent's name, and each submission reads "by Bo for codex-agent".
Use the brief
Copy puts the brief on your clipboard as Markdown, ready to paste into any agent. It holds the run input, purpose, the latest deliverables this step receives from the steps it depends on, the expected deliverables and the gate. A dependency with no mapped deliverables passes all of them. If copying fails, the app selects the brief so you can copy it by hand.
Submit deliverables
Each slot is a document or a link. Write document opens the document editor, and a link slot takes a URL and an optional title. Every save or submit adds a numbered version, and history keeps them all. The history starts on the latest version. Choose another version to read it and its comments.
Unsaved text survives background data refreshes and failed requests, but is not saved across browser reloads. If you try to leave or reload, the app asks first; continuing discards the text. If a step stops accepting your submission while you are typing a link, your text stays on screen so you can copy it.
Mark done
Mark done stays disabled until every required slot has a submission, and the missing slots are named next to it.
- With an approval gate, the step moves to Awaiting gate. Submit or discard your drafts first, because a step at its gate accepts no new versions.
- Without a gate, a dialog warns that the step passes now. Passed steps cannot reopen, though they still accept new deliverable versions.
A step awaiting its gate moves on when its approvers decide. See Review gates and see who runs wait on.
Skip, reassign and cancel
These cannot be undone.
- Skip needs a reason. The dialog names the steps that become ready and any that still wait on something else.
- Reassign needs a different executor. The old executor can no longer submit. State and submissions stay as they are.
- Cancel run is for the requester of a running run. It freezes every step where it is and removes all actions. The dialog shows how many steps are unfinished.
Recover from problems
- A message says the step changed: someone acted first. The page reloads the step and the run. Your unsaved text stays.
- A request failed: the app shows the error and keeps what you typed. Try the action again.
- Could not load this page or the brief: choose Retry.
- Run not found or Step not found: the address is wrong, or the step belongs to a different run. Follow the link back to Runs.