Skip to content
/

CodeMachine CLI

codemachine-cli · moazbuilds/CodeMachine-CLI · ★ 2.5k · last commit 2026-02-25

JavaScript-DSL workflow orchestration engine that captures repeatable AI coding agent workflows with tracks, condition groups, and long-running persistence across Claude Code, Codex, Cursor, and Gemini.

Best whenEvery developer already has a workflow — the tool should capture it as reusable code, not impose a generic methodology.
Skip ifRebuilding the same workflow from scratch every session, One-size-fits-all methodology prescription
vs seeds
No seed matches this architecture. The closest is microsoft/conductor (YAML workflow engine), but CodeMachine uses JavaScript modu…
Primitive shape 9 total
Commands 8 MCP tools 1
00

Summary

CodeMachine CLI — Summary

CodeMachine CLI (npm i -g codemachine) is a TypeScript/Node.js workflow orchestration engine that wraps AI coding CLI tools (Claude Code, Codex, Cursor, Gemini) into user-defined repeatable workflows expressed as JavaScript module files (*.workflow.js). Unlike the CDD conductor variants (methodology frameworks) and microsoft/conductor (YAML-driven workflow engine), CodeMachine uses a hybrid model: workflows are defined in JavaScript (not YAML) with a declarative config object plus programmatic step composition, and executed by spawning the AI coding engine as a subprocess through its headless/scripting mode. Key features include conditional branching via conditionGroups and tracks, parallel execution, long-running workflow persistence, a TUI for progress monitoring, multi-agent coordination with distinct "modules" and "controller" roles, and a built-in workflow builder ("Ali") that uses Claude to help users create their own workflows interactively. At 2,488 stars with 7 contributors and Apache-2.0 license, CodeMachine is by far the most starred tool in this batch. It ships 8 CLI subcommands (run, step, mcp, auth, export, import, templates, and a TUI) and represents a distinct "workflow programming language" paradigm not seen in any seed.

01

Overview

CodeMachine CLI — Overview

Origin

  • Package: codemachine (npm), binary: codemachine / cm
  • Repo: https://github.com/moazbuilds/CodeMachine-CLI
  • Version: 0.8.0
  • License: Apache-2.0
  • Stars: 2,488 | Forks: 239 | Contributors: 7 | Last commit: 2026-02-25
  • Company: CodeMachine contributors (moazbuilds)

Philosophy

From the README:

"Every time you use an AI coding agent, you're running a workflow. Fix a bug? You ask questions, reproduce, analyze, plan, implement, test. Build a feature? You research, design, code, review."

"The workflow lives in your head. You guide the agent through it, step by step, session by session. But every time you start, you rebuild it from scratch."

"CodeMachine lets you capture that workflow and run it again."

This framing is fundamentally different from CDD conductor variants: CodeMachine doesn't prescribe a methodology — it helps you capture your own methodology as a reusable workflow.

Key innovations over YAML-based workflow engines

  1. JavaScript workflow files — workflows are .workflow.js modules; programmatic composition with resolveStep(), not just YAML configuration
  2. Tracks system — workflows can branch based on user choices at startup (tracks: { options: {...} })
  3. Condition groups — interactive multi-select questions that filter which steps run per track
  4. Autonomous mode — configurable per workflow: 'never' (always interactive), 'always' (always autonomous), or specific steps can be gated
  5. Ali workflow builder — a default meta-workflow that uses Claude to help you design and generate new workflows interactively (expert or quick mode)
  6. Long-running workflows — built-in persistence handles multi-hour or multi-day workflow runs without user babysitting

Community

Active Discord (discord.gg/vS3A5UDNSq) and Reddit (r/CodeMachine/) community.

02

Architecture

CodeMachine CLI — Architecture

Distribution

  • Type: npm package (CLI tool)
  • Install: npm i -g codemachine (or bun add -g codemachine)
  • Binary names: codemachine and cm (alias)
  • Required runtime: Node.js >= 20.10.0

Source structure

