Claude Master

A dual-AI orchestration CLI that coordinates two Claude instances to complete software engineering tasks:
- Instructor: The architect and project organizer
- Worker: The implementation executor

✨ What Makes This Special

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

🚀 Quick Start

$3

Option 1: Install from npm (Recommended)

``bash


Install globally - no authentication required!

npm install -g @k-l-lambda/claude-master

Verify installation

claude-master --version
`

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

Install dependencies and build

npm install
npm run build

Install globally (creates 'claude-master' command)

npm link

Or on Windows:

npm install -g .
`

Option 3: Local Development
`bash


Install dependencies

npm install
npm run build

Run locally with npm

npm start "Do this task described in README.md" -d ./my-project

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

If 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.sh

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

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

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

Local

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

Local

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

Run 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 ./project

Build TypeScript to JavaScript

npm run build

Run built version

npm start "Your task" -d ./project

Link for global testing

npm run link

Unlink global installation

npm run unlink
`

$3

`bash

Update version

npm version patch # or minor, or major

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

🤝 Contributing

This is a personal project for orchestrating dual-AI collaboration. Feel free to fork and adapt to your needs!

📜 License

ISC

---

Made with ❤️ to explore multi-agent AI collaboration