The Problem: Claude Code is incredibly powerful, but you can only work on one thing at a time with a single claude code instance. This kills true multitasking and orchestration.
Our Belief: AI should scale with your ambition, not limit it. Why use only one Claude instance?
The Vision: Transform your machine or dedicated server into an AI powerhouse where you orchestrate multiple Claude Code instances through one main session. Work on authentication in repo A while simultaneously building APIs in repo B, all coordinated through your primary Claude Code interface - no context pollution, no workflow interruption.
- Event-Driven Architecture: Coordinates components through events, eliminating race conditions
- Intelligent Resource Management: Monitors CPU and memory in real-time, spawning workers when resources are available
- Task Persistence & Recovery: SQLite storage with automatic crash recovery
- Task Dependencies: DAG-based dependency resolution with cycle detection
- Task Scheduling: Cron and one-time scheduling with timezone support and missed run policies
- Task Resumption: Resume failed/completed tasks with enriched context from automatic checkpoints
See FEATURES.md for complete feature list.
- Node.js 20.0.0+
- npm 10.0.0+
- Claude Code CLI installed (
claudecommand available)
Minimum (for development/testing):
- 8+ CPU cores
- 16GB RAM
- 100GB SSD
Recommended (for production):
- 32+ CPU cores
- 64GB+ RAM
- 500GB+ NVMe SSD
- Dedicated Linux server (Ubuntu 22.04+)
Add to your project's .mcp.json:
{
"mcpServers": {
"delegate": {
"command": "npx",
"args": ["-y", "@dean0x/delegate", "mcp", "start"]
}
}
}Restart Claude Code to connect to Delegate.
Once configured, use these tools in Claude Code:
| Tool | Description | Usage |
|---|---|---|
| DelegateTask | Submit tasks to background instances | DelegateTask({ prompt: "...", priority: "P1" }) |
| TaskStatus | Get real-time task status | TaskStatus({ taskId }) |
| TaskLogs | Stream or retrieve execution logs | TaskLogs({ taskId }) |
| CancelTask | Cancel tasks with resource cleanup | CancelTask({ taskId, reason }) |
| RetryTask | Retry a failed or completed task | RetryTask({ taskId }) |
| ScheduleTask | Schedule recurring or one-time tasks | ScheduleTask({ prompt: "...", scheduleType: "cron", cronExpression: "0 2 * * *" }) |
| ListSchedules | List schedules with optional status filter | ListSchedules({ status: "active" }) |
| GetSchedule | Get schedule details and execution history | GetSchedule({ scheduleId }) |
| CancelSchedule | Cancel an active schedule | CancelSchedule({ scheduleId, reason }) |
| PauseSchedule | Pause a schedule (resumable) | PauseSchedule({ scheduleId }) |
| ResumeSchedule | Resume a paused schedule | ResumeSchedule({ scheduleId }) |
| ResumeTask | Resume a failed/completed task with checkpoint context | ResumeTask({ taskId, additionalContext? }) |
| Command | Description |
|---|---|
delegate mcp start |
Start the MCP server |
delegate delegate <task> |
Submit new task |
delegate status [task-id] |
Check task status (all tasks if no ID) |
delegate logs <task-id> |
View task output |
delegate cancel <task-id> |
Cancel running task |
delegate schedule create <prompt> |
Create a cron or one-time schedule |
delegate schedule list |
List schedules with optional status filter |
delegate schedule get <id> |
Get schedule details and execution history |
delegate schedule pause <id> |
Pause an active schedule |
delegate schedule resume <id> |
Resume a paused schedule |
delegate schedule cancel <id> |
Cancel a schedule |
delegate pipeline <prompt> ... |
Create chained one-time schedules with delays |
delegate resume <task-id> |
Resume a task from its checkpoint |
delegate help |
Show help |
Create workflows where tasks wait for dependencies to complete:
# Step 1: Create build task
delegate delegate "npm run build" --priority P1
# → task-abc123
# Step 2: Create test task that waits for build
delegate delegate "npm test" --depends-on task-abc123
# Task waits for build to complete before running
# Step 3: Create deploy task that waits for tests
delegate delegate "npm run deploy" --depends-on task-def456
# Execution order: build → test → deployMultiple dependencies (parallel execution):
// lint and format run in parallel
const lint = await DelegateTask({ prompt: "npm run lint" });
const format = await DelegateTask({ prompt: "npm run format" });
// commit waits for both to complete
const commit = await DelegateTask({
prompt: "git commit -m 'Formatted and linted'",
dependsOn: [lint.taskId, format.taskId]
});Session continuation (pass output context through dependency chains):
// Build task runs first
const build = await DelegateTask({ prompt: "npm run build" });
// Test task receives build's output/git state in its prompt
const test = await DelegateTask({
prompt: "npm test",
dependsOn: [build.taskId],
continueFrom: build.taskId
});When continueFrom is set, the dependent task's prompt is automatically enriched with the dependency's checkpoint context (output summary, git state, errors) before execution.
See Task Dependencies Documentation for advanced patterns (diamond dependencies, error handling, failure propagation).
Schedule tasks for future or recurring execution:
// Recurring: daily backup at 2am EST
await ScheduleTask({
prompt: "Backup database to S3",
scheduleType: "cron",
cronExpression: "0 2 * * *",
timezone: "America/New_York",
missedRunPolicy: "catchup"
});
// One-time: deploy tomorrow at 8am UTC
await ScheduleTask({
prompt: "Deploy to production",
scheduleType: "one_time",
scheduledAt: "2026-02-19T08:00:00Z"
});Schedule types: cron (5-field expressions) and one_time (ISO 8601 datetime). Missed run policies: skip, catchup, fail. Supports IANA timezones and concurrent execution prevention.
Resume failed or completed tasks with enriched context from automatic checkpoints:
# Resume a failed task
delegate resume task-abc123
# Resume with additional instructions
delegate resume task-abc123 --context "Try a different approach this time"// Via MCP
await ResumeTask({
taskId: "task-abc123",
additionalContext: "Focus on the database migration step"
});Checkpoints are captured automatically on task completion/failure, preserving git state (branch, SHA, dirty files) and the last 50 lines of output. Resumed tasks receive the full checkpoint context in their prompt and track lineage via parentTaskId and retryOf fields.
Event-driven system with autoscaling workers and SQLite persistence. Components communicate through a central EventBus, eliminating race conditions and direct state management.
Task Lifecycle: Queued → Running → Completed / Failed / Cancelled
See Architecture Documentation for implementation details.
| Variable | Default | Range | Description |
|---|---|---|---|
TASK_TIMEOUT |
1800000 (30min) | 1000-86400000 | Task timeout in milliseconds |
MAX_OUTPUT_BUFFER |
10485760 (10MB) | 1024-1073741824 | Output buffer size in bytes |
CPU_THRESHOLD |
80 | 1-100 | CPU usage threshold percentage |
MEMORY_RESERVE |
1073741824 (1GB) | 0+ | Memory reserve in bytes |
LOG_LEVEL |
info | debug/info/warn/error | Logging verbosity |
Override limits for individual tasks:
// Long-running task with larger buffer
await DelegateTask({
prompt: "analyze large dataset",
timeout: 7200000, // 2 hours
maxOutputBuffer: 104857600 // 100MB
});
// Quick task with minimal resources
await DelegateTask({
prompt: "run eslint",
timeout: 30000, // 30 seconds
maxOutputBuffer: 1048576 // 1MB
});npm run dev # Development mode with auto-reload
npm run build # Build TypeScript
npm start # Run built server
npm run typecheck # Type checking
npm run clean # Clean build artifactsTests are grouped to prevent memory exhaustion. npm test is blocked as a safety measure.
# Grouped tests (fast, safe to run individually)
npm run test:core # Core domain logic (~3s)
npm run test:handlers # Service handlers (~3s)
npm run test:repositories # Data layer (~2s)
npm run test:adapters # MCP adapter (~2s)
npm run test:implementations # Other implementations (~2s)
npm run test:cli # CLI tests (~2s)
npm run test:integration # Integration tests
# Full suite (local terminal / CI only)
npm run test:all # All tests
npm run test:coverage # With coveragedelegate/
├── src/
│ ├── core/ # Core interfaces and types
│ ├── implementations/ # Service implementations
│ ├── services/ # Business logic & event handlers
│ ├── adapters/ # MCP adapter
│ ├── bootstrap.ts # Dependency injection
│ ├── cli.ts # CLI interface
│ └── index.ts # Entry point
├── dist/ # Compiled JavaScript
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── docs/ # Documentation
- v0.2.0 - Autoscaling and persistence
- v0.2.1 - Event-driven architecture and CLI
- v0.2.3 - Stability improvements
- v0.3.0 - Task dependency resolution
- v0.3.2 - Settling workers and spawn burst protection
- v0.3.3 - Test infrastructure and memory management
- v0.4.0 - Task scheduling and task resumption
- v0.5.0 - Distributed multi-server processing
See ROADMAP.md for detailed plans and timelines.
Ensure claude CLI is in your PATH:
which claudeCheck logs in stderr and verify Node.js version:
node --version # Should be v20.0.0+Run in development mode to see detailed logs:
npm run devContributions are welcome! Please read our contributing guidelines before submitting PRs.
MIT License - see LICENSE file for details
- Report issues: GitHub Issues
Built with the Model Context Protocol SDK