moazbuilds/CodeMachine-CLI/
├── src/
│   ├── agents/                 # Agent subsystem
│   │   ├── chat/               # Agent chat interface
│   │   ├── coordinator/        # Agent coordination
│   │   ├── execution/          # Task execution
│   │   ├── monitoring/         # Agent health monitoring
│   │   ├── runner/             # Agent runtime
│   │   └── session/            # Session management
│   ├── cli/
│   │   ├── commands/           # CLI subcommands
│   │   │   ├── run.command.ts
│   │   │   ├── step.command.ts
│   │   │   ├── mcp.command.ts
│   │   │   ├── auth.command.ts
│   │   │   ├── export.command.ts
│   │   │   ├── import.command.ts
│   │   │   ├── templates.command.ts
│   │   │   └── agents.command.ts
│   │   ├── tui/                # Terminal UI
│   │   └── utils/
│   ├── infra/                  # Infrastructure (persistence, etc.)
│   ├── runtime/                # Workflow execution engine
│   │   ├── context/            # Context management
│   │   ├── controller/         # Workflow controller
│   │   ├── directives/         # Step directives
│   │   ├── indexing/           # Code indexing
│   │   ├── input/              # User input handling
│   │   ├── mode/               # Execution modes
│   │   ├── onboarding/         # New user onboarding
│   │   ├── recovery/           # Crash recovery
│   │   ├── signals/            # Signal handling
│   │   ├── state/              # State management
│   │   ├── step/               # Step execution
│   │   └── templates/          # Template engine
│   ├── shared/                 # Shared utilities
│   └── workflows/              # Workflow definitions (built-in)
├── prompts/
│   └── templates/
│       └── ali/                # Ali workflow builder prompts
├── templates/
│   └── workflows/
│       ├── _example.workflow.js
│       └── ali.workflow.js     # Default meta-workflow
├── config/                     # Default configuration
└── bin/
    └── codemachine.js          # CLI entry point

Target AI tools

  • Claude Code (primary, explicitly listed)
  • Codex (supported)
  • Cursor (supported)
  • Gemini CLI (supported)
  • Any AI coding CLI that provides headless/scripting mode
03

Components

CodeMachine CLI — Components

CLI subcommands (8)

Command Purpose
cm run [workflow] Run a workflow (interactive or autonomous)
cm step [step-id] Run a single step from a workflow
cm mcp MCP server management
cm auth Authenticate with AI coding engines
cm export Export workflow state
cm import Import workflow state
cm templates Manage workflow templates
cm agents Manage agents

Workflow definition format (JavaScript modules)

export default {
  name: 'Workflow Name',
  autonomousMode: 'never' | 'always' | 'per-step',
  projectName: true | false,

  tracks: {
    question: 'Choose mode:',
    options: { 'mode-1': {...}, 'mode-2': {...} }
  },

  conditionGroups: [
    {
      id: 'group-id',
      question: 'Question text',
      multiSelect: true | false,
      tracks: ['mode-1'],
      conditions: { 'cond-a': {...}, 'cond-b': {...} },
      children: { 'cond-a': { ... nested conditionGroup ... } }
    }
  ],

  steps: [
    resolveStep('step-id', {
      engine: 'claude' | 'codex' | 'gemini',
      tracks: ['mode-1'],
      conditions: ['cond-a'],
    })
  ]
}

Built-in workflow: Ali (workflow builder)

templates/workflows/ali.workflow.js — the default meta-workflow that helps users create their own workflows:

  • Two tracks: Expert Mode and Quick Mode
  • Expert: 5-step guided process (brainstorming → definition → agents → prompts → generation)
  • Quick: single-step rapid build
  • Condition groups for selecting which phases to focus on
  • Steps resolve to cm-workflow-builder and cm-workflow-builder-quick prompts

TUI (Terminal UI)

src/cli/tui/ — real-time progress monitoring in the terminal.

Prompt templates

prompts/templates/ali/ — prompt files for the Ali workflow builder steps.

MCP integration

src/runtime/mcp.ts — MCP server support for tool integration. cm mcp manages MCP servers.

