> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemachine.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Controls

> Understand how workflow execution is controlled - signals, modes, state, and recovery.

**How execution is controlled at runtime.**

## Signals

Signals are user-initiated events that interrupt or redirect workflow execution. They let you intervene while agents are running.

<AccordionGroup>
  <Accordion title="Pause" icon="pause">
    Stops execution and switches to manual mode. Use when you need to review or intervene.
  </Accordion>

  <Accordion title="Skip" icon="forward">
    Moves to the next step without completing the current one.
  </Accordion>

  <Accordion title="Mode Toggle" icon="toggle-on">
    Switches between manual and auto mode.
  </Accordion>

  <Accordion title="Return to Controller" icon="arrow-up">
    Goes back to controller view (if controller exists).
  </Accordion>
</AccordionGroup>

<Tip>
  Want to know the keyboard shortcuts for signals? [Check the shortcuts reference →](/reference/interactive-mode#keyboard-shortcuts)
</Tip>

<Note>
  Signals come from the user. Directives come from agents. Both control execution, but from different sources. [Learn more →](#signals-vs-directives)
</Note>

***

## Modes

Two modes determine who drives the workflow:

<Tabs>
  <Tab title="Manual Mode" icon="hand">
    **You control advancement.** Agents wait for you to proceed between steps and prompts.

    Best for:

    * Learning how workflows behave
    * Debugging issues
    * High-stakes operations requiring review
  </Tab>

  <Tab title="Auto Mode" icon="robot">
    **The system controls advancement.** Either a controller agent makes decisions, or agents auto-advance without waiting.

    Best for:

    * Repetitive tasks
    * Trusted workflows
    * Background processing
  </Tab>
</Tabs>

You can switch modes at any time during execution.

### Who Drives the Workflow?

The actual behavior depends on three factors:

* **Mode** - Manual or [Auto](/build-workflows/advanced-workflows#autonomous-mode)
* **Paused** - Whether you've paused execution
* **[Agent Interactivity](/build-workflows/your-first-workflow#interactive-vs-non-interactive-steps)** - Whether the agent is configured to wait for input

| Auto Mode | Paused | Agent Interactive | Who Drives                  |
| --------- | ------ | ----------------- | --------------------------- |
| OFF       | —      | Yes               | User                        |
| OFF       | —      | No                | User (forced, with warning) |
| ON        | YES    | Any               | User (pause overrides)      |
| ON        | NO     | Yes               | Controller                  |
| ON        | NO     | No                | System (auto advance)       |

<Info>
  **The rule:** Pausing always gives you control. Auto mode only takes over when not paused.
</Info>

### Four Behaviors

<CardGroup cols={2}>
  <Card title="User drives" icon="user">
    You send input. Agent waits for you.
  </Card>

  <Card title="Controller drives" icon="gamepad">
    Controller agent sends input. Agent waits for controller.
  </Card>

  <Card title="Auto advance" icon="bolt">
    System auto-advances. No waiting.
  </Card>

  <Card title="Forced" icon="triangle-exclamation">
    Agent designed to auto-advance but mode is manual. Falls back to user control with a warning.
  </Card>
</CardGroup>

***

## State

Workflows move through defined states during execution. State determines what actions are available and what the workflow is waiting for.

| State                                   | Meaning                                                        |
| --------------------------------------- | -------------------------------------------------------------- |
| <Badge>idle</Badge>                     | Workflow has not started                                       |
| <Badge color="blue">running</Badge>     | An agent is actively executing                                 |
| <Badge color="yellow">awaiting</Badge>  | Workflow is waiting for user input                             |
| <Badge color="purple">delegated</Badge> | Workflow is waiting for controller to decide                   |
| <Badge color="green">completed</Badge>  | All steps finished successfully                                |
| <Badge color="gray">stopped</Badge>     | User exited the workflow view                                  |
| <Badge color="red">error</Badge>        | Agent directive stopped the workflow or a fatal error occurred |

<Tip>
  Want to see how states look in the TUI? Check the [Agent Status Icons](/reference/interactive-mode#agent-status-icons).
</Tip>

### How State Changes

**Starting:** `idle` → `running`

**During execution:**

* Agent needs input: `running` → `awaiting` → `running`
* Controller involved: `running` → `delegated` → `running`

**Ending:**

* All steps complete: `running` → `completed`
* Agent directive to stop: `running` → `error`
* User exits workflow view: `running` → `stopped`

***

## Recovery

Workflows are designed to survive interruptions. If the process crashes, loses connection, or terminates unexpectedly, CodeMachine can resume from where it left off.

### How Recovery Works

<Steps>
  <Step title="Detection">
    On startup, CodeMachine checks if a step was running but never completed.
  </Step>

  <Step title="Restoration">
    Previous state is loaded from the persisted session.
  </Step>

  <Step title="Resumption">
    Workflow continues based on mode:

    * **Auto mode:** Sends continuation prompt to agent
    * **Manual mode:** Pauses and waits for your input
  </Step>
</Steps>

### What Gets Persisted

Workflow state is continuously saved to `.codemachine/template.json`:

* Current step index
* Prompt queue progress (for chained prompts)
* Step completion status
* Agent session IDs
* Monitoring IDs for logs

### Recovery Scenarios

<AccordionGroup>
  <Accordion title="Process crash mid-step" icon="bolt-lightning">
    Resumes from last checkpoint.
  </Accordion>

  <Accordion title="Machine restart" icon="power-off">
    Resumes on next workflow start.
  </Accordion>

  <Accordion title="User closes terminal" icon="rectangle-xmark">
    State preserved, resume anytime.
  </Accordion>

  <Accordion title="Network timeout" icon="wifi">
    Reconnects if session is still valid.
  </Accordion>
</AccordionGroup>

<Note>
  Recovery depends on proper session configuration. Each agent needs a unique session ID for reliable resumption. Want to know how to control workflow progress? See [Manipulating Workflow Progress](/build-workflows/runtime-state#manipulating-workflow-progress).
</Note>

***

## Signals vs Directives

Both influence workflow execution, but they serve different purposes:

<Columns cols={2}>
  <Card title="Signals" icon="hand">
    **Source:** User

    **When:** Anytime during execution

    **Purpose:** User intervention

    **Examples:** Pause, Skip, Stop
  </Card>

  <Card title="Directives" icon="robot">
    **Source:** Agent

    **When:** After a step completes

    **Purpose:** Agent-controlled flow

    **Examples:** Loop, Checkpoint, Trigger
  </Card>
</Columns>

Signals let you take control. [Directives](/core-concepts/agent-basics#directives) let agents request what should happen next.

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Agent Basics" icon="users" href="/core-concepts/agent-basics">
    Understand multi-agent orchestration
  </Card>

  <Card title="Package Structure" icon="folder-tree" href="/build-workflows/package-structure">
    Create a custom workflow from scratch
  </Card>

  <Card title="Keyboard Shortcuts" icon="keyboard" href="/reference/interactive-mode#keyboard-shortcuts">
    All available shortcuts reference
  </Card>
</CardGroup>