Skip to main content

Run and manage workflows

Workflow runs preserve progress, so you can leave and return without replaying completed work. Across IDE, CLI, and Web, the run remains connected to its parent conversation while Kiro checkpoints node status, outputs, artifacts, repeat progress, watch cursors, and step sessions at durable boundaries. Displayed elapsed time counts active execution and excludes time the run spends paused.

Follow progress from the parent chat

A background workflow does not block the main conversation. Kiro can acknowledge the launch, return progress while steps run, inspect the completed run and its artifacts, and synthesize the outcome in the parent chat. The Workflows overview traces one such run end to end.

In Kiro Web, the parent session and run details remain visible together:

  • Workflows shows runs, nested nodes, status, elapsed time, agent, model, effort, and step activity.
  • Summary shows the synthesized session outcome.
  • Files lets you inspect workspace files produced or changed during the run.
  • Artifacts shows outputs explicitly exposed by the workflow.

A progress update in the parent chat and a direct message to a selected step serve different purposes. Ask the main agent to interpret progress, resolve a broader issue, or decide what should happen next. Message the step when the guidance applies specifically to that agent's current task.

The channel between the parent chat and a step runs both ways, at any point in the run. A step reports outward through its send_message signals. Guidance reaches the step by either route: message the selected step directly in your client, or tell the main agent in the parent chat what the step should do and it delivers that guidance into the step's session. A running step picks the guidance up on its next turn; a paused step treats it as the reply it was waiting for.

Find and inspect a run

Open Workflows above the parent chat. The area lists the session's runs. Expand a run to inspect its step tree and status, then select a step to open a dedicated Workflow step tab. The tab identifies the step and agent, preserves the step's own message history, and can remain beside the parent chat while the run continues.

Use the Search workflows field to filter runs by name, status, or recorded duration. Select Clear search or press Escape to restore the full list.

The run list groups runs by status, with Needs you first. Only groups with runs appear.

In Kiro IDE 1.4.86 and later, select Open run on a run's card in the parent chat to work inside that run. Kiro opens the run in its own Workflow tab, with the step tree docked beside the selected step's transcript and Pause, Resume, and Stop in the tab header. The tab title reads Workflow: followed by the run name. The tab stays open across a window reload and remembers where you docked the step tree.

In Kiro IDE 1.4.178 and later, the tab header also shows:

  • Created by: and the name of the chat that launched the run. Select the name to open that chat.
  • Go to active, which selects the oldest step that is running, paused, or waiting on you.
  • A Follow switch, which keeps the active step selected and moves to the next one as each step finishes. Selecting a step yourself turns Follow off.

In Kiro IDE 1.4.178 and later, hover a step's title to see its status and, when available, its agent, model, and effort on one line. To resize the step tree, drag its edge, or focus Resize workflow steps and press Left Arrow or Right Arrow. Press Home or End to jump to the smallest or largest width.

The parent run card shows Pause and Stop while work is active. Expanded step details show the selected agent, model, effort, and activity. Launch and completion updates in the parent chat can also expose the run name, ID, task, output artifact, elapsed time, and estimated usage when available.

Messages from steps arrive in the parent chat as collapsed notification rows. Select a row to read its full message. Each row can show:

  • the step name;
  • the agent name, when it differs;
  • the run name;
  • Info, Completed, Needs input, or Failed;
  • the time.
StatusStep action
Info or CompletedOpen step session can appear when Kiro knows the source session.
Needs inputAnswer followed by the step name appears when the row has a live step session.
FailedOpen followed by the step name appears when the row has a live step session.

Rows without a known step session have no step action. Run outcome rows, such as completed or stopped runs, stay on one line and do not expand.

A run that requires input can surface a Needs you state. Return to the run and select the paused step to answer it directly. You can also select Answer on its notification row. Or ask the main agent to pass your answer to that step.

Understand run status

A run reports one of five statuses, and paused covers three different situations that call for different responses. The controls a client offers differ by surface; the statuses, and what moves a run between them, are the same everywhere.