05

Prompts

CodeMachine CLI — Prompts

Excerpt 1: templates/workflows/ali.workflow.js — JavaScript workflow definition

export default {
  name: 'CodeMachine Workflow Builder',
  autonomousMode: 'never',
  projectName: true,

  tracks: {
    question: 'Choose your workflow building mode:',
    options: {
      'expert': {
        label: 'Expert Mode',
        description: 'For complex or custom workflows'
      },
      'quick': {
        label: 'Quick Mode',
        description: 'Speed over customization'
      },
    },
  },

  conditionGroups: [
    {
      id: 'workflow_action',
      question: 'What do you want to do?',
      multiSelect: false,
      tracks: ['quick', 'expert'],
      conditions: {
        'create-workflow': { label: 'Create Workflow', description: 'Build a new workflow from scratch' },
        'modify-workflow': { label: 'Modify Workflow', description: 'Edit or update an existing workflow' },
      },
    },
    {
      id: 'workflow_scope',
      question: 'How do you want to build your workflow?',
      tracks: ['expert'],
      conditions: {
        'select-parts': {
          label: 'Select Parts',
          description: 'Choose specific phases to focus on'
        },
      },
      children: {
        'select-parts': {
          question: 'What areas do you want to focus on?',
          multiSelect: true,
          conditions: {
            brainstorming: { label: 'Brainstorming' },
            'workflow-definition': { label: 'Workflow Definition' },
            agents: { label: 'Agents' },
            prompts: { label: 'Prompts' },
            'workflow-generation': { label: 'Workflow Generation' },
          },
        },
      },
    },
  ],

  steps: [
    resolveStep('cm-workflow-builder-quick', {
      engine: 'claude',
      tracks: ['quick'],
    }),
    resolveStep('cm-workflow-builder', {
      engine: 'claude',
      tracks: ['expert'],
    }),
  ],
};

Technique: JavaScript module as workflow definition — not YAML or markdown. Declarative conditionGroups with nested children for hierarchical question trees. Track-filtering: steps only run when the active track matches. resolveStep() function call connects workflow definition to prompt file.


Excerpt 2: prompts/templates/ali/ — prompt files for Ali workflow steps

The Ali workflow builder prompt files (in prompts/templates/ali/) guide Claude to help users design workflows. These are the actual prompts sent to the AI coding engine during the cm-workflow-builder step. Content not directly fetchable in this analysis, but the structure is:

  • cm-workflow-builder.md — expert mode multi-step builder prompt
  • cm-workflow-builder-quick.md — quick mode single-step builder prompt

Technique: Prompt files are separate from workflow definition files — clean separation of orchestration logic (.workflow.js) from AI instruction content (.md prompt files).


Prompting techniques observed

  1. JavaScript-as-config — workflow logic in JS module rather than YAML/JSON; resolveStep() links config to prompts
  2. Track-conditioned steps — steps have tracks: ['quick'] arrays; only activated for matching tracks
  3. Multi-select condition groups — users select multiple options; step activation is the intersection
  4. Nested condition children — condition groups can have sub-questions revealed based on parent selection
  5. Autonomous mode flag — per-workflow and per-step control over human-in-the-loop gates
  6. Engine selection per stepengine: 'claude' or 'codex' at the step level
09

Uniqueness

CodeMachine CLI — Uniqueness

differs_from_seeds

No seed matches CodeMachine's architecture. The closest is microsoft/conductor (YAML workflow engine for multi-agent orchestration), but CodeMachine uses JavaScript modules instead of YAML, spawns AI coding CLIs as subprocesses instead of using provider SDKs directly, and adds the tracks/conditionGroups interactive selection system for workflow branching. The Ali workflow builder meta-workflow (a workflow that builds workflows) has no equivalent in the seed corpus. Among seeds, taskmaster-ai's MCP toolserver is the closest in "workflow programming" spirit, but taskmaster uses JSON tasks while CodeMachine uses JS modules as the workflow DSL. CodeMachine is the only framework in this batch that is tool-agnostic (runs Claude Code, Codex, Cursor, Gemini), has 2,488 stars (most in the batch), and defines workflows as JavaScript code rather than config files.

