{"id":31076524,"url":"https://github.com/dean0x/claudine","last_synced_at":"2025-09-16T05:21:20.527Z","repository":{"id":310376132,"uuid":"1039272387","full_name":"dean0x/claudine","owner":"dean0x","description":"MCP server for delegating tasks to background Claude Code instances","archived":false,"fork":false,"pushed_at":"2025-09-06T19:03:45.000Z","size":301,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-07T02:24:31.004Z","etag":null,"topics":["ai-tools","automation","claude","claude-code","mcp","task-delegation","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dean0x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-16T21:11:28.000Z","updated_at":"2025-09-06T07:39:25.000Z","dependencies_parsed_at":"2025-08-17T18:38:31.517Z","dependency_job_id":null,"html_url":"https://github.com/dean0x/claudine","commit_stats":null,"previous_names":["dean0x/claudine"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/dean0x/claudine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dean0x%2Fclaudine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dean0x%2Fclaudine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dean0x%2Fclaudine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dean0x%2Fclaudine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dean0x","download_url":"https://codeload.github.com/dean0x/claudine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dean0x%2Fclaudine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275364760,"owners_count":25451517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-16T02:00:10.229Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","automation","claude","claude-code","mcp","task-delegation","typescript"],"created_at":"2025-09-16T05:21:14.785Z","updated_at":"2025-09-16T05:21:20.510Z","avatar_url":"https://github.com/dean0x.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claudine - Background Task Delegation MCP Server\n\n[![npm version](https://img.shields.io/npm/v/claudine.svg)](https://www.npmjs.com/package/claudine)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)\n[![CI](https://github.com/dean0x/claudine/actions/workflows/ci.yml/badge.svg)](https://github.com/dean0x/claudine/actions/workflows/ci.yml)\n![MCP](https://img.shields.io/badge/MCP-Compatible-purple)\n\n## Why Claudine Exists\n\n**The Problem**: Claude Code is incredibly powerful, but you can only work on one thing at a time. This kills true multitasking and orchestration:\n\n- **No parallel feature development** - Can't work on authentication while simultaneously building the API layer\n- **Cross-repository workflow breaks** - Switch from frontend to backend repo? Your main session context gets polluted by the detour\n- **Session context pollution** - Get sidetracked debugging? Your original feature work context is contaminated and lost\n- **No true orchestration** - Can't coordinate multiple Claude instances to work on interconnected parts of your system\n- **Single-threaded thinking** - Complex products require parallel workstreams, but Claude Code forces linear execution\n- **Context juggling overhead** - Constantly losing mental models when forced to switch between unrelated codebases\n\n**Our Belief**: AI should scale with your ambition, not limit it. why use only one Claude instance?\n\n**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.\n\n## How Claudine Works\n\n**Event-Driven Architecture**: Instead of managing state directly, Claudine uses events to coordinate between components, eliminating race conditions and ensuring reliability.\n\n**Intelligent Resource Management**: Monitors CPU and memory in real-time, spawning new Claude Code instances when resources are available, maintaining system stability.\n\n**Task Persistence \u0026 Recovery**: Every task is stored in SQLite with automatic recovery after crashes. Your work never gets lost.\n\n**No Artificial Limits**: Unlike traditional approaches, Claudine uses ALL available system resources - spawning as many workers as your server can handle.\n\n## What You Get\n\n✅ **Currently Available in v0.2.1**:\n- **Event-Driven Architecture**: Fully event-driven system with EventBus coordination\n- **Task Persistence**: SQLite-based storage with automatic recovery on startup\n- **CLI Interface**: Direct task management (`claudine delegate`, `claudine status`, etc.)\n- **Autoscaling**: Automatically spawns workers based on available CPU and memory  \n- **Priority Levels**: P0 (Critical), P1 (High), P2 (Normal) task prioritization\n- **Git Worktree Support**: Branch-based isolation with PR/manual/auto/patch merge strategies\n- **GitHub Integration**: Automatic PR creation with merge strategies\n- **Retry Logic**: Exponential backoff for transient failures (git, network, API)\n- **Resource Management**: Dynamic worker scaling with CPU/memory monitoring\n- **Output Capture**: Fixed process handling with proper stdin management\n- **Recovery System**: Automatic task recovery after crashes\n- **Configuration**: Environment variables and per-task overrides\n\n📋 **MCP Tools**:\n- **DelegateTask**: Submit tasks to background Claude Code instances\n- **TaskStatus**: Real-time status of all running and queued tasks\n- **TaskLogs**: Stream or retrieve execution logs from any task\n- **CancelTask**: Cancel tasks with automatic resource cleanup\n\nSee [FEATURES.md](./FEATURES.md) for complete feature documentation.\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20.0.0+ \n- npm 10.0.0+\n- Claude Code CLI installed (`claude` command available)\n\n### System Requirements\n\n**Minimum** (for development/testing):\n- 8+ CPU cores\n- 16GB RAM\n- 100GB SSD\n\n**Recommended** (for production):\n- 32+ CPU cores\n- 64GB+ RAM\n- 500GB+ NVMe SSD\n- Dedicated Linux server (Ubuntu 22.04+)\n\n### Installation \u0026 Configuration\n\n#### Production Setup (Recommended)\nAdd to your project's `.mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"claudine\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claudine\", \"mcp\", \"start\"]\n    }\n  }\n}\n```\n\n#### Local Development\nFor developing Claudine itself:\n```json\n{\n  \"mcpServers\": {\n    \"claudine\": {\n      \"command\": \"node\", \n      \"args\": [\"/path/to/claudine/dist/cli.js\", \"mcp\", \"start\"]\n    }\n  }\n}\n```\n\nAfter adding the configuration, restart Claude Code to connect to Claudine.\n\n## Usage\n\n### CLI Commands\n\n#### MCP Server Management\n```bash\n# Start the MCP server\nclaudine mcp start\n\n# Test server startup and validation\nclaudine mcp test\n\n# Show MCP configuration\nclaudine mcp config\n```\n\n#### Direct Task Management (New in v0.2.1)\n```bash\n# Delegate a task directly\nclaudine delegate \"Create a Python script to analyze CSV data\"\n\n# Check status of all tasks\nclaudine status\n\n# Check specific task status\nclaudine status \u003ctask-id\u003e\n\n# Get task logs (with optional tail)\nclaudine logs \u003ctask-id\u003e [--tail 100]\n\n# Cancel a running task\nclaudine cancel \u003ctask-id\u003e [reason]\n\n# Show help\nclaudine help\n```\n\n### MCP Tools in Claude Code\n\nOnce configured, you can use Claudine's tools in Claude Code:\n\n### Delegate a Task\n\n```\nUse DelegateTask to run: \"Create a Python script that analyzes CSV data\"\n```\n\n### Check Task Status\n\n```\nUse TaskStatus to check the current task\n```\n\n### Get Task Logs\n\n```\nUse TaskLogs with taskId: \u003ctask-id-here\u003e\n```\n\n### Cancel a Task\n\n```\nUse CancelTask with taskId: \u003ctask-id-here\u003e and reason: \"Taking too long\"\n```\n\n## Development\n\n### Available Scripts\n\n```bash\n# Development mode (with auto-reload)\nnpm run dev\n\n# Build TypeScript\nnpm run build\n\n# Run built server\nnpm start\n\n# Type checking\nnpm run typecheck\n\n# Run tests\nnpm test\n\n# Clean build artifacts\nnpm run clean\n```\n\n### Testing\n\n```bash\n# Run tests\nnpm test\n\n# Run comprehensive tests\nnpm run test:comprehensive\n\n# Validate entire setup\nnpm run validate\n```\n\n### Project Structure\n\n```\nclaudine/\n├── src/\n│   ├── index.ts              # Entry point\n│   ├── cli.ts                # CLI interface\n│   ├── bootstrap.ts          # Dependency injection\n│   ├── core/                 # Core interfaces and types\n│   ├── implementations/      # Service implementations\n│   ├── services/             # Business logic\n│   └── adapters/             # MCP adapter\n├── dist/                     # Compiled JavaScript\n├── tests/\n│   ├── unit/                 # Unit tests\n│   └── integration/          # Integration tests\n├── .docs/                    # Internal documentation\n└── README.md\n```\n\n## Architecture\n\n### Dedicated Server Design\n\nClaudine is optimized for **dedicated servers** with ample resources, not constrained environments:\n\n- **Autoscaling Workers**: Spawns as many Claude Code instances as your system can handle\n- **Dynamic Resource Monitoring**: Continuously checks CPU and memory availability\n- **Queue-Based Load Management**: Processes tasks from queue as resources become available\n- **Zero Configuration**: No worker limits or tuning required\n\n### Core Components\n\n**Event-Driven Architecture (New in v0.2.1)**:\n1. **EventBus**: Central coordination hub for all system events\n2. **Event Handlers**: Specialized handlers for persistence, queue, worker, and output events\n3. **MCP Server**: Handles JSON-RPC requests from Claude Code\n4. **Task Manager**: Event-driven orchestrator (no direct state management)\n5. **Autoscaling Manager**: Event-based worker scaling with resource monitoring\n6. **Task Queue**: Priority-based queue with event-driven processing\n7. **Worker Pool**: Event-driven worker lifecycle management\n8. **Output Capture**: Event-based output handling with proper stdin management\n9. **Task Persistence**: SQLite database with WAL mode for concurrent access\n10. **Recovery Manager**: Restores interrupted tasks via events on startup\n\n### Task Lifecycle\n\n1. **Queued**: Task waiting for available resources\n2. **Running**: Claude Code process actively executing\n3. **Completed**: Task finished successfully (exit code 0)\n4. **Failed**: Task failed with error\n5. **Cancelled**: Task manually cancelled by user\n\n## Configuration\n\n### Environment Variables\n\n- `TASK_TIMEOUT`: Task timeout in milliseconds (default: 1800000 = 30 minutes, range: 1000-86400000)\n- `MAX_OUTPUT_BUFFER`: Output buffer size in bytes (default: 10485760 = 10MB, range: 1024-1073741824)  \n- `CPU_THRESHOLD`: CPU usage threshold percentage (default: 80, range: 1-100)\n- `MEMORY_RESERVE`: Memory reserve in bytes (default: 1073741824 = 1GB, range: 0+)\n- `LOG_LEVEL`: Logging level (default: 'info', options: 'debug', 'info', 'warn', 'error')\n\n### Per-Task Configuration\n\nYou can override timeout and buffer limits for individual tasks via MCP parameters:\n\n```javascript\n// Example: Long-running task with larger buffer\nawait claudine.DelegateTask({\n  prompt: \"analyze large dataset and generate report\", \n  timeout: 7200000,        // 2 hours\n  maxOutputBuffer: 104857600  // 100MB\n});\n\n// Example: Quick task with minimal resources  \nawait claudine.DelegateTask({\n  prompt: \"run eslint on current file\",\n  timeout: 30000,          // 30 seconds\n  maxOutputBuffer: 1048576    // 1MB\n});\n```\n\n## Current Limitations\n\n- No task dependency resolution (planned for v0.3.0)  \n- No distributed execution across multiple machines (planned for v0.4.0)\n- No web dashboard (monitoring via logs only)\n\nFor complete feature list, see [FEATURES.md](./FEATURES.md).\n\n## Troubleshooting\n\n### Claude CLI not found\n\nEnsure `claude` CLI is in your PATH:\n```bash\nwhich claude\n```\n\n### Server won't start\n\nCheck logs in stderr and verify Node.js version:\n```bash\nnode --version  # Should be v20.0.0+\n```\n\n### Tasks fail immediately\n\nRun in development mode:\n```bash\nnpm run dev\n```\n\n## Roadmap\n\n- [x] **v0.2.0**: Autoscaling and persistence (Released Sep 2025)\n- [x] **v0.2.1**: Event-driven architecture and CLI commands (Current - Released Sep 2025)\n- [ ] **v0.3.0**: Task dependency resolution (Q4 2025)\n- [ ] **v0.4.0**: Distributed processing (Q1 2026)\n- [ ] **v0.5.0**: Advanced orchestration and monitoring (Q2 2026)\n\nSee [ROADMAP.md](./ROADMAP.md) for detailed feature plans and timelines.\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines before submitting PRs.\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Support\n\n- Report issues: [GitHub Issues](https://github.com/dean0x/claudine/issues)\n\n## Acknowledgments\n\nBuilt with the [Model Context Protocol SDK](https://modelcontextprotocol.io)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdean0x%2Fclaudine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdean0x%2Fclaudine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdean0x%2Fclaudine/lists"}