Runtime State

When you run a workflow, CodeMachine creates a .codemachine folder in your project. This folder tracks everything about your workflow session—what’s running, what’s finished, and how to pick up where you left off.

The .codemachine Folder

.codemachine

agents

agent-config.json

planner.md

coder.md

reviewer.md

inputs

specification.md

artifacts

prompts

memory

directive.json

logs

template.json

What each folder and file contains

Path	Description
`agents/agent-config.json`	Subagents registered for this workflow
`inputs/specification.md`	User specifications (if workflow requires them)
`artifacts/`	Optional folder for planning files (must be defined in prompts)
`prompts/`	Optional folder for cached prompts (must be defined in prompts)
`memory/directive.json`	Action that determines what the workflow does next
`logs/`	Database of agent history and running states
`template.json`	Single source of truth for runtime data. Deleting this resets the workflow from zero

How Progress is Tracked

The template.json file is the heart of workflow tracking. It remembers:

Current Position

Which step is running and which steps are done

Session Info

IDs needed to resume interrupted steps

Your Choices

Selected track and conditions from onboarding

Recovery Data

Everything needed to continue after a crash

template.json Schema

interface TemplateTracking {
  // === Required ===
  activeTemplate: string;        // Running template filename (e.g., "bug-fixer.workflow.js")
  lastUpdated: string;           // ISO 8601 timestamp (UTC)

  // === Step Tracking ===
  completedSteps?: Record<string, StepData>;  // Map of step index → execution data
  notCompletedSteps?: number[];               // Steps started but not finished (for crash recovery)
  resumeFromLastStep?: boolean;               // Enable resume capability (default: true)

  // === Workflow Configuration ===
  selectedTrack?: string;                     // Selected track (e.g., 'quick', 'enterprise')
  selectedConditions?: string[];              // Selected condition IDs
  projectName?: string;                       // User-provided project name
  autonomousMode?: string;                    // 'true' | 'false' | 'never' | 'always'

  // === Controller Mode ===
  controllerConfig?: {
    agentId: string;
    sessionId: string;
    monitoringId: number;
  };
  controllerView?: boolean;                   // Recovery opens controller vs workflow view
}

interface StepData {
  sessionId: string;           // Engine session ID for resume
  monitoringId: number;        // Database ID in registry.db
  completedChains?: number[];  // Completed chained prompt indices
  completedAt?: string;        // ISO timestamp when step finished
}

State Transitions

Phase	What Changes in template.json
Onboarding	`selectedTrack`, `selectedConditions` set
Workflow Start	`activeTemplate` set, `completedSteps: {}`, `notCompletedSteps: []`
Step Starts	`notCompletedSteps: [0]` added
Session Init	`completedSteps["0"] = { sessionId, monitoringId }`
Chain Complete	`completedSteps["0"].completedChains = [0, 1, ...]`
Step Complete	`completedSteps["0"].completedAt` set, `notCompletedSteps` cleaned
Loop Triggered	`notCompletedSteps` updated to loop-back index
Crash Occurs	`notCompletedSteps` preserved for recovery

Manipulating Workflow Progress

You can manually control workflow execution by editing template.json. This is useful for:

Re-running a specific step
Resetting the workflow to an earlier point
Skipping steps that already completed

Revert to a Previous Step

The completedSteps object tracks finished steps by index. To go back to a step, remove it (and all steps after it) from completedSteps. Example: You have steps 0, 1, 2 completed and want to re-run step 2:

// Before - all steps complete
{
  "completedSteps": {
    "0": { "sessionId": "abc", "monitoringId": 1, "completedAt": "..." },
    "1": { "sessionId": "def", "monitoringId": 2, "completedAt": "..." },
    "2": { "sessionId": "ghi", "monitoringId": 3, "completedAt": "..." }
  }
}

// After - remove step 2 to re-run it
{
  "completedSteps": {
    "0": { "sessionId": "abc", "monitoringId": 1, "completedAt": "..." },
    "1": { "sessionId": "def", "monitoringId": 2, "completedAt": "..." }
  }
}