What makes CodeMachine unique

  1. JavaScript workflow DSL.workflow.js modules with tracks, conditionGroups, nested children — more expressive than YAML
  2. Tracks system — workflows branch at startup based on user-chosen tracks (quick vs. expert modes)
  3. Condition groups with children — hierarchical interactive question trees with multi-select that filter step execution
  4. Ali workflow builder — meta-workflow using Claude to help you create your own workflows interactively
  5. Engine selection per stepengine: 'claude' | 'codex' | 'gemini' at the step level; different steps can use different AI tools
  6. Long-running persistencecm export/import for state portability across sessions
  7. 2,488 stars — the highest adoption of any framework in this batch by a wide margin
  8. Subprocess spawning model — wraps existing AI coding CLIs via their headless mode; does not use any AI provider SDK directly

Observable failure modes

  1. JavaScript complexity: .workflow.js with conditionGroups/children is harder to read than YAML; non-JS developers face friction
  2. AI CLI headless mode dependency: relies on Claude Code/Codex CLI headless mode flags; any CLI API change breaks workflows
  3. No isolation: all steps run in same working directory; parallel agents can conflict
  4. No explicit safety limits: no max_iterations equivalent; infinite loop risk in fully autonomous mode
  5. Closed docs: detailed docs require visiting docs.codemachine.co (not in repo)

Positioning

CodeMachine occupies the "workflow programming language" niche: it does not prescribe a development methodology (unlike CDD variants) and does not use a provider SDK (unlike microsoft/conductor). It is the metaprogramming tool for AI agent workflows — the tool that lets you build custom tools.

04

Workflow

CodeMachine CLI — Workflow

Creating a workflow

Option A: Use Ali workflow builder (interactive)

cm run ali   # guided workflow creation

Ali asks: expert or quick mode, what to build, which phases to focus on, and generates the .workflow.js file.

Option B: Copy and modify _example.workflow.js

cp ~/.codemachine/templates/_example.workflow.js my-workflow.js

Option C: Manual authoring — write .workflow.js following the schema.

Running a workflow

cm run my-workflow         # with TUI
cm run my-workflow --auto  # autonomous (no interactive prompts)
cm step my-workflow step-id # run single step only

Workflow execution model

  1. Startup: user selects track (if tracks: defined); answers condition group questions
  2. Step filtering: based on track + conditions, active steps determined
  3. Step execution: each step spawns the configured AI coding engine via subprocess headless mode
  4. Context passing: step outputs flow to next step's context
  5. Persistence: long-running workflows save state; can resume after interruption

Autonomous mode

Per workflow configuration:

  • autonomousMode: 'never' — pauses at every confirmation point (full human-in-the-loop)
  • autonomousMode: 'always' — runs fully autonomously
  • Per-step overrides possible

Approval gates

In never autonomous mode, the user can inspect and approve at each step. In always mode, no gates.

Long-running workflows

Built-in persistence handles multi-hour or multi-day workflows:

  • State saved between steps
  • Resume after interruption without restarting from scratch
  • cm export / cm import for state portability

Multi-agent coordination

Workflows can define agent modules and a controller:

  • Modules handle specific tasks
  • Controller coordinates between modules
  • Different steps can use different engines (e.g., Claude for analysis, Codex for implementation)
06

Memory Context

CodeMachine CLI — Memory & Context

Workflow state persistence

Long-running workflows save state automatically:

  • cm export — export current workflow state
  • cm import — import and resume workflow state
  • State stored in .codemachine/ directory (inferred from codebase patterns)

Context cache

src/runtime/context/ handles context management:

  • Manages what context is passed to each step
  • Context from completed steps flows to downstream steps

Code indexing

src/runtime/indexing/ — code index maintained during workflow execution:

  • Enables semantic code references in prompts
  • Reduces context size by indexing rather than embedding full files

Session management

