OpenClaw DevEngine

State-machine-driven agentic workflow for automated software development.

OpenClaw DevEngine orchestrates multiple AI agents to handle the complete software development lifecycle: Analysis, Planning, Implementation, Verification, and Documentation.

✨ Features

• 🏗️ Architect Agent — Breaks down goals into atomic file-level tasks
• 👷 Builder Agent — Generates complete, production-ready code
• 🔍 Auditor Agent — Creates comprehensive tests and verifies code
• 🔧 Fixer Agent — Self-heals code based on test failures
• 📝 Scribe Agent — Generates documentation
• ⚡ Parallel Execution — Tasks run concurrently when dependencies allow
• 💾 Checkpointing — Resume from failures without losing progress
• 🎯 Error Classification — Smart error categorization for targeted fixes
• 📊 Event System — Real-time progress tracking and monitoring

📦 Installation

npm install openclaw-dev-engine

Or install globally for CLI access:

npm install -g openclaw-dev-engine

🚀 Quick Start

CLI Usage

# Set your API key
export OPENAI_API_KEY=your-api-key

# Create a new project
dev-engine "Create a REST API with Express and TypeScript"

# Extend existing project
dev-engine "Add user authentication" ./my-project

# Resume from checkpoint
dev-engine "Create a todo app" --resume

# Verbose mode with detailed logging
dev-engine "Build a CLI tool" --verbose

# Specify concurrency and model
dev-engine "Create a React app" --concurrency 5 --model gpt-4

CLI Options

| Option | Short | Description | |--------|-------|-------------| | --help | -h | Show help message | | --version | -v | Show version number | | --verbose | -V | Enable verbose output | | --resume | -r | Resume from last checkpoint | | --concurrency <n> | -c | Max parallel tasks (default: 3) | | --model <name> | -m | LLM model to use |

Programmatic Usage

import { DevEngine } from 'openclaw-dev-engine';
import { OpenClawAdapter } from 'openclaw-dev-engine/adapters';

const adapter = new OpenClawAdapter(process.env.OPENAI_API_KEY);
const engine = new DevEngine(adapter, {
  maxConcurrency: 3,
  verbose: true,
  enableCheckpoints: true
});

// Subscribe to events
engine.events.on('task:complete', async (e) => {
  console.log(`Completed: ${e.data.taskId}`);
});

// Track progress
engine.progress.onProgress((p) => {
  console.log(`${p.percentage}% complete`);
});

// Execute
const result = await engine.run('Create a REST API');
console.log(result);

As an OpenClaw Skill

import { DevEngine } from 'openclaw-dev-engine';
import { SkillContext } from 'openclaw-dev-engine/interfaces';

const engine = new DevEngine(openclawAdapter);

const result = await engine.execute({
  adapter: openclawAdapter,
  parameters: {
    goal: 'Create a React component library',
    resume: false
  },
  workingDirectory: process.cwd()
});

if (result.success) {
  console.log('Generated files:', result.artifacts);
} else {
  console.error('Failed:', result.error);
}

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           DevEngine (ISkill)                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Architect  │→ │   Builder    │→ │   Auditor   │→ │   Scribe    │  │
│  │  (Planning)  │  │   (Code)     │  │   (Test)    │  │   (Docs)    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘ └─────────────┘  │
│                            ↓                ↓                           │
│                    ┌──────────────────────────────┐                     │
│                    │           Fixer              │                     │
│                    │     (Self-Healing Loop)      │                     │
│                    └──────────────────────────────┘                     │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                       TaskScheduler                              │   │
│  │  • DAG-based execution        • Concurrency control (Semaphore) │   │
│  │  • Dependency resolution      • Retry with backoff              │   │
│  │  • Priority scheduling        • Circular dependency detection    │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌────────────────────┐  ┌─────────────────┐  ┌────────────────────┐   │
│  │   StateManager     │  │ InterfaceExtract│  │  ErrorClassifier   │   │
│  │  (Checkpointing)   │  │   (AST-based)   │  │  (10 Categories)   │   │
│  └────────────────────┘  └─────────────────┘  └────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                     EngineEventEmitter                           │   │
│  │  • Typed events            • Progress tracking                   │   │
│  │  • Event history           • Filtered streams                    │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────┐
│                        IEnvironmentAdapter                              │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐   │
│  │ ILLMProvider│  │ IFileSystem │  │IShellAdapter│  │ IImageAdapter│   │
│  │ (streaming) │  │ (enhanced)  │  │(test runner)│  │  (optional)  │   │
│  └─────────────┘  └─────────────┘  └─────────────┘  └──────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