StatusMeaningYou canIt moves on when
runningKiro is executing or scheduling nodesPause (takes effect at the next node boundary; status stays running until then) or Stopa step asks for input (paused), every required top-level node completes (completed), or a node fails (failed)
paused · needs inputA step called send_message with severity warning and is waiting for youReply in the paused step (the run stays paused while that turn runs) or Stopthe step signals success (running) or error (failed), or asks again (stays paused)
paused · at a boundaryA requested pause took effect at a safe node boundaryResume from persisted state, or Stopyou resume (running)
paused · iteration capA repeat reached maxIterations with onMaxIterations: "pause"Resume, which does not add iterations, so the repeat reaches the same cap and pauses again; Add loops (IDE), Run N more (Web), or Run 1 more iteration (CLI 3.2.0 or later) to grant more iterations; or Stop; or revise the remaining planyou grant more iterations (running), you stop, or a revised plan replaces the remaining work
completedEvery required top-level node completedInspect the run and its artifactsterminal
failedA node failed and the failure propagated to the runRetry when the failed nodes are retryable: failed targets reset, completed siblings are keptyou retry (running), otherwise terminal
abortedThe run was stopped, or a repeat used onMaxIterations: "abort"Retry when retryable work remainsyou retry (running), otherwise terminal

Nodes can also be pending or skipped. Each repeat iteration creates a fresh set of state entries for its body, so the same static node ID can appear once per iteration. Which of these controls each client exposes is listed under Choose the right run control.

Review-loop decisions in V3

When a workflow review loop rejects work twice, Kiro pauses the run. The parent session asks whether to grant another review pass or move on. Your choice controls the remaining loop without replaying completed work.

Respond when a step needs input

A step can ask for information and pause without losing its session context. The step agent signals this by calling send_message with severity warning; Kiro parks the step and run until you reply.

Your reply has to reach the paused step's session. The direct route is to open that step in your client and answer there; the tabs below show where. You can also answer through the parent chat by asking the main agent to pass your answer to the paused step, and it delivers the reply into the step's session for you. A plain message typed into the parent chat without that instruction is a conversation with the main agent, not a reply to the step.

  1. Open Workflows above the parent chat.
  2. Expand the run.
  3. Select the paused step. Kiro opens its dedicated Workflow step tab.
  4. Send a normal text reply in Message this step's agent.

You can also expand the step's Needs input notification row in the parent chat and select Answer followed by the step name to open the same tab.

Kiro routes the message through the parked step and runs another turn in the same backing session. The run remains paused until the step completes or fails.

Whichever route you take, the reply lands in the paused step's own session; the parent chat is at most the place you typed it. Three things decide what happens next, and the figure below follows one reply through all of them: the step continues with its history intact; its next send_message signal picks the branch; and only success moves the run on to the next node in a new session. A warning pauses the same session again, and an error ends the run.

Figure 3.2: paused step · the reply returns to the same session
1/6
Paused. Step 1 of 6.

Select a node, or play the run.

Paused step · session 7f2

next send_message

warning↺ stays in 7f2, pauses again
errorends: run fails

triagesession 7f2 · paused · waiting for your input

Send_message · warning.

triage asks for input and the run pauses

Where it goes: session 7f2, typed there or relayed by the main agent. The parent learns the outcome only when the step signals.

your reply lands in the paused step's own session; its next signal picks the branch, and only success moves on to a new session

The flow above is Kiro's built-in pause when a step asks for input. A recipe author can also make a step explicitly interactive with completion, which keeps the step open after each reply until a condition is met:

json
{ "type": "step", "id": "triage", "agent": "wf-planner", "prompt": "Investigate the flaky test and refine a fix plan with the user.", "completion": { "completionSignal": "success" } }

After each turn, Kiro evaluates completion. If it remains false, the step waits for another message in its session.

Interactive steps cannot run inside parallel, because Kiro cannot park one branch for input while its siblings continue.

Choose the right run control

ActionMeaning
PauseLet the active agent turn finish, then park at a safe node boundary
ResumeContinue a paused run from persisted state
Stop / CancelInterrupt active work and mark the run aborted without undoing file changes
RetryReset retryable failed work to pending while preserving completed siblings; exposed in CLI and on Web terminal runs with failed nodes

Open the run in Workflows and use the run controls:

  • Pause requests a cooperative pause at the next node boundary.
  • Resume continues a paused run.
  • Stop interrupts active work and marks the run aborted.
  • Add loops appears in the step tree and in the parent chat when a loop pauses at its limit. Enter how many more loops to run and confirm; the run continues, and the parent chat shows the grant as your message.

In Kiro IDE 1.4.86 and later, the header of a run's Workflow tab shows the same controls.

The current IDE UI does not expose Retry. To repeat a recipe after completion or failure, start it as a new run after inspecting the workspace.

