Signals
Signals are user-initiated events that interrupt or redirect workflow execution. They let you intervene while agents are running.Pause
Pause
Stops execution and switches to manual mode. Use when you need to review or intervene.
Skip
Skip
Moves to the next step without completing the current one.
Mode Toggle
Mode Toggle
Switches between manual and auto mode.
Return to Controller
Return to Controller
Goes back to controller view (if controller exists).
Signals come from the user. Directives come from agents. Both control execution, but from different sources. Learn more →
Modes
Two modes determine who drives the workflow:- Manual Mode
- Auto Mode
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
Who Drives the Workflow?
The actual behavior depends on three factors:- Mode - Manual or Auto
- Paused - Whether you’ve paused execution
- Agent Interactivity - 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) |
The rule: Pausing always gives you control. Auto mode only takes over when not paused.
Four Behaviors
User drives
You send input. Agent waits for you.
Controller drives
Controller agent sends input. Agent waits for controller.
Auto advance
System auto-advances. No waiting.
Forced
Agent designed to auto-advance but mode is manual. Falls back to user control with a warning.
State
Workflows move through defined states during execution. State determines what actions are available and what the workflow is waiting for.| State | Meaning |
|---|---|
| idle | Workflow has not started |
| running | An agent is actively executing |
| awaiting | Workflow is waiting for user input |
| delegated | Workflow is waiting for controller to decide |
| completed | All steps finished successfully |
| stopped | User exited the workflow view |
| error | Agent directive stopped the workflow or a fatal error occurred |
How State Changes
Starting:idle → running
During execution:
- Agent needs input:
running→awaiting→running - Controller involved:
running→delegated→running
- 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
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
Process crash mid-step
Process crash mid-step
Resumes from last checkpoint.
Machine restart
Machine restart
Resumes on next workflow start.
User closes terminal
User closes terminal
State preserved, resume anytime.
Network timeout
Network timeout
Reconnects if session is still valid.
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.
Signals vs Directives
Both influence workflow execution, but they serve different purposes:Signals
Source: UserWhen: Anytime during executionPurpose: User interventionExamples: Pause, Skip, Stop
Directives
Source: AgentWhen: After a step completesPurpose: Agent-controlled flowExamples: Loop, Checkpoint, Trigger