Dual-AI orchestration CLI that coordinates Instructor and Worker Claude instances
npm install @k-l-lambda/claude-masterA dual-AI orchestration CLI that coordinates two Claude instances to complete software engineering tasks:
- Instructor: The architect and project organizer
- Worker: The implementation executor
- ๐ง Intelligent Task Decomposition: Instructor breaks down complex tasks into manageable steps
- ๐ Continuous Session: Complete multiple tasks without restarting
- ๐ฏ Model Selection: Instructor dynamically chooses the best model for each task
- โธ๏ธ Interactive Control: Pause anytime with ESC to guide the process
- ๐ Full Visibility: Watch both AIs collaborate in real-time with color-coded output
Option 1: Install from npm (Recommended)
``bashInstall globally - no authentication required!
npm install -g @k-l-lambda/claude-master
After installation, you can use
claude-master from anywhere:
`bash
Set up your API key
export ANTHROPIC_AUTH_TOKEN="your-key"Run from any directory
cd ./my-project
claude-master "Do this task described in README.md"
`Option 2: Install from Source (Development)
`bash
Clone the repository
git clone https://github.com/k-l-lambda/claude-master.git
cd claude-masterInstall dependencies and build
npm install
npm run buildInstall globally (creates 'claude-master' command)
npm linkOr on Windows:
npm install -g .
`Option 3: Local Development
`bash
Install dependencies
npm install
npm run buildRun locally with npm
npm start "Do this task described in README.md" -d ./my-projectOr use the dev command (with auto-reload)
npm run dev "Your task" -d ./my-project
`$3
`bash
If installed from npm
npm uninstall -g @k-l-lambda/claude-masterIf installed from source with npm link
npm unlink -g claude-master
`$3
Option 1: Environment Variable (Global)
`bash
Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"
export ANTHROPIC_BASE_URL="https://api.anthropic.com" # optional
`Option 2: .env.local File (Per Project)
`bash
In your project directory
echo "ANTHROPIC_AUTH_TOKEN=your-key" > .env.local
echo "ANTHROPIC_BASE_URL=https://api.anthropic.com" >> .env.local
`Option 3: CLI Arguments
`bash
claude-master "task" -k your-key -u https://api.anthropic.com
`$3
`bash
Verify installation
./verify-installation.shTest with the simple calculator example
claude-master "Read README.md to understand your task" \
-d tests/cases/simple-calculator \
--no-thinking
`๐ Key Features
$3
The system stays active after completing a task, ready for your next instruction:
`bash
Start with an initial task
npm start "Read README.md to understand your task" -d ./my-projectAfter completion:
โ Instructor has completed the current task
๐ฌ Instructor is waiting for your next instruction...
Your instruction: Add error handling to all API endpoints
Continue working in the same context!
`$3
Instructor can choose the right model for each subtask:
- Sonnet (default) - Balanced for most tasks
- Opus - Complex architecture and algorithms
- Haiku - Quick commands and simple tasks$3
Press ESC during execution to:
- Give new directions
- Clarify requirements
- Add constraints
- Resume or exit๐ How It Works
$3
Instructor (Project Organizer)
- Reads and understands task requirements
- Plans project architecture
- Breaks down complex tasks
- Chooses appropriate Worker model
- Reviews Worker's output
- Makes decisions
Tools: File operations, Git commands
Worker (Implementation Executor)
- Executes specific instructions
- Writes and modifies code
- Runs commands (npm, build, test)
- Searches the web for documentation
- Reports results back
Tools: File operations, Bash commands, Web search
$3
`
User โ Instructor (with task)
โ
[Thinks deeply about approach]
โ
Tell worker (use sonnet): Create project structure
โ
Worker โ [Executes task]
โ
Worker says: [Result]
โ
Instructor โ Reviews and continues or says DONE
`๐ฎ Usage
$3
`bash
If installed globally
claude-master [instruction] [options]If running locally
npm start [instruction] [options]
or
npm run dev [instruction] [options]
`$3
1. Put task details in README.md (recommended)
2. Run with initial instruction:
`bash
Global installation
claude-master "Read README.md to get aware your task" -d ./your-projectLocal installation
npm start "Read README.md to get aware your task" -d ./your-project
`$3
Instructor communicates with Worker using:
`bash
Simple format
Tell worker: [instruction]With model selection
Tell worker (use opus): [complex instruction]
Tell worker (model: haiku): [quick command]Task completion
DONE
`$3
-
sonnet - Claude Sonnet 4.5 (default, balanced)
- opus - Claude Opus 4 (most capable, for complex tasks)
- haiku - Claude 3.5 Haiku (fastest, for simple tasks)๐ ๏ธ Configuration
$3
`bash
Create .env.local file
ANTHROPIC_AUTH_TOKEN=your-api-key-here
ANTHROPIC_BASE_URL=https://api.anthropic.com # optional
`$3
`bash
export ANTHROPIC_AUTH_TOKEN="your-key"
`$3
`bash
npm start "task" -k your-key -u https://api.anthropic.com
`๐ CLI Options
`bash
Global installation
claude-master [options]Local installation
npm start [options]
`Arguments:
-
- Initial instruction for Instructor (optional, can be provided interactively)Options:
-
-V, --version - Output the version number
- -d, --work-dir - Working directory (default: current)
- -r, --max-rounds - Maximum conversation rounds
- -i, --instructor-model - Instructor model
- -w, --worker-model - Worker default model
- -k, --api-key - Anthropic API key
- -u, --base-url - API base URL
- --no-thinking - Disable thinking display
- -h, --help - Display help๐ฏ Example Use Cases
$3
`bash
Global
claude-master "Read README.md to understand your task" \
-d tests/cases/simple-calculator \
--no-thinkingLocal
npm start "Read README.md to understand your task" \
-d tests/cases/simple-calculator \
--no-thinking
`$3
`bash
Global
claude-master "Read README.md to understand your task" \
-d tests/cases/easy-todo-list \
--no-thinkingLocal
npm start "Read README.md to understand your task" \
-d tests/cases/easy-todo-list \
--no-thinking
`$3
`bash
claude-master "Read README.md to understand your task" \
-d tests/cases/api-client-library \
--no-thinking
`$3
`bash
claude-master "Read README.md to understand your task" \
-d tests/cases/expense-tracker \
--no-thinking
`$3
`bash
claude-master "Read README.md to understand your task" \
-d tests/cases/blog-cms-backend \
--no-thinking
`$3
`bash
Navigate to your project
cd ~/my-awesome-projectRun claude-master
claude-master "Read README.md and help me implement the authentication system"
`๐งช Test Cases
We provide several test cases to evaluate the system's capabilities:
| Test Case | Difficulty | Focus | Rounds |
|-----------|-----------|-------|--------|
| Simple Calculator | Easy | TDD basics | 5-10 |
| Todo List CLI | Easy | Project structure | 5-10 |
| API Client Library | Medium | Library design | 10-15 |
| Expense Tracker | Medium-Hard | Layered architecture | 15-25 |
| Blog CMS Backend | Hard | Production system | 25-40+ |
See tests/cases/README.md for details.
๐จ Console Output
Color-coded for easy tracking:
- Blue - Instructor's responses
- Green - Worker's responses
- Gray - Thinking process
- Yellow - System messages
๐ง Development
$3
`bash
Clone and install
git clone https://github.com/yourusername/claude-master.git
cd claude-master
npm install
`$3
`bash
Development mode with auto-reload (tsx)
npm run dev "Your task" -d ./projectBuild TypeScript to JavaScript
npm run buildRun built version
npm start "Your task" -d ./projectLink for global testing
npm run linkUnlink global installation
npm run unlink
`$3
`bash
Update version
npm version patch # or minor, or majorBuild and publish
npm publish
`๐ Documentation
- Communication Protocol - Detailed communication formats
- Continuous Session - Session management (ไธญๆ)
- Test Cases Guide - All available test cases
- Architecture - System architecture (ไธญๆ)
๐ Worker Tools
$3
- read_file - Read file contents with optional offset/limit
- write_file - Create new files
- edit_file - Edit existing files (replace text)
- glob_files - Find files by glob pattern
- grep_search - Search code with regex$3
- bash_command - Execute safe bash commands (git blocked)$3
- web_search - Search the internet for information๐ก Tips
1. Start Simple: Use test cases to understand the system
2. Use README.md: Put task details in README for better context
3. Watch Thinking: Don't use
--no-thinking initially to see planning
4. Press ESC: Interrupt anytime to provide guidance
5. Continuous Mode: After "DONE", provide next instruction to continue
6. Model Selection: Let Instructor choose models, or guide when needed๐ Troubleshooting
$3
- Normal when running in background mode or when session ends
- Not an error in interactive mode$3
- Set proxy: export https_proxy=http://localhost:1091
- Web search uses curl, requires network access$3
- Ensure working directory is correct: -d path/to/tests
- Check file exists: ls tests/cases/simple-calculator/README.md๐ Project Structure
`
claude-master/
โโโ src/ # Source code
โ โโโ index.ts # CLI entry point
โ โโโ orchestrator.ts # Main coordination logic
โ โโโ instructor.ts # Instructor agent
โ โโโ worker.ts # Worker agent
โ โโโ client.ts # Claude API client
โ โโโ tools.ts # Tool definitions
โ โโโ tool-executor.ts # Tool implementations
โ โโโ display.ts # Console output formatting
โโโ tests/
โ โโโ cases/ # Test cases for evaluation
โโโ docs/ # Documentation
โโโ dist/ # Built files
``This is a personal project for orchestrating dual-AI collaboration. Feel free to fork and adapt to your needs!
ISC
---
Made with โค๏ธ to explore multi-agent AI collaboration