{"id":44975959,"url":"https://github.com/k-l-lambda/claude-master","last_synced_at":"2026-02-18T17:04:53.359Z","repository":{"id":322768519,"uuid":"1090191110","full_name":"k-l-lambda/claude-master","owner":"k-l-lambda","description":"Dual-AI orchestration CLI that coordinates Instructor and Worker Claude instances","archived":false,"fork":false,"pushed_at":"2025-11-06T08:35:16.000Z","size":3443,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-06T09:05:09.074Z","etag":null,"topics":["agentic-ai"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-l-lambda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-05T10:41:25.000Z","updated_at":"2025-11-06T08:35:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k-l-lambda/claude-master","commit_stats":null,"previous_names":["k-l-lambda/claude-master"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/k-l-lambda/claude-master","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Fclaude-master","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Fclaude-master/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Fclaude-master/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Fclaude-master/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-l-lambda","download_url":"https://codeload.github.com/k-l-lambda/claude-master/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Fclaude-master/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29587066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T16:55:40.614Z","status":"ssl_error","status_checked_at":"2026-02-18T16:55:37.558Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agentic-ai"],"created_at":"2026-02-18T17:04:43.885Z","updated_at":"2026-02-18T17:04:53.341Z","avatar_url":"https://github.com/k-l-lambda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Master\n\nA dual-AI orchestration CLI that coordinates two Claude instances to complete software engineering tasks:\n- **Instructor**: The architect and project organizer\n- **Worker**: The implementation executor\n\n## ✨ What Makes This Special\n\n- 🧠 **Intelligent Task Decomposition**: Instructor breaks down complex tasks into manageable steps\n- 🔄 **Continuous Session**: Complete multiple tasks without restarting\n- 🎯 **Model Selection**: Instructor dynamically chooses the best model for each task\n- ⏸️ **Interactive Control**: Pause anytime with ESC to guide the process\n- 🔍 **Full Visibility**: Watch both AIs collaborate in real-time with color-coded output\n\n## 🚀 Quick Start\n\n### Installation\n\n**Option 1: Install from npm (Recommended)**\n\n```bash\n# Install globally - no authentication required!\nnpm install -g @k-l-lambda/claude-master\n\n# Verify installation\nclaude-master --version\n```\n\nAfter installation, you can use `claude-master` from anywhere:\n```bash\n# Set up your API key\nexport ANTHROPIC_AUTH_TOKEN=\"your-key\"\n\n# Run from any directory\ncd ./my-project\nclaude-master \"Do this task described in README.md\"\n```\n\n**Option 2: Install from Source (Development)**\n```bash\n# Clone the repository\ngit clone https://github.com/k-l-lambda/claude-master.git\ncd claude-master\n\n# Install dependencies and build\nnpm install\nnpm run build\n\n# Install globally (creates 'claude-master' command)\nnpm link\n\n# Or on Windows:\nnpm install -g .\n```\n\n**Option 3: Local Development**\n```bash\n# Install dependencies\nnpm install\nnpm run build\n\n# Run locally with npm\nnpm start \"Do this task described in README.md\" -d ./my-project\n\n# Or use the dev command (with auto-reload)\nnpm run dev \"Your task\" -d ./my-project\n```\n\n### Uninstall\n\n```bash\n# If installed from npm\nnpm uninstall -g @k-l-lambda/claude-master\n\n# If installed from source with npm link\nnpm unlink -g claude-master\n```\n\n### Configuration\n\n**Option 1: Environment Variable (Global)**\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nexport ANTHROPIC_AUTH_TOKEN=\"your-api-key-here\"\nexport ANTHROPIC_BASE_URL=\"https://api.anthropic.com\"  # optional\n```\n\n**Option 2: .env.local File (Per Project)**\n```bash\n# In your project directory\necho \"ANTHROPIC_AUTH_TOKEN=your-key\" \u003e .env.local\necho \"ANTHROPIC_BASE_URL=https://api.anthropic.com\" \u003e\u003e .env.local\n```\n\n**Option 3: CLI Arguments**\n```bash\nclaude-master \"task\" -k your-key -u https://api.anthropic.com\n```\n\n### Quick Test\n\n```bash\n# Verify installation\n./verify-installation.sh\n\n# Test with the simple calculator example\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/simple-calculator \\\n  --no-thinking\n```\n\n## 📋 Key Features\n\n### Continuous Session Mode\nThe system stays active after completing a task, ready for your next instruction:\n```bash\n# Start with an initial task\nnpm start \"Read README.md to understand your task\" -d ./my-project\n\n# After completion:\n✓ Instructor has completed the current task\n💬 Instructor is waiting for your next instruction...\nYour instruction: Add error handling to all API endpoints\n# Continue working in the same context!\n```\n\n### Dynamic Model Selection\nInstructor can choose the right model for each subtask:\n- **Sonnet** (default) - Balanced for most tasks\n- **Opus** - Complex architecture and algorithms\n- **Haiku** - Quick commands and simple tasks\n\n### Interactive Pause (ESC)\nPress ESC during execution to:\n- Give new directions\n- Clarify requirements\n- Add constraints\n- Resume or exit\n\n## 📖 How It Works\n\n### The Two Agents\n\n**Instructor (Project Organizer)**\n- Reads and understands task requirements\n- Plans project architecture\n- Breaks down complex tasks\n- Chooses appropriate Worker model\n- Reviews Worker's output\n- Makes decisions\n- Manages Worker's context and permissions\n\nTools: File operations, Git commands, Worker management (call_worker, tell_worker, etc.)\n\n**Worker (Implementation Executor)**\n- Executes specific instructions from Instructor\n- Writes and modifies code\n- Runs commands (npm, build, test)\n- Searches the web for documentation\n- Uses read-only git commands\n- Reports results back to Instructor\n\nTools: File operations, Bash commands, Web search, Git status (read-only)\n\n### Communication Flow\n\n```\nUser → Instructor (with task)\n         ↓\n   [Thinks deeply about approach]\n         ↓\n   call_worker(system_prompt, instruction, model='sonnet')\n         ↓\n      Worker → [Executes task with tools]\n         ↓\n   [Worker returns result]\n         ↓\n   Instructor → Reviews and continues or says DONE\n```\n\n## 🎮 Usage\n\n### Command Format\n\n```bash\n# If installed globally\nclaude-master [instruction] [options]\n\n# If running locally\nnpm start [instruction] [options]\n# or\nnpm run dev [instruction] [options]\n```\n\n### Basic Pattern\n\n1. **Put task details in README.md** (recommended)\n2. **Run with initial instruction**:\n```bash\n# Global installation\nclaude-master \"Read README.md to get aware your task\" -d ./your-project\n\n# Local installation\nnpm start \"Read README.md to get aware your task\" -d ./your-project\n```\n\n### Communication Formats\n\nInstructor communicates with Worker using tool calls:\n\n**Three Worker Tools Available:**\n\n1. **call_worker** - Reset Worker's context with new system prompt\n   ```typescript\n   call_worker({\n     system_prompt: \"You are a backend developer...\",\n     instruction: \"Implement user authentication\",\n     model: \"sonnet\"  // optional: opus, sonnet, haiku\n   })\n   ```\n\n2. **call_worker_with_file** - Load system prompt from file\n   ```typescript\n   call_worker_with_file({\n     system_prompt_file: \"path/to/prompt.txt\",\n     instruction: \"Implement the feature\",\n     model: \"haiku\"\n   })\n   ```\n\n3. **tell_worker** - Continue existing conversation\n   ```typescript\n   tell_worker({\n     message: \"Add error handling to the code\",\n     model: \"sonnet\"  // optional\n   })\n   ```\n\n**Task Completion:**\nWhen task is complete, Instructor responds with \"DONE\".\n\n### Available Models\n\n- `sonnet` - Claude Sonnet 4.5 (default, balanced)\n- `opus` - Claude Opus 4 (most capable, for complex tasks)\n- `haiku` - Claude 3.5 Haiku (fastest, for simple tasks)\n\n## 🛠️ Configuration\n\n### Option 1: .env.local (Recommended)\n```bash\n# Create .env.local file\nANTHROPIC_AUTH_TOKEN=your-api-key-here\nANTHROPIC_BASE_URL=https://api.anthropic.com  # optional\n```\n\n### Option 2: Environment Variables\n```bash\nexport ANTHROPIC_AUTH_TOKEN=\"your-key\"\n```\n\n### Option 3: CLI Arguments\n```bash\nnpm start \"task\" -k your-key -u https://api.anthropic.com\n```\n\n## 📝 CLI Options\n\n```bash\n# Global installation\nclaude-master \u003cinstruction\u003e [options]\n\n# Local installation\nnpm start \u003cinstruction\u003e [options]\n```\n\n**Arguments:**\n- `\u003cinstruction\u003e` - Initial instruction for Instructor (optional, can be provided interactively)\n\n**Options:**\n- `-V, --version` - Output the version number\n- `-d, --work-dir \u003cpath\u003e` - Working directory (default: current)\n- `-r, --max-rounds \u003cnumber\u003e` - Maximum conversation rounds\n- `-i, --instructor-model \u003cmodel\u003e` - Instructor model\n- `-w, --worker-model \u003cmodel\u003e` - Worker default model\n- `-k, --api-key \u003ckey\u003e` - Anthropic API key\n- `-u, --base-url \u003curl\u003e` - API base URL\n- `--no-thinking` - Disable thinking display\n- `-h, --help` - Display help\n\n## 🎯 Example Use Cases\n\n### 1. Simple Calculator (TDD)\n```bash\n# Global\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/simple-calculator \\\n  --no-thinking\n\n# Local\nnpm start \"Read README.md to understand your task\" \\\n  -d tests/cases/simple-calculator \\\n  --no-thinking\n```\n\n### 2. Todo List Application\n```bash\n# Global\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/easy-todo-list \\\n  --no-thinking\n\n# Local\nnpm start \"Read README.md to understand your task\" \\\n  -d tests/cases/easy-todo-list \\\n  --no-thinking\n```\n\n### 3. HTTP API Client Library\n```bash\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/api-client-library \\\n  --no-thinking\n```\n\n### 4. Expense Tracker (Advanced)\n```bash\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/expense-tracker \\\n  --no-thinking\n```\n\n### 5. Blog CMS Backend (Complex)\n```bash\nclaude-master \"Read README.md to understand your task\" \\\n  -d tests/cases/blog-cms-backend \\\n  --no-thinking\n```\n\n### 6. Use with Any Project\n```bash\n# Navigate to your project\ncd ~/my-awesome-project\n\n# Run claude-master\nclaude-master \"Read README.md and help me implement the authentication system\"\n```\n\n## 🧪 Test Cases\n\nWe provide several test cases to evaluate the system's capabilities:\n\n| Test Case | Difficulty | Focus | Rounds |\n|-----------|-----------|-------|--------|\n| Simple Calculator | Easy | TDD basics | 5-10 |\n| Todo List CLI | Easy | Project structure | 5-10 |\n| API Client Library | Medium | Library design | 10-15 |\n| Expense Tracker | Medium-Hard | Layered architecture | 15-25 |\n| Blog CMS Backend | Hard | Production system | 25-40+ |\n\nSee [tests/cases/README.md](tests/cases/README.md) for details.\n\n## 🎨 Console Output\n\nColor-coded for easy tracking:\n- **Blue** - Instructor's responses\n- **Green** - Worker's responses\n- **Gray** - Thinking process\n- **Yellow** - System messages\n\n## 🔧 Development\n\n### Setup for Development\n```bash\n# Clone and install\ngit clone https://github.com/yourusername/claude-master.git\ncd claude-master\nnpm install\n```\n\n### Development Commands\n```bash\n# Development mode with auto-reload (tsx)\nnpm run dev \"Your task\" -d ./project\n\n# Build TypeScript to JavaScript\nnpm run build\n\n# Run built version\nnpm start \"Your task\" -d ./project\n\n# Link for global testing\nnpm run link\n\n# Unlink global installation\nnpm run unlink\n```\n\n### Publishing (for maintainers)\n```bash\n# Update version\nnpm version patch  # or minor, or major\n\n# Build and publish\nnpm publish\n```\n\n## 📚 Documentation\n\n- [Communication Protocol](docs/COMMUNICATION_PROTOCOL.md) - Detailed communication formats\n- [Continuous Session](docs/CONTINUOUS_SESSION.md) - Session management (中文)\n- [Test Cases Guide](tests/cases/README.md) - All available test cases\n- [Architecture](docs/ARCHITECTURE.md) - System architecture (中文)\n\n## 🔧 Instructor Tools\n\n### Worker Management\n- `call_worker` - Reset Worker with new system prompt and instruction\n- `call_worker_with_file` - Reset Worker with system prompt from file\n- `tell_worker` - Continue Worker's existing conversation\n- `set_worker_timeout` - Adjust Worker's inactivity timeout (30-600s)\n- `grant_worker_permission` - Grant Worker access to restricted tools\n- `revoke_worker_permission` - Revoke Worker's tool permissions\n\n### File Operations\n- `read_file` - Read file contents\n- `write_file` - Create/overwrite files\n- `edit_file` - Edit existing files (replace text)\n- `glob_files` - Find files by glob pattern\n- `grep_search` - Search code with regex\n\n### Git Operations\n- `git_status` - Read-only git commands (status, log, diff, etc.)\n- `git_command` - Write git commands (commit, push, etc.)\n\n### Execution\n- `bash_command` - Execute bash commands\n\n## 🔍 Worker Tools\n\n### File Operations\n- `read_file` - Read file contents with optional offset/limit\n- `write_file` - Create/overwrite files\n- `edit_file` - Edit existing files (replace text)\n- `glob_files` - Find files by glob pattern\n- `grep_search` - Search code with regex\n\n### Git Operations (Read-only)\n- `git_status` - Read-only git commands (status, log, diff, show, etc.)\n\n### Execution\n- `bash_command` - Execute safe bash commands (non-destructive)\n\n### Research\n- `web_search` - Search the internet for information\n\n## 💡 Tips\n\n1. **Start Simple**: Use test cases to understand the system\n2. **Use README.md**: Put task details in README for better context\n3. **Watch Thinking**: Don't use `--no-thinking` initially to see planning\n4. **Press ESC**: Interrupt anytime to provide guidance\n5. **Continuous Mode**: After \"DONE\", provide next instruction to continue\n6. **Model Selection**: Let Instructor choose models, or guide when needed\n\n## 🐛 Troubleshooting\n\n### \"readline was closed\"\n- Normal when running in background mode or when session ends\n- Not an error in interactive mode\n\n### Network Issues with Web Search\n- Set proxy: `export https_proxy=http://localhost:1091`\n- Web search uses curl, requires network access\n\n### Tests Not Found\n- Ensure working directory is correct: `-d path/to/tests`\n- Check file exists: `ls tests/cases/simple-calculator/README.md`\n\n## 📄 Project Structure\n\n```\nclaude-master/\n├── src/                    # Source code\n│   ├── index.ts           # CLI entry point\n│   ├── orchestrator.ts    # Main coordination logic\n│   ├── instructor.ts      # Instructor agent\n│   ├── worker.ts          # Worker agent\n│   ├── client.ts          # Claude API client\n│   ├── tools.ts           # Tool definitions\n│   ├── tool-executor.ts   # Tool implementations\n│   └── display.ts         # Console output formatting\n├── tests/\n│   └── cases/             # Test cases for evaluation\n├── docs/                  # Documentation\n└── dist/                  # Built files\n```\n\n## 🤝 Contributing\n\nThis is a personal project for orchestrating dual-AI collaboration. Feel free to fork and adapt to your needs!\n\n## 📜 License\n\nISC\n\n---\n\n**Made with ❤️ to explore multi-agent AI collaboration**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-l-lambda%2Fclaude-master","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-l-lambda%2Fclaude-master","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-l-lambda%2Fclaude-master/lists"}