Reset Entire Workflow

To start from the beginning, clear completedSteps:

{
  "completedSteps": {},
  "notCompletedSteps": []
}

Or simply delete the entire template.json file to reset everything.

Workflow Lifecycle

Here’s what happens as your workflow runs:

Workflow Starts

CodeMachine creates the .codemachine folder and initializes template.json with your selected options.

Step Begins

The current step is marked as “in progress” so CodeMachine knows where you are.

Agent Runs

The agent executes with its prompts. Session info is saved for potential recovery.

Step Completes

The step is marked complete with a timestamp, and CodeMachine moves to the next step.

Workflow Ends

All steps are marked complete. The workflow is finished.

What Happens If Something Goes Wrong?

CodeMachine automatically saves your progress. If your workflow crashes or you close the terminal, you can pick up right where you left off.

When you restart after an interruption:

CodeMachine finds the .codemachine folder
It reads template.json to see which step was running
It offers to resume from that step (or the last completed one)

Agent Directives

Agents can control what happens next by writing to directive.json. This is how agents communicate with the workflow.

{ "action": "continue" }

Move to the next step normally. This is the default.

{ "action": "loop", "reason": "Tests failed, need another pass" }

Go back to an earlier step and try again.

{ "action": "checkpoint", "reason": "Review changes before continuing" }

Pause and wait for user confirmation.

{ "action": "trigger", "triggerAgentId": "code-reviewer" }

Spawn a sub-agent to help with a specific task.

{ "action": "stop", "reason": "Task completed successfully" }

End the workflow early.

{ "action": "error", "reason": "Something went wrong" }

Terminate the workflow with an error.

User Controls

You can control workflow execution with keyboard shortcuts:

Action	Shortcut	What Happens
Skip Step	`Ctrl+S`	Mark current step as done and move on
Quit	`Ctrl+C`	Save progress and exit (can resume later)
Advance	`Enter`	Complete step and continue to next

When a workflow pauses at a checkpoint, you’ll see a prompt. Choose to continue or quit—your progress is saved either way.

Execution Logs

The logs/ folder contains detailed records of every agent run:

registry.db - Execution History

A SQLite database tracking every agent execution:

Agent name and engine used
Start time, end time, and duration
Status (running, completed, failed, skipped)
Token usage and cost estimates
Error messages if something went wrong

Agent Log Files

Each agent gets its own log file (agent-*.log) containing:

The full prompt sent to the agent
The agent’s complete response
Any errors or warnings during execution

Cleaning Up

The .codemachine folder contains your workflow state. Deleting it will remove your ability to resume an interrupted workflow.

To start fresh, you can safely delete the .codemachine folder:

rm -rf .codemachine

A new folder will be created the next time you run a workflow.

Build Workflows

Configuration

Share Workflows

The .codemachine Folder

How Progress is Tracked

Current Position

Session Info

Your Choices

Recovery Data

template.json Schema

State Transitions

Manipulating Workflow Progress

Revert to a Previous Step

Reset Entire Workflow

Workflow Lifecycle

What Happens If Something Goes Wrong?

Agent Directives

User Controls

Execution Logs

Cleaning Up

​The .codemachine Folder

​How Progress is Tracked

Current Position

Session Info

Your Choices

Recovery Data

​template.json Schema

​State Transitions

​Manipulating Workflow Progress

​Revert to a Previous Step

​Reset Entire Workflow

​Workflow Lifecycle

​What Happens If Something Goes Wrong?

​Agent Directives

​User Controls

​Execution Logs

​Cleaning Up

The .codemachine Folder

How Progress is Tracked

template.json Schema

State Transitions

Manipulating Workflow Progress

Revert to a Previous Step

Reset Entire Workflow

Workflow Lifecycle

What Happens If Something Goes Wrong?

Agent Directives

User Controls

Execution Logs

Cleaning Up