Your First Workflow

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:

Mode	Description	Best For
Manual	User controls flow, agents wait for input	Interactive workflows, brainstorming
Continuous	Runs automatically from start to finish	Batch processing, reports
Hybrid	Mix of interactive and auto-advancing agents	Complex 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'),
  ],
};

Value	Behavior
`'never'` or `false`	Manual - waits for user at each step
`'always'` or `true`	Continuous - 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

Key	Action
Shift+Tab	Toggle Autonomous Mode
Tab	Toggle Timeline Panel
P	Pause Workflow
Ctrl+S	Skip current prompt or agent
Escape	Stop Confirmation
H	History View
Enter	Toggle Expand / Open Log
Arrow Up/Down	Navigate
Arrow Right	Focus Prompt Box

Validation Checklist

Before running your workflow, verify:

Agent IDs Match

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

Prompt Files Exist

All promptPath references in agent configs point to existing files

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

Build Workflows

Configuration

Share Workflows

Workflow File Location

Basic Structure

Name

Steps

Workflow Modes

Adding Separators

Interactive vs Non-Interactive Steps

Complete Simple Example

Running Your Workflow

Keyboard Shortcuts

Validation Checklist

Next Steps

Advanced Workflows

Workflow Examples

​Workflow File Location

​Basic Structure

​Name

​Steps

​Workflow Modes

​Adding Separators

​Interactive vs Non-Interactive Steps

​Complete Simple Example

​Running Your Workflow

​Keyboard Shortcuts

​Validation Checklist

​Next Steps

Advanced Workflows

Workflow Examples

Workflow File Location

Basic Structure

Name

Steps

Workflow Modes

Adding Separators

Interactive vs Non-Interactive Steps

Complete Simple Example

Running Your Workflow

Keyboard Shortcuts

Validation Checklist

Next Steps