Claudine - Task Delegation And Management Framework

Why Claudine Exists

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.

Features

• 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

See FEATURES.md for complete feature list.

Quick Start

Prerequisites

• Node.js 20.0.0+
• npm 10.0.0+
• Claude Code CLI installed (claude command available)

System Requirements

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+)

Installation

Add to your project's .mcp.json:

{
  "mcpServers": {
    "claudine": {
      "command": "npx",
      "args": ["-y", "claudine", "mcp", "start"]
    }
  }
}

Restart Claude Code to connect to Claudine.

Usage

MCP Tools

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 }) |

CLI Commands

| Command | Description | |---------|-------------| | claudine mcp start | Start the MCP server | | claudine delegate <task> | Submit new task | | claudine status [task-id] | Check task status (all tasks if no ID) | | claudine logs <task-id> | View task output | | claudine cancel <task-id> | Cancel running task | | claudine help | Show help |

Task Dependencies

Create workflows where tasks wait for dependencies to complete:

# Step 1: Create build task
claudine delegate "npm run build" --priority P1
# → task-abc123

# Step 2: Create test task that waits for build
claudine delegate "npm test" --depends-on task-abc123
# Task waits for build to complete before running

# Step 3: Create deploy task that waits for tests
claudine delegate "npm run deploy" --depends-on task-def456
# Execution order: build → test → deploy

Multiple 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]
});

See Task Dependencies Documentation for advanced patterns (diamond dependencies, error handling, failure propagation).

Architecture

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.

Configuration

Environment Variables

| 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 |

Per-Task Configuration

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
});

Development

Available Scripts

npm run dev        # Development mode with auto-reload
npm run build      # Build TypeScript
npm start          # Run built server
npm run typecheck  # Type checking
npm test           # Run tests
npm run clean      # Clean build artifacts

Testing

npm test                    # Run all tests (safe, sequential)
npm run test:coverage       # Run with coverage
npm run test:unit           # Unit tests only
npm run test:integration    # Integration tests only
npm run validate            # Validate entire setup

Project Structure

claudine/
├── 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

Roadmap

• [x] v0.2.0 - Autoscaling and persistence
• [x] v0.2.1 - Event-driven architecture and CLI
• [x] v0.2.3 - Stability improvements
• [x] v0.3.0 - Task dependency resolution
• [ ] v0.3.1 - Dependency performance optimizations
• [ ] v0.4.0 - Task resumption and scheduling
• [ ] v0.5.0 - Distributed multi-server processing

See ROADMAP.md for detailed plans and timelines.

Troubleshooting

Claude CLI not found

Ensure claude CLI is in your PATH:

which claude

Server won't start

Check logs in stderr and verify Node.js version:

node --version  # Should be v20.0.0+

Tasks fail immediately

Run in development mode to see detailed logs:

npm run dev

Contributing

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

License

MIT License - see LICENSE file for details

Support

• Report issues: GitHub Issues

Acknowledgments

Built with the Model Context Protocol SDK