Pause safely

Pause is cooperative. Acceptance of a pause request does not mean execution has already stopped. The active agent turn can continue until Kiro reaches the next node boundary. Inspect the run until its status becomes paused before assuming no more agent work is occurring.

Resume

A repeat paused by onMaxIterations: "pause" has exhausted its fixed budget. Resume does not add iterations; the repeat reaches the same cap and pauses again. Revise the remaining plan, or stop the run and launch a corrected recipe as a new run. In Kiro Web, use Run N more or Stop looping and continue instead; in Kiro CLI 3.2.0 or later, use Run 1 more iteration or Mark loop complete and continue. See the Web tab and the CLI tab under Choose the right run control.

Stop or cancel

Use Stop, /workflow cancel, or Ctrl+X only when work must stop immediately. Cancellation can interrupt a step between file operations. Files already changed remain changed. Inspect the workspace and use version control to discard unwanted partial edits before starting again.

Retry

CLI can retry all unsuccessful work or a selected failed/aborted node:

bash
/workflow retry <workflowId> /workflow retry <workflowId> <nodeId>

Kiro resets each retry target to pending and clears its step session, timestamps, captured output, node artifacts, failure metadata, completion metadata, interactive state, and watch state. It reopens terminal ancestors so execution can reach the target while preserving completed sibling work.

Retry does not undo workspace files. Inspect partial edits before retrying. A completed run is not retryable in the current CLI UI; launch the recipe again to create a new run.

Manage several runs

Each run has its own workflow ID and state tree. Recipe files do not isolate output paths, Git branches, or worktrees, so two runs can still edit the same checkout or overwrite the same artifact.

  • In IDE, use the run list under Workflows in the parent session details.
  • In CLI, use /workflow history or /workflow list, then select or pass the workflow ID.
  • In Web, open Workflows beside the parent conversation and select a run from the run list.
  • Give concurrent runs distinct run_dir and artifact paths.
  • Use separate worktrees or workspaces when runs can edit the same files.

When the run finishes

Completion is a handoff, not just a status change. The main agent can inspect the run, read its declared artifacts and relevant files, verify the requested evidence, and summarize the result in the parent conversation.

A useful completion summary names:

  • the outcome and workflow ID;
  • steps completed and any loops or reviews performed;
  • files created or changed;
  • artifacts and machine-readable verdicts;
  • validation performed and anything left unverified.

In Kiro Web, use Summary, Files, and Artifacts to inspect that evidence directly. A recipe or step agent must produce and expose an artifact; not every file created during a run becomes a declared artifact automatically.

Revise work that has not started

A running or paused workflow can replace its remaining top-level plan while preserving nodes that already ran.

  • Completed and currently executing work remains immutable.
  • If a step is active, Kiro queues the replacement until the next step boundary.
  • If no step is active, including while the run is paused, Kiro can apply the replacement immediately.
  • The complete revised tree must still pass schema, ID, nesting, step-count, template, agent, and watch validation.
  • If a queued replacement fails validation, Kiro rejects it and continues with the original plan.

Who may revise a plan is fixed by the run structure:

CallerUpdate its current stepReplace the remaining plan
A step agent at the root level or nested inside one root-level containerYesYes
The parent session that launched the runNo current stepYes
A sub-agent spawned inside a stepNoNo

Agents use update_workflow for both actions. For ordinary outcomes, a step should still signal through send_message; update_status is for deliberate overrides. Kiro IDE asks you to review proposed steps before they run unless a saved permission decision applies; other clients may not expose a manual revision control.

Review proposed steps in Kiro IDE

Kiro IDE shows a permission card before proposed steps run in any of these cases: Kiro creates a workflow from your prompt, an agent adds steps to a run, or an agent replaces the remaining plan. The card previews the proposed steps and their descriptions; a very large plan may show fewer details. If the proposal keeps steps from the current plan, the card lists them under Runs after.

  • Choose Allow to run the proposed steps, or Deny to reject them. When the card also offers Always allow or Always deny, that choice saves your decision for later workflow plan requests, and Kiro applies it without showing the card again. See Interactive approval flow.
  • To ask for changes instead, type your feedback in the chat input and press Enter. While the card is open, the send button's tooltip reads Send feedback on the workflow plan (Enter), and your message goes to the agent as feedback on the plan rather than starting a new turn. The agent revises the plan from your feedback, and once you approve, the steps follow the revised plan rather than the original request.
  • Attachments are not supported for plan feedback. Remove them to send your message; your draft is kept.

