Skip to main content
A workflow file defines how your agents execute: the order they run and how they interact with users.
Before creating a workflow, make sure you’ve already configured your agents and written your prompts.

​
Workflow File Location

Workflow files live in templates/workflows/ and use the .workflow.js extension:
my-workflow-codemachine
templates
workflows
my-workflow.workflow.js

​
Basic Structure

Every workflow exports a default object with a name and steps:
templates/workflows/my-workflow.workflow.js
export default {
  name: 'My Workflow',

  steps: [
    resolveStep('planner'),
    resolveStep('developer'),
    resolveStep('reviewer'),
  ],
};

​
Name

Names should be short and descriptive. They define the objective of your workflow and help users understand what it accomplishes. 
name: 'Code Review Pipeline'
Example names:
  • Code Review Pipeline
  • API Generator
  • Documentation Writer
  • Bug Fixer

​
Steps

Steps are agents set in sequence. The resolveStep() function loads an agent from your config/main.agents.js. Arrangement matters. Each step receives context from previous steps, so the order determines how information flows through your workflow. 
steps: [
  resolveStep('planner'),    // Runs first
  resolveStep('developer'),  // Receives planner's output
  resolveStep('reviewer'),   // Receives both outputs
],

​
Workflow Modes

Choose how your workflow runs:
ModeDescriptionBest For
ManualUser controls flow, agents wait for inputInteractive workflows, brainstorming
ContinuousRuns automatically from start to finishBatch processing, reports
HybridMix of interactive and auto-advancing agentsComplex workflows with checkpoints
Set the mode using autonomousMode: 
export default {
  name: 'My Workflow',
  autonomousMode: 'never',  // Manual mode - user controls each step

  steps: [
    resolveStep('planner'),
    resolveStep('developer'),
  ],
};
ValueBehavior
'never' or falseManual - waits for user at each step
'always' or trueContinuous - auto-advances through all steps

​
Adding Separators

Use separator() to add visual dividers between workflow phases:
templates/workflows/code-review.workflow.js
export default {
  name: 'Code Review Workflow',

  steps: [
    separator('Analysis Phase'),
    resolveStep('analyzer'),

    separator('Review Phase'),
    resolveStep('structure-reviewer'),
    resolveStep('quality-reviewer'),

    separator('Final Report'),
    resolveStep('report-generator'),
  ],
};
Separators appear in the TUI timeline to help users understand workflow progress.

​
Interactive vs Non-Interactive Steps

By default, steps are interactive - the workflow waits for user input. Set interactive: false to auto-advance: 
export default {
  name: 'Hybrid Pipeline',

  steps: [
    // First step is interactive - gather requirements from user
    resolveStep('requirements-gatherer'),

    // Remaining steps run automatically
    resolveStep('planner', { interactive: false }),
    resolveStep('developer', { interactive: false }),
    resolveStep('tester', { interactive: false }),
  ],
};
A common pattern is making the first step interactive for gathering requirements, then running subsequent steps non-interactively.

​
Complete Simple Example

Here’s a complete workflow for a basic code generation pipeline:
templates/workflows/code-generator.workflow.js
export default {
  name: 'Code Generator',
  autonomousMode: 'never',

  steps: [
    separator('Requirements'),
    resolveStep('requirements-analyst'),

    separator('Planning'),
    resolveStep('architect', { interactive: false }),

    separator('Implementation'),
    resolveStep('developer', { interactive: false }),

    separator('Quality Check'),
    resolveStep('reviewer', { interactive: false }),
  ],
};

​
Running Your Workflow

Once your workflow is complete, run it with: 
codemachine workflow my-workflow
Or select it from the TUI workflow picker.

​
Keyboard Shortcuts

KeyAction
Shift+TabToggle Autonomous Mode
TabToggle Timeline Panel
PPause Workflow
Ctrl+SSkip current prompt or agent
EscapeStop Confirmation
HHistory View
EnterToggle Expand / Open Log
Arrow Up/DownNavigate
Arrow RightFocus Prompt Box

​
Validation Checklist

Before running your workflow, verify:
1

Agent IDs Match

Every agent ID in resolveStep() exists in config/main.agents.js
2

Prompt Files Exist

All promptPath references in agent configs point to existing files
3

Placeholders Registered

All placeholders used in prompts are registered in config/placeholders.js

​
Next Steps

Ready for more? Learn about tracks, conditions, modules, controllers, and sub-agents.

Advanced Workflows

Tracks, conditions, modules, and controllers

Workflow Examples

Complete real-world examples