⚙️ Configuration

Engine Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxConcurrency | number | 3 | Maximum parallel tasks | | maxRetries | number | 3 | Retry attempts per task | | enableCheckpoints | boolean | true | Enable state persistence | | checkpointDir | string | .openclaw/state | Checkpoint directory | | verbose | boolean | false | Enable verbose logging | | testTimeout | number | 60000 | Test execution timeout (ms) |

Adapter Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | gpt-4-turbo-preview | LLM model to use | | baseUrl | string | OpenAI API | LLM API endpoint | | basePath | string | process.cwd() | Working directory | | logPrefix | string | OpenClaw | Log message prefix |

📡 Events

The engine emits typed events for monitoring:

// Phase lifecycle
engine.events.on('phase:start', async (e) => {
  console.log(`Phase: ${e.data.phase}`);
});

// Task lifecycle
engine.events.on('task:start', async (e) => {
  console.log(`Starting: ${e.data.taskId}`);
});

engine.events.on('task:complete', async (e) => {
  console.log(`Done: ${e.data.taskId} in ${e.data.duration}ms`);
});

engine.events.on('task:failed', async (e) => {
  console.error(`Failed: ${e.data.taskId} - ${e.data.error}`);
});

// Checkpoints
engine.events.on('checkpoint:saved', async (e) => {
  console.log(`Saved: ${e.data.planId}`);
});

// LLM calls
engine.events.on('llm:request', async (e) => {
  console.log(`LLM call: ${e.data.tokens} tokens`);
});

🔌 Custom Adapters

Implement custom adapters for different environments:

import { 
  IEnvironmentAdapter, 
  IFileSystem, 
  IShellAdapter, 
  ILLMProvider,
  ILogger 
} from 'openclaw-dev-engine/interfaces';

class MyCustomAdapter implements IEnvironmentAdapter {
  fs: IFileSystem = new MyFileSystem();
  shell: IShellAdapter = new MyShell();
  llm: ILLMProvider = new MyLLMProvider();
  logger: ILogger = new MyLogger();
  
  log(message: string, level = 'info') {
    this.logger.log(level, message);
  }
}

const engine = new DevEngine(new MyCustomAdapter());

🛡️ Error Handling

The engine automatically classifies errors and applies targeted fix strategies:

| Category | Examples | Fix Strategy | |----------|----------|--------------| | syntax | Missing brackets, invalid tokens | Check syntax structure | | type | Type mismatches, missing types | Fix type annotations | | import | Module not found, wrong path | Correct import paths | | runtime | Null access, undefined vars | Add defensive checks | | assertion | Test failures | Fix implementation or test | | timeout | Hanging tests | Add async handling | | permission | Access denied | Check file permissions | | resource | File not found | Verify paths exist | | network | Connection refused | Mock network calls |

🧪 Testing

# Run all tests
npm test

# Run unit tests only (mocked services)
npm run test:unit

# Run integration tests (mocked services)
npm run test:integration

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

📊 Benchmarks

Benchmarks test against real services and require API keys:

# Dry run (no API calls)
npm run benchmark:dry

# Run all benchmarks (costs $$$)
npm run benchmark

# Speed benchmarks only
npm run benchmark:speed

# Quality benchmarks only
npm run benchmark:quality

See benchmarks/README.md for details.

🔧 Development

# Clone repository
git clone https://github.com/openclaw/dev-engine

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

📁 Project Structure

src/
├── index.ts                 # Main exports
├── cli.ts                   # CLI entry point
├── interfaces/              # TypeScript interfaces
├── core/                    # Core engine components
│   ├── DevEngine.ts         # Main orchestrator
│   ├── TaskScheduler.ts     # DAG execution
│   ├── StateManager.ts      # Checkpointing
│   ├── InterfaceExtractor.ts # AST extraction
│   ├── ErrorClassifier.ts   # Error categorization
│   └── EventEmitter.ts      # Event system
├── adapters/                # Environment adapters
└── skills/                  # Prompt templates

tests/
├── mocks/                   # Mock adapters
├── unit/                    # Unit tests
└── integration/             # Integration tests

benchmarks/
├── suites/                  # Benchmark implementations
└── results/                 # Benchmark outputs

🌍 Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENAI_API_KEY | Yes* | OpenAI API key | | OPENCLAW_KEY | Yes* | Alternative key name |

*One of these is required.

📄 License

MIT

🤝 Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request