Understand watch behavior

A watch node polls an external resource without spending model turns while the resource is idle. Its handler returns one of three outcomes:

OutcomeEffect
idleWait for the next poll
new-activityFinish this watch instance and expose the JSON payload as its output
terminal-stateFinish the watch and latch its terminal flag for a repeat's stopWhen condition

Kiro persists the watch cursor and terminal state with the run, so novelty tracking survives a restart. Across an interruption and recovery, delivery is at least once, so a responder must tolerate a repeated item. If idleTimeoutSec is set, an idle watch ends with a terminal outcome after that duration; without it, the watch can wait indefinitely.

Two handlers are built in. github-pr tracks what it has already reported itself. command runs a program you write once per poll and stores whatever cursor the program returns, so your program decides what counts as new; see Watch anything else with command.

The publish-pr pattern pairs a github-pr watch with a responder inside a repeat; see Publish and respond.

Recovery after an interruption

Kiro persists full workflow state after node transitions. Completed steps, recorded terminal outcomes, paused-for-input state, captured outputs, artifacts, and watch cursors survive at their last durable boundary. An interrupted step without a final signal continues in its existing step session instead of replaying its initial prompt as a new step. If you answer a paused step after Kiro restarts, the same step session resumes and its progress and completion signals continue moving the run lifecycle.

  1. Reopen the parent chat session that owns the run.
  2. Open Workflows above the parent chat.
  3. Expand the run and inspect its status before taking action.
  4. If the run is paused, use Resume or reply in the paused step as appropriate.
  5. If it is failed or aborted, inspect the workspace and launch the corrected recipe as a new run; the current IDE has no Retry control.

A run that still reports running does not accept Resume. Reopen its parent session or monitor and inspect its active step. If it remains running without new output, record the workflow ID and collect client diagnostics before starting a duplicate run; the client has no separate manual "reclaim" control.

For connection failures, a workflow retries the same step session in place for up to 24 hours before pausing the run if the final attempt also fails. The first five minutes retry about once per minute; later attempts use approximately two-minute waits with jitter. A successful turn or an explicit resume starts a new retry window. Service 5xx errors, throttling, and stalled streams use their own shorter retry behavior.

The exact storage layout and process-ownership records are implementation details, not recipe API.

Troubleshooting

SymptomCheck
IDE workflow surfaces are missingEnable workflows for the workspace, then start a new chat session
CLI workflow commands are missingEnable workflows under /settings → Features, then restart Kiro CLI
Recipe does not appearConfirm its source and precedence; project files must be under .kiro/workflows/ with a supported suffix
Run starts with literal {{name}}The bare input was not declared or supplied at launch
Step fails on an output or artifact templateConfirm the producer runs first and captures or declares the value
Repeat reaches its capInspect the stop file, JSON path, expected value, and producing step
Repeat pauses immediately after ResumeResume does not grant more iterations; see Resume
File condition never matchesConfirm valid JSON, the exact JSON path/value, and an allowed workspace path
Validation passes but run creation failsCheck agent names, model access, and watch-handler configuration; standalone validation cannot fully check runtime registries
command watch fails at onceThe program exited 2, 126, or 127, or exited 0 with malformed JSON or no cursor; run it by hand with a saved stdin object and check that stdout holds exactly one JSON object
command watch never wakesAny other non-zero exit, including a commandTimeoutSec kill, counts as idle and retries; check stderr for a recurring failure, and confirm the program reports new-activity instead of only advancing its cursor
Parallel work is not fasterKiro starts branches concurrently, but use parallel for isolation and join semantics rather than speed
Cancelled run left edits behindCancellation does not undo file changes; inspect or revert the workspace
Paused step ignores a replySend text in the step's own session, not only an attachment or the parent chat

Operational limits

  • Recipes support at most 8 levels of nesting and 50 static step nodes.
  • Every repeat has a positive maxIterations.
  • Repeat conditions run after an iteration, so every repeat executes at least once.
  • parallel gives each branch its own context and a join policy (all, allSettled, or any). Kiro starts the branches concurrently; use it for isolation and join semantics rather than assuming a shorter wall-clock time.
  • Workflows do not isolate Git branches or create worktrees.
  • Client closure and cross-client attachment behavior are not part of the recipe contract documented here.

Next steps

Page updated: November 13, 2026