src/agents/session/ — agent session lifecycle:

  • Session creation, resumption, termination
  • Cross-step state within a workflow run

Crash recovery

src/runtime/recovery/ — explicit crash recovery module:

  • Workflow can resume from last successful step after failure
  • Not documented in detail publicly

Memory persistence scope

  • Project-scoped during workflow run
  • Session-scoped for individual step execution
  • Persistent across runs via export/import

No cross-project memory

Unlike claudiomiro's insights/reflection system (which accumulates learnings across runs), CodeMachine's memory is workflow-run-scoped. No global insight store.

07

Orchestration

CodeMachine CLI — Orchestration

Multi-agent

Yes — workflows support multiple agents with modules and a controller pattern.

Orchestration pattern

Task-decomposition-tree — the workflow's conditionGroups and tracks system builds a decision tree at startup, then executes the appropriate steps. Steps can run the same or different AI coding engines. The controller module coordinates between agent modules.

Isolation mechanism

No explicit isolation (no worktrees, no containers). Each step spawns the AI coding engine in the same working directory.

Multi-model

Yes (implicit) — steps can specify engine: 'claude' or engine: 'codex', so different steps in the same workflow can use different AI providers.

Execution mode

Interactive loop (default autonomousMode: 'never') or one-shot (autonomousMode: 'always'). Long-running workflows with persistence make this closer to continuous for extended tasks.

Prompt chaining

Yes — step outputs flow to subsequent steps' context. The resolveStep() function connects sequential prompt execution.

Parallel execution

Supported (per README: "Run multiple agents simultaneously"). The agent coordination module (src/agents/coordinator/) manages parallel step execution.

Context accumulation

context: mode: accumulate (implicit) — context from completed steps flows forward.

Max iterations

Not documented; no explicit safety limit like microsoft/conductor's max_iterations.

08

Ui Cli Surface

CodeMachine CLI — UI & CLI Surface

Dedicated CLI binary

Yes — codemachine and cm (alias).

Subcommand Purpose
cm run [workflow] Execute workflow with TUI
cm step [step-id] Execute single step
cm mcp MCP server management
cm auth Authentication management
cm export Export workflow state
cm import Import workflow state
cm templates Template management
cm agents Agent management

Terminal UI (TUI)

src/cli/tui/ — real-time workflow progress monitoring in the terminal. Not a full dashboard (no web), but a structured terminal view.

TUI features
Active step tracking
Agent status display
Progress visualization
Log streaming

Local web dashboard

None — TUI only.

IDE integration

None — standalone CLI tool; does not integrate as a plugin for any IDE.

Observability

  • TUI: real-time terminal feedback during workflow execution
  • cm export/import: workflow state portability
  • Workflow logs: captured during step execution
  • MCP server visibility: cm mcp shows configured MCP servers

Cross-platform

Node.js >= 20.10.0 — works on macOS, Linux, Windows.

Community tools

Active Discord and Reddit community; Telemetry migration plan visible in TELEMETRY_MIGRATION_PHASE_PLAN.md.

Related frameworks

same archetype · same primary tool · same memory type

Codexia ★ 690

Tauri desktop app providing visual control plane, task scheduler, git worktree manager, and headless REST API for Codex CLI +…

Kagan ★ 88

Kanban TUI for AI coding agents with a structurally enforced human review gate (REVIEW → DONE cannot be automated) — one git…

oh-my-claudecode (Yeachan-Heo) ★ 35k

Zero-learning-curve teams-first multi-agent orchestration for Claude Code with autopilot (6-phase lifecycle), ralph (PRD-driven…

Paseo ★ 6.8k

Multi-provider AI coding agent orchestration daemon with cross-device access (phone/desktop/CLI) and git worktree isolation.

CCG Workflow ★ 5.4k

Routes Claude + Codex + Gemini to task-appropriate collaboration strategies (direct-fix through full-collaborate) with hook-based…

CCS (Claude Code Switch) ★ 2.4k

Routes Claude Code tasks to the optimal AI agent (Codex, Factory Droid, Ollama, Claude) based on configurable cost/capability…