> **ðĨ The most flexible fire-and-forget task execution system + prod-level MCP for Claude Code SDK**
> Run with zero infrastructure (MCP standalone) or at scale (REST API + Workers)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://fastapi.tiangolo.com)
[](LICENSE)
[-orange.svg)](https://pypi.org/project/claude-worker/)
[](docs/00-overview.md)
## ðŊ Why Claude Worker?
**The Problem:** Claude Code tasks may take a few minutes to finish. Running them interactively in your terminal can be time-consuming. When possible, you can run tasks in parallel to save time. By using Claude Code as a CTO and running it in MCP server mode, you can execute multiple tasks simultaneously.
**The Solution:** Claude Worker provides a robust task execution system that:
- â
**Runs anywhere** - From lightweight CLI tools to MCP that can be used by another Claude Code
- â
**Never loses work** - SQLite persistence survives crashes (local, accessible DB)
- â
**Scales flexibly** - Process isolation with configurable workers
- â
**Integrates everywhere** - MCP, CLI, REST API (not documented) or programmatic
## ðïļ Architecture: Two Modes, One Codebase
```mermaid
graph TB
subgraph "Lightweight Mode (MCP Only)"
User1[Claude Desktop/Code] -->|stdio| MCP1[MCP Server]
MCP1 --> DB1[(Embedded SQLite)]
MCP1 --> Executor1[Direct Execution]
end
subgraph "Full Stack Mode (REST + MCP)"
User2[CLI/API Client] -->|HTTP| REST[REST API]
User3[Claude Desktop] -->|stdio| MCP2[MCP Proxy]
MCP2 -->|HTTP| REST
REST --> DB2[(Shared Database)]
REST --> Pool[Process Pool]
Pool --> Workers[Worker Processes]
end
style MCP1 fill:#90EE90
style MCP2 fill:#87CEEB
style REST fill:#FFB6C1
```
## ⥠Quick Start
### Choose Your Path:
<table>
<tr>
<td width="30%">
### ðĒ CLI Mode
**For:** Set tasks from both CLI, flexible to add tasks by MD/TXT files or just plain text commands!
```bash
pip install "claude-worker[server]" <- (ðĄ if you want both, use claude-worker[full] )
claude-worker server start
claude-worker run "Your task"
```
[â Quick Start Guide](docs/01-getting-started-quick-start.md)
</td>
<td width="30%">
### ðŠķ MCP Mode
**For:** Use 'Claude Code' as planner (CTO) and use 'Claude Code Worker' to execute tasks (dev) in parallel
```bash
pip install "claude-worker[mcp]" <- (ðĄ if you want both, use claude-worker[full] )
fastmcp install claude-desktop \
claude-worker-mcp
```
[â Installation Guide](docs/01-getting-started-installation.md)
</td>
</tr>
</table>
---
## ð Documentation
Comprehensive documentation is available in the `docs/` directory:
### ð Getting Started
- **[Overview](docs/00-overview.md)** - Project introduction and feature overview
- **[Installation](docs/01-getting-started-installation.md)** - Complete setup guide for all platforms
- **[Quick Start](docs/01-getting-started-quick-start.md)** - Get running in 5 minutes
### ð User Guides
- **[CLI Reference](docs/02-user-guide-cli-reference.md)** - Complete command reference
- **[Task Submission](docs/02-user-guide-task-submission.md)** - Advanced submission methods (files, stdin, automation)
- **[Monitoring & Logs](docs/02-user-guide-monitoring-and-logs.md)** - Status checking and debugging
### ðïļ Core Concepts
- **[Architecture](docs/03-concepts-architecture.md)** - System design and component overview
- **[Database Schema](docs/03-concepts-database-schema.md)** - Data model and persistence
- **[Process Model](docs/03-concepts-process-model.md)** - Task execution lifecycle
- **[Project Philosophy](docs/03-concepts-project-philosophy.md)** - Design principles and SOLE responsibility
### ð Integrations
- **[REST API](docs/04-integrations-rest-api.md)** - HTTP endpoints and data models
- **[MCP for AI Agents](docs/04-integrations-mcp-for-agents.md)** - Model Context Protocol integration
- **[MCP with Claude Code](docs/04-integrations-mcp-claude-code.md)** - Error-driven prompt optimization and task delegation
### âïļ Administration
- **[Configuration](docs/05-administration-configuration.md)** - Environment variables and settings
- **[Deployment](docs/05-administration-deployment.md)** - Production deployment strategies
- **[Security](docs/05-administration-security.md)** - Security considerations and best practices
### ðĪ Contributing
- **[Development Setup](docs/06-contributing-development-setup.md)** - Local development environment
- **[Contribution Guide](docs/06-contributing-guide.md)** - How to contribute to the project
---
## ð Installation
### Prerequisites
- **Python 3.10+** and **Node.js 16+** (for Claude Code SDK)
- **Authentication** (choose one):
- ð **Anthropic API Key** ([Get yours here](https://console.anthropic.com/))
- ðŊ **Claude Max/Pro Subscription** (OAuth via Claude CLI - no setup needed!)
### Installation Options
```bash
# 1. MCP Tools Only (Lightweight)
pip install "claude-worker[mcp]"
# 2. REST API + CLI (No MCP)
pip install "claude-worker[server]"
# 3. Everything (Recommended)
pip install "claude-worker[full]"
# 4. From Source (Development)
git clone https://github.com/yigitkonur/claude-worker
cd claude-worker
poetry install
```
> ð **Need detailed setup instructions?** See the [Installation Guide](docs/01-getting-started-installation.md)
## ðŪ Usage Examples
### MCP Mode (Claude Code Integration) ð§
**The "CTO + Dev Team" Pattern**: Use Claude Code as the architect/planner, Claude Worker as the execution team.
```bash
# One-command installation
pip install "claude-worker[mcp]" && \
claude mcp add claude-worker -s user -- python -m claude_worker.mcp.factory
# Verify installation
claude mcp list # Should show claude-worker â Connected
```
**Smart Error-Driven Optimization** ðŊ
Claude Worker uses strategic validation errors to train AI agents to write better prompts:
| Validation Rule | Purpose | Example Fix |
|-----------------|---------|-------------|
| 150+ characters | Forces detailed context | "Fix bug" â "Fix JWT expiration bug in ./src/auth/login.js by updating token validation logic" |
| Path requirement | Ensures concrete actions | "Add tests" â "Add unit tests in ./tests/auth.test.js for login functionality" |
| "Minimalist" keyword* | Enforces surgical precision | Auto-adds focus on simple, direct solutions |
*_The "John Carmack" requirement is just a [clever metaphor](https://x.com/mattshumer_/status/1921276852200477114) that works because LLMs associate it with minimal, elegant code. It's hardcoded prompt engineering, not philosophy worship!_ ð
**Available Tools:**
- `create_task(prompt, dir, system_prompt)` - Delegate tasks with smart validation
- `get_task_status(id)` - Monitor progress with real-time updates
- `list_tasks(limit)` - View team dashboard
- `check_api_health()` - System health check
**Example: Error-Driven Prompt Optimization**
```javascript
// â This fails with helpful errors:
create_task("Add a function")
// Error: "Execution prompt must be at least 150 characters"
// Error: "Execution prompt must contain a path-like string"
// â
AI learns to write this instead:
create_task(
"Create calculateTotal() function in ./src/utils/math.js that takes array of numbers and returns sum. Include JSDoc comments and unit tests in ./tests/math.test.js",
"./my-project"
)
// Result: Precise, actionable task with clear deliverables
```
### Server Mode (CLI & API)
```bash
# Start server
claude-worker server start
# Submit tasks
claude-worker run "Create a README for my project"
claude-worker run "Refactor this code" --dir ./src --watch
# Monitor tasks
claude-worker list
claude-worker status 1
```
### Advanced Task Submission
```bash
# From files
claude-worker run prompt-template.txt --dir ./project
# From stdin (great for automation)
git diff | claude-worker run "Review these changes"
find . -name "*.py" | xargs -I {} claude-worker run "Document {}"
```
> ð **For comprehensive usage examples:** See [Task Submission Guide](docs/02-user-guide-task-submission.md) and [CLI Reference](docs/02-user-guide-cli-reference.md)
### REST API Usage
```python
# Python example
import httpx
client = httpx.Client(base_url="http://localhost:8000")
# Create task
task = client.post("/api/v1/tasks", json={
"execution_prompt": "Build a todo app with FastAPI",
"working_directory": "./project",
"system_prompt": "You are a Python expert"
}).json()
# Check status
status = client.get(f"/api/v1/tasks/{task['id']}").json()
print(f"Task {task['id']}: {status['status']}")
```
```javascript
// JavaScript example
const response = await fetch('http://localhost:8000/api/v1/tasks', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
execution_prompt: 'Build a todo app with FastAPI',
working_directory: './project'
})
});
const task = await response.json();
```
> ð **For complete API documentation:** See [REST API Reference](docs/04-integrations-rest-api.md)
## ð§ Configuration
### ð Authentication Setup
Claude Worker supports **two authentication methods** automatically:
<table>
<tr>
<td width="50%">
#### ð API Key Method
```bash
export ANTHROPIC_API_KEY=your-api-key-here
claude-worker run "your task"
```
**Best for:** Teams, CI/CD, granular billing control
</td>
<td width="50%">
#### ðŊ Claude Max/Pro (OAuth)
```bash
# No setup needed!
claude-worker run "your task"
```
**Best for:** Individual users with Claude subscription
</td>
</tr>
</table>
> ðĄ **Smart Authentication:** Claude Worker automatically tries API key first, then falls back to your Claude Max subscription. No configuration needed!
### Optional Environment Variables
```bash
export CLAUDE_WORKER_DB=~/.claude-worker/tasks.db
export CLAUDE_WORKER_SERVER_URL=http://localhost:8000 # for CLI client
export CLAUDE_WORKER_LOG_DIR=~/.claude-worker/logs
```
> ð **For complete configuration options:** See [Configuration Guide](docs/05-administration-configuration.md)
## ð Troubleshooting
### Quick Fixes for Common Issues
| Issue | Quick Fix |
|-------|-----------|
| **MCP not showing in Claude Desktop** | Restart Claude Desktop completely (Cmd+Q) |
| **Tasks stuck in "running"** | Check authentication: API key or Claude CLI login |
| **Authentication failed** | Try: `claude --version` to test Claude CLI |
| **Database lock errors** | Stop all services: `pkill -f claude-worker` |
| **Permission denied** | Fix permissions: `chmod 755 ~/.claude-worker` |
### Debug Commands
```bash
# Check system status
claude-worker server health
# Check authentication
echo $ANTHROPIC_API_KEY # Check if API key is set
claude --version # Test Claude CLI (for OAuth)
# View logs
tail -f ~/.claude-worker/logs/*.log
# List processes
ps aux | grep claude-worker
```
> ð **For detailed troubleshooting:** See [Security Guide](docs/05-administration-security.md) and check the issues on GitHub
## ðĒ Production Deployment
### Docker (Recommended)
```bash
# Quick start with Docker Compose
curl -O https://raw.githubusercontent.com/yigitkonur/claude-worker/main/docker-compose.yml
echo "ANTHROPIC_API_KEY=your-key" > .env
docker-compose up -d
```
```dockerfile
# Custom Dockerfile
FROM python:3.11-slim
WORKDIR /app
RUN pip install "claude-worker[full]"
ENV CLAUDE_WORKER_DB=/data/tasks.db
EXPOSE 8000
CMD ["claude-worker", "server", "start", "--host", "0.0.0.0"]
```
### Systemd Service
```ini
# /etc/systemd/system/claude-worker.service
[Unit]
Description=Claude Worker Server
After=network.target
[Service]
Type=exec
User=claude
WorkingDirectory=/opt/claude-worker
Environment="ANTHROPIC_API_KEY=your-key-here"
ExecStart=/usr/local/bin/claude-worker server start --host 0.0.0.0
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
> ð **For comprehensive deployment guides:** See [Deployment Guide](docs/05-administration-deployment.md)
## ðïļ Architecture Principles
- **ðŊ SOLE Responsibility**: Each module has Single, Overarching, Lucidly-stated Expertise
- **ð Process Isolation**: Every task runs in its own process for safety
- **ðū Fail-Safe**: SQLite persistence ensures no work is lost
- **ð§ Extensible**: Clear interfaces for adding new features
> ð **Learn more about the design:** See [Project Philosophy](docs/03-concepts-project-philosophy.md) and [Architecture Overview](docs/03-concepts-architecture.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-worker",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "claude, ai, automation, task-queue, cli, mcp, anthropic",
"author": "Yigit Konur",
"author_email": "yigit@thinkbuddy.ai",
"download_url": "https://files.pythonhosted.org/packages/50/9b/ad761dd01c047ee0429eab603d52d1e5c08e1d9fab9e20c91e56a5441af1/claude_worker-0.2.0.tar.gz",
"platform": null,
"description": "\n> **\ud83d\udd25 The most flexible fire-and-forget task execution system + prod-level MCP for Claude Code SDK** \n> Run with zero infrastructure (MCP standalone) or at scale (REST API + Workers)\n\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io)\n[](https://fastapi.tiangolo.com)\n[](LICENSE)\n[-orange.svg)](https://pypi.org/project/claude-worker/)\n[](docs/00-overview.md)\n\n## \ud83c\udfaf Why Claude Worker?\n\n**The Problem:** Claude Code tasks may take a few minutes to finish. Running them interactively in your terminal can be time-consuming. When possible, you can run tasks in parallel to save time. By using Claude Code as a CTO and running it in MCP server mode, you can execute multiple tasks simultaneously.\n\n**The Solution:** Claude Worker provides a robust task execution system that:\n\n- \u2705 **Runs anywhere** - From lightweight CLI tools to MCP that can be used by another Claude Code\n- \u2705 **Never loses work** - SQLite persistence survives crashes (local, accessible DB)\n- \u2705 **Scales flexibly** - Process isolation with configurable workers\n- \u2705 **Integrates everywhere** - MCP, CLI, REST API (not documented) or programmatic\n\n## \ud83c\udfd7\ufe0f Architecture: Two Modes, One Codebase\n\n```mermaid\ngraph TB\n subgraph \"Lightweight Mode (MCP Only)\"\n User1[Claude Desktop/Code] -->|stdio| MCP1[MCP Server]\n MCP1 --> DB1[(Embedded SQLite)]\n MCP1 --> Executor1[Direct Execution]\n end\n \n subgraph \"Full Stack Mode (REST + MCP)\"\n User2[CLI/API Client] -->|HTTP| REST[REST API]\n User3[Claude Desktop] -->|stdio| MCP2[MCP Proxy]\n MCP2 -->|HTTP| REST\n REST --> DB2[(Shared Database)]\n REST --> Pool[Process Pool]\n Pool --> Workers[Worker Processes]\n end\n \n style MCP1 fill:#90EE90\n style MCP2 fill:#87CEEB\n style REST fill:#FFB6C1\n```\n\n## \u26a1 Quick Start\n\n### Choose Your Path:\n\n<table>\n<tr>\n<td width=\"30%\">\n\n### \ud83c\udfe2 CLI Mode\n**For:** Set tasks from both CLI, flexible to add tasks by MD/TXT files or just plain text commands!\n\n```bash\npip install \"claude-worker[server]\" <- (\ud83d\udca1 if you want both, use claude-worker[full] )\nclaude-worker server start\nclaude-worker run \"Your task\"\n```\n\n[\u2192 Quick Start Guide](docs/01-getting-started-quick-start.md)\n\n</td>\n<td width=\"30%\">\n\n### \ud83e\udeb6 MCP Mode\n**For:** Use 'Claude Code' as planner (CTO) and use 'Claude Code Worker' to execute tasks (dev) in parallel\n\n```bash\npip install \"claude-worker[mcp]\" <- (\ud83d\udca1 if you want both, use claude-worker[full] )\nfastmcp install claude-desktop \\\n claude-worker-mcp\n```\n\n[\u2192 Installation Guide](docs/01-getting-started-installation.md)\n\n</td>\n</tr>\n</table>\n\n---\n\n## \ud83d\udcda Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n### \ud83d\ude80 Getting Started\n- **[Overview](docs/00-overview.md)** - Project introduction and feature overview\n- **[Installation](docs/01-getting-started-installation.md)** - Complete setup guide for all platforms\n- **[Quick Start](docs/01-getting-started-quick-start.md)** - Get running in 5 minutes\n\n### \ud83d\udcd6 User Guides \n- **[CLI Reference](docs/02-user-guide-cli-reference.md)** - Complete command reference\n- **[Task Submission](docs/02-user-guide-task-submission.md)** - Advanced submission methods (files, stdin, automation)\n- **[Monitoring & Logs](docs/02-user-guide-monitoring-and-logs.md)** - Status checking and debugging\n\n### \ud83c\udfd7\ufe0f Core Concepts\n- **[Architecture](docs/03-concepts-architecture.md)** - System design and component overview\n- **[Database Schema](docs/03-concepts-database-schema.md)** - Data model and persistence\n- **[Process Model](docs/03-concepts-process-model.md)** - Task execution lifecycle\n- **[Project Philosophy](docs/03-concepts-project-philosophy.md)** - Design principles and SOLE responsibility\n\n### \ud83d\udd0c Integrations\n- **[REST API](docs/04-integrations-rest-api.md)** - HTTP endpoints and data models\n- **[MCP for AI Agents](docs/04-integrations-mcp-for-agents.md)** - Model Context Protocol integration\n- **[MCP with Claude Code](docs/04-integrations-mcp-claude-code.md)** - Error-driven prompt optimization and task delegation\n\n### \u2699\ufe0f Administration\n- **[Configuration](docs/05-administration-configuration.md)** - Environment variables and settings\n- **[Deployment](docs/05-administration-deployment.md)** - Production deployment strategies\n- **[Security](docs/05-administration-security.md)** - Security considerations and best practices\n\n### \ud83e\udd1d Contributing\n- **[Development Setup](docs/06-contributing-development-setup.md)** - Local development environment\n- **[Contribution Guide](docs/06-contributing-guide.md)** - How to contribute to the project\n\n---\n\n## \ud83d\ude80 Installation\n\n### Prerequisites\n\n- **Python 3.10+** and **Node.js 16+** (for Claude Code SDK)\n- **Authentication** (choose one):\n - \ud83d\udd11 **Anthropic API Key** ([Get yours here](https://console.anthropic.com/))\n - \ud83c\udfaf **Claude Max/Pro Subscription** (OAuth via Claude CLI - no setup needed!)\n\n### Installation Options\n\n```bash\n# 1. MCP Tools Only (Lightweight)\npip install \"claude-worker[mcp]\"\n\n# 2. REST API + CLI (No MCP) \npip install \"claude-worker[server]\"\n\n# 3. Everything (Recommended)\npip install \"claude-worker[full]\"\n\n# 4. From Source (Development)\ngit clone https://github.com/yigitkonur/claude-worker\ncd claude-worker\npoetry install\n```\n\n> \ud83d\udcd6 **Need detailed setup instructions?** See the [Installation Guide](docs/01-getting-started-installation.md)\n\n## \ud83c\udfae Usage Examples\n\n### MCP Mode (Claude Code Integration) \ud83e\udde0\n\n**The \"CTO + Dev Team\" Pattern**: Use Claude Code as the architect/planner, Claude Worker as the execution team.\n\n```bash\n# One-command installation\npip install \"claude-worker[mcp]\" && \\\nclaude mcp add claude-worker -s user -- python -m claude_worker.mcp.factory\n\n# Verify installation\nclaude mcp list # Should show claude-worker \u2713 Connected\n```\n\n**Smart Error-Driven Optimization** \ud83c\udfaf\n\nClaude Worker uses strategic validation errors to train AI agents to write better prompts:\n\n| Validation Rule | Purpose | Example Fix |\n|-----------------|---------|-------------|\n| 150+ characters | Forces detailed context | \"Fix bug\" \u2192 \"Fix JWT expiration bug in ./src/auth/login.js by updating token validation logic\" |\n| Path requirement | Ensures concrete actions | \"Add tests\" \u2192 \"Add unit tests in ./tests/auth.test.js for login functionality\" |\n| \"Minimalist\" keyword* | Enforces surgical precision | Auto-adds focus on simple, direct solutions |\n\n*_The \"John Carmack\" requirement is just a [clever metaphor](https://x.com/mattshumer_/status/1921276852200477114) that works because LLMs associate it with minimal, elegant code. It's hardcoded prompt engineering, not philosophy worship!_ \ud83d\ude04\n\n**Available Tools:**\n- `create_task(prompt, dir, system_prompt)` - Delegate tasks with smart validation\n- `get_task_status(id)` - Monitor progress with real-time updates \n- `list_tasks(limit)` - View team dashboard\n- `check_api_health()` - System health check\n\n**Example: Error-Driven Prompt Optimization**\n```javascript\n// \u274c This fails with helpful errors:\ncreate_task(\"Add a function\")\n// Error: \"Execution prompt must be at least 150 characters\"\n// Error: \"Execution prompt must contain a path-like string\"\n\n// \u2705 AI learns to write this instead:\ncreate_task(\n \"Create calculateTotal() function in ./src/utils/math.js that takes array of numbers and returns sum. Include JSDoc comments and unit tests in ./tests/math.test.js\",\n \"./my-project\"\n)\n// Result: Precise, actionable task with clear deliverables\n```\n\n### Server Mode (CLI & API)\n\n```bash\n# Start server\nclaude-worker server start\n\n# Submit tasks\nclaude-worker run \"Create a README for my project\"\nclaude-worker run \"Refactor this code\" --dir ./src --watch\n\n# Monitor tasks\nclaude-worker list\nclaude-worker status 1\n```\n\n### Advanced Task Submission\n\n```bash\n# From files\nclaude-worker run prompt-template.txt --dir ./project\n\n# From stdin (great for automation)\ngit diff | claude-worker run \"Review these changes\"\nfind . -name \"*.py\" | xargs -I {} claude-worker run \"Document {}\"\n```\n\n> \ud83d\udcd6 **For comprehensive usage examples:** See [Task Submission Guide](docs/02-user-guide-task-submission.md) and [CLI Reference](docs/02-user-guide-cli-reference.md)\n\n### REST API Usage\n\n```python\n# Python example\nimport httpx\n\nclient = httpx.Client(base_url=\"http://localhost:8000\")\n\n# Create task\ntask = client.post(\"/api/v1/tasks\", json={\n \"execution_prompt\": \"Build a todo app with FastAPI\",\n \"working_directory\": \"./project\",\n \"system_prompt\": \"You are a Python expert\"\n}).json()\n\n# Check status\nstatus = client.get(f\"/api/v1/tasks/{task['id']}\").json()\nprint(f\"Task {task['id']}: {status['status']}\")\n```\n\n```javascript\n// JavaScript example\nconst response = await fetch('http://localhost:8000/api/v1/tasks', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n execution_prompt: 'Build a todo app with FastAPI',\n working_directory: './project'\n })\n});\nconst task = await response.json();\n```\n\n> \ud83d\udcd6 **For complete API documentation:** See [REST API Reference](docs/04-integrations-rest-api.md)\n\n## \ud83d\udd27 Configuration\n\n### \ud83d\udd10 Authentication Setup\n\nClaude Worker supports **two authentication methods** automatically:\n\n<table>\n<tr>\n<td width=\"50%\">\n\n#### \ud83d\udd11 API Key Method\n```bash\nexport ANTHROPIC_API_KEY=your-api-key-here\nclaude-worker run \"your task\"\n```\n**Best for:** Teams, CI/CD, granular billing control\n\n</td>\n<td width=\"50%\">\n\n#### \ud83c\udfaf Claude Max/Pro (OAuth)\n```bash\n# No setup needed! \nclaude-worker run \"your task\"\n```\n**Best for:** Individual users with Claude subscription\n\n</td>\n</tr>\n</table>\n\n> \ud83d\udca1 **Smart Authentication:** Claude Worker automatically tries API key first, then falls back to your Claude Max subscription. No configuration needed!\n\n### Optional Environment Variables\n\n```bash\nexport CLAUDE_WORKER_DB=~/.claude-worker/tasks.db\nexport CLAUDE_WORKER_SERVER_URL=http://localhost:8000 # for CLI client\nexport CLAUDE_WORKER_LOG_DIR=~/.claude-worker/logs\n```\n\n> \ud83d\udcd6 **For complete configuration options:** See [Configuration Guide](docs/05-administration-configuration.md)\n\n## \ud83d\udc1b Troubleshooting\n\n### Quick Fixes for Common Issues\n\n| Issue | Quick Fix |\n|-------|-----------|\n| **MCP not showing in Claude Desktop** | Restart Claude Desktop completely (Cmd+Q) |\n| **Tasks stuck in \"running\"** | Check authentication: API key or Claude CLI login |\n| **Authentication failed** | Try: `claude --version` to test Claude CLI |\n| **Database lock errors** | Stop all services: `pkill -f claude-worker` |\n| **Permission denied** | Fix permissions: `chmod 755 ~/.claude-worker` |\n\n### Debug Commands\n\n```bash\n# Check system status\nclaude-worker server health\n\n# Check authentication\necho $ANTHROPIC_API_KEY # Check if API key is set\nclaude --version # Test Claude CLI (for OAuth)\n\n# View logs\ntail -f ~/.claude-worker/logs/*.log\n\n# List processes\nps aux | grep claude-worker\n```\n\n> \ud83d\udcd6 **For detailed troubleshooting:** See [Security Guide](docs/05-administration-security.md) and check the issues on GitHub\n\n## \ud83d\udea2 Production Deployment\n\n### Docker (Recommended)\n\n```bash\n# Quick start with Docker Compose\ncurl -O https://raw.githubusercontent.com/yigitkonur/claude-worker/main/docker-compose.yml\necho \"ANTHROPIC_API_KEY=your-key\" > .env\ndocker-compose up -d\n```\n\n```dockerfile\n# Custom Dockerfile\nFROM python:3.11-slim\nWORKDIR /app\nRUN pip install \"claude-worker[full]\"\nENV CLAUDE_WORKER_DB=/data/tasks.db\nEXPOSE 8000\nCMD [\"claude-worker\", \"server\", \"start\", \"--host\", \"0.0.0.0\"]\n```\n\n### Systemd Service\n\n```ini\n# /etc/systemd/system/claude-worker.service\n[Unit]\nDescription=Claude Worker Server\nAfter=network.target\n\n[Service]\nType=exec\nUser=claude\nWorkingDirectory=/opt/claude-worker\nEnvironment=\"ANTHROPIC_API_KEY=your-key-here\"\nExecStart=/usr/local/bin/claude-worker server start --host 0.0.0.0\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n```\n\n> \ud83d\udcd6 **For comprehensive deployment guides:** See [Deployment Guide](docs/05-administration-deployment.md)\n\n## \ud83c\udfd7\ufe0f Architecture Principles\n\n- **\ud83c\udfaf SOLE Responsibility**: Each module has Single, Overarching, Lucidly-stated Expertise\n- **\ud83d\udd12 Process Isolation**: Every task runs in its own process for safety\n- **\ud83d\udcbe Fail-Safe**: SQLite persistence ensures no work is lost\n- **\ud83d\udd27 Extensible**: Clear interfaces for adding new features\n\n> \ud83d\udcd6 **Learn more about the design:** See [Project Philosophy](docs/03-concepts-project-philosophy.md) and [Architecture Overview](docs/03-concepts-architecture.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fire-and-forget task execution system for Claude Code SDK with CLI and MCP interfaces",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/yigitkonur/claude-worker/issues",
"Changelog": "https://github.com/yigitkonur/claude-worker/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/yigitkonur/claude-worker/blob/main/README.md",
"Homepage": "https://github.com/yigitkonur/claude-worker",
"MCP Documentation": "https://github.com/yigitkonur/claude-worker/blob/main/MCP_README.md",
"Repository": "https://github.com/yigitkonur/claude-worker"
},
"split_keywords": [
"claude",
" ai",
" automation",
" task-queue",
" cli",
" mcp",
" anthropic"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0ebd67a51e285b294fafe5a6cf823e9401651ddd42120fa08b4e2a5109db155f",
"md5": "85af036296198090ede4bccc52136519",
"sha256": "a75f94d253fa39c2542b3f3ae076832a87899c6c7567789f398dafd943064541"
},
"downloads": -1,
"filename": "claude_worker-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85af036296198090ede4bccc52136519",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 33706,
"upload_time": "2025-08-11T09:33:28",
"upload_time_iso_8601": "2025-08-11T09:33:28.239399Z",
"url": "https://files.pythonhosted.org/packages/0e/bd/67a51e285b294fafe5a6cf823e9401651ddd42120fa08b4e2a5109db155f/claude_worker-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "509bad761dd01c047ee0429eab603d52d1e5c08e1d9fab9e20c91e56a5441af1",
"md5": "7a537df3eaa7da22dac97c8bc7ff216a",
"sha256": "f19b39083db719530f1ae9d8e73907a2eba8c99ada5d338373d680673a63956b"
},
"downloads": -1,
"filename": "claude_worker-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7a537df3eaa7da22dac97c8bc7ff216a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 29939,
"upload_time": "2025-08-11T09:33:29",
"upload_time_iso_8601": "2025-08-11T09:33:29.100785Z",
"url": "https://files.pythonhosted.org/packages/50/9b/ad761dd01c047ee0429eab603d52d1e5c08e1d9fab9e20c91e56a5441af1/claude_worker-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 09:33:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yigitkonur",
"github_project": "claude-worker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-worker"
}
JSON
