Skip to main content
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
PathDescription
agents/agent-config.jsonSubagents registered for this workflow
inputs/specification.mdUser 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.jsonAction that determines what the workflow does next
logs/Database of agent history and running states
template.jsonSingle 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

PhaseWhat Changes in template.json
OnboardingselectedTrack, selectedConditions set
Workflow StartactiveTemplate set, completedSteps: {}, notCompletedSteps: []
Step StartsnotCompletedSteps: [0] added
Session InitcompletedSteps["0"] = { sessionId, monitoringId }
Chain CompletecompletedSteps["0"].completedChains = [0, 1, ...]
Step CompletecompletedSteps["0"].completedAt set, notCompletedSteps cleaned
Loop TriggerednotCompletedSteps updated to loop-back index
Crash OccursnotCompletedSteps 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:
  1. CodeMachine finds the .codemachine folder
  2. It reads template.json to see which step was running
  3. 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.

​
User Controls

You can control workflow execution with keyboard shortcuts:
ActionShortcutWhat Happens
Skip StepCtrl+SMark current step as done and move on
QuitCtrl+CSave progress and exit (can resume later)
AdvanceEnterComplete 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:
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
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.