<h3 align="center">
  <code>npm i -g codemachine</code>
</h3>

<p align="center">
  <strong>CodeMachine CLI</strong> is an autonomous multi-agent platform that works locally on your computer, turning specifications into production-ready code.<br></p>

> ### **✨ CodeMachine Built Itself**
>
> **90% of this entire codebase was generated by CodeMachine from a single specification file.**
> This isn't a demo—it's proof. CodeMachine orchestrated its own architecture, planning, implementation, and testing—creating a massively scalable codebase ready for continuous updates and improvements.

<p align="center">
  <img src="assets/images/codemachine-demo.gif" alt="CodeMachine in Action" width="800">
</p>

---

## **What is CodeMachine?**

CodeMachine is a CLI-native orchestration platform that transforms specification files and contextual inputs into production-ready code through coordinated multi-agent workflows. Specialized AI agents operate in hierarchical and parallel configurations with the ability for bidirectional communication, enabling runtime-adaptable methodologies that dynamically adjust to project requirements without framework modifications.


**Why CodeMachine?**

*   **Customizable, End-to-End Workflows:** Architect sophisticated orchestration pipelines for any scale, from executing simple scripts to managing multi-day, complex development cycles.
*   **Strategic Multi-Agent Collaboration:** Leverage a heterogeneous multi-agent system by assigning specialized models to specific tasks—for instance, using Gemini for planning, Claude for implementation, and another model for code review.
*   **Massively Parallel Execution:** Achieve significantly accelerated output by deploying sub-agents that operate simultaneously on different components of a task.
*   **Persistent, Long-Running Orchestration:** Execute workflows for extended durations—hours or even days—to autonomously accomplish complex, long-term development goals.
---

## 🚀 Quick Start

### **Installing and running CodeMachine CLI**

First, install the command-line tool globally via npm:
```bash
npm install -g codemachine
```

Then, simply run `codemachine` in your project directory to get started.
```bash
codemachine
```
### **Initializing a Project**

 CodeMachine initializes a `.codemachine/` workspace. To start **add your specs** to the `inputs/specifications.md` file, then **run `/start`** and watch the magic happen, CodeMachine will:
 *   **Architect a complete system blueprint from your requirements.**
 *   **Formulate detailed, step-by-step execution plans.**
 *   **Engineer clean, production-grade code for every component.**
 *   **Generate essential automation for testing and deployment.**
 *   **Integrate rigorous validation checks across every phase of execution.**

### Supported AI Engines

CodeMachine requires at least one CLI-based AI engine to handle the primary roles of planning and writing code, and is designed to orchestrate multiple engines to collaborate within a single workflow. The table below shows the current status of supported and upcoming integrations.


<table align="center" style="width: 80%; margin: 0 auto;">
  <tr>
    <th align="center" style="padding: 12px; font-size: 16px;">CLI Engine</th>
    <th align="center" style="padding: 12px; font-size: 16px;">Status</th>
    <th align="center" style="padding: 12px; font-size: 16px;">Main Agents</th>
    <th align="center" style="padding: 12px; font-size: 16px;">Sub Agents</th>
    <th align="center" style="padding: 12px; font-size: 16px;">Orchestrate</th>
  </tr>
  <tr>
    <td align="center" style="padding: 10px; font-size: 15px;"><strong>Codex CLI</strong></td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅ Supported</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
  </tr>
  <tr>
    <td align="center" style="padding: 10px; font-size: 15px;"><strong>Claude Code</strong></td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅ Supported</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
  </tr>
  <tr>
    <td align="center" style="padding: 10px; font-size: 15px;"><strong>Cursor CLI</strong></td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅ Supported</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
    <td align="center" style="padding: 10px; font-size: 15px;">✅</td>
  </tr>
  <tr>
    <td align="center" style="padding: 10px; font-size: 15px;"><strong>Gemini CLI</strong></td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧 Coming Soon</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
  </tr>
<tr>
    <td align="center" style="padding: 10px; font-size: 15px;"><strong>Qwen Coder</strong></td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧 Coming Soon</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
    <td align="center" style="padding: 10px; font-size: 15px;">🚧</td>
  </tr>
</table>

---

## **Production Validation:**

CodeMachine has been battle-tested on the Sustaina Platform a full-stack ESG compliance system spanning **7 microservices**, **500+ files**, and **50,000+ lines of code** across Python, TypeScript, React, FastAPI, and NestJS.

<table>
  <tr>
    <td><strong>Services Generated</strong></td>
    <td>7 microservices (AI/ML + CRUD APIs)</td>
  </tr>
  <tr>
    <td><strong>Codebase Scale</strong></td>
    <td>~500 files, 50K+ Line of code</td>
  </tr>
  <tr>
    <td><strong>Tech Stack</strong></td>
    <td>React 18, FastAPI, NestJS, PostgreSQL, MongoDB, Redis, Kubernetes</td>
  </tr>
  <tr>
    <td><strong>Time to MVP</strong></td>
    <td>~6 raw hours of autonomous orchestration</td>
  </tr>
</table>

### [View detailed breakdown →](./docs/case-study-sustaina.md)

---


## 🛠️ How It Works

CodeMachine orchestrates workflows through sequential main agent steps and parallel sub-agent execution. After selecting a workflow template, the main agent processes each step in order. When sub-agents are triggered, they work simultaneously on specialized tasks (e.g., frontend, backend, database), then results flow back into the main workflow. Conditional loops allow workflows to iterate until completion criteria are met.

<p align="center">
  <img src="assets/images/diagram1.jpg" alt="CodeMachine Workflow Architecture" width="550">
</p>


**Example Workflow:**

```javascript
export default {
  name: 'Apps Builder',
  steps: [
     resolveStep('git-commit', { executeOnce: true }), // Commit the initial project specification to git
    resolveStep('arch-agent', { executeOnce: true, engine: 'claude' }), // Define system architecture and technical design decisions
    resolveStep('plan-agent', { executeOnce: true, engine: 'claude', notCompletedFallback: 'plan-fallback' }), // Generate comprehensive iterative development plan with architectural artifacts
    resolveStep('task-breakdown', { executeOnce: true, engine: 'claude', notCompletedFallback: 'task-fallback' }), // Extract and structure tasks from project plan into JSON format
    resolveStep('git-commit', { executeOnce: true, engine: 'codex', model: 'gpt-5', modelReasoningEffort: 'low' }), // Commit the task breakdown to git
    resolveStep('context-manager', { engine: 'codex' , model: 'gpt-5', modelReasoningEffort: 'medium' }), // Gather and prepare relevant context from architecture, plan, and codebase for task execution
    resolveStep('code-generation', { engine: 'codex' , model: 'gpt-5', modelReasoningEffort: 'medium' }), // Generate code implementation based on task specifications and design artifacts
    resolveStep('runtime-prep', { executeOnce: true }), // Generate robust shell scripts for project automation (install, run, lint, test)
    resolveStep('task-sanity-check', { engine: 'codex' , model: 'gpt-5', modelReasoningEffort: 'medium' }), // Verify generated code against task requirements and acceptance criteria
    resolveStep('git-commit', { engine: 'codex', model: 'gpt-5', modelReasoningEffort: 'low' }), // Commit the generated and verified code
    resolveModule('check-task', { loopSteps: 6, loopMaxIterations: 20, loopSkip: ['runtime-prep'] }), // Loop back if tasks are not completed
  ],
  subAgentIds: ['frontend-agent', 'backend-agent', 'database-agent', 'auth-agent', 'testing-agent', 'deployment-agent'], // Sub-agents work in parallel
};
```
---
