@k-l-lambda/claude-master

v2.0.3

Published

a month ago

Dual-AI orchestration CLI that coordinates Instructor and Worker Claude instances

0High
0Medium
0Low

k-l-lambda

claude ai cli agentic-ai orchestration instructor-worker

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

Installation

Option 1: Install from npm (Recommended)

# 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:

# 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)

# 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

# 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

Uninstall

# If installed from npm
npm uninstall -g @k-l-lambda/claude-master

# If installed from source with npm link
npm unlink -g claude-master

Configuration

Option 1: Environment Variable (Global)

# 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)

# 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

claude-master "task" -k your-key -u https://api.anthropic.com

Quick Test

# 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

Continuous Session Mode

The system stays active after completing a task, ready for your next instruction:

# 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!

Dynamic Model Selection

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

Interactive Pause (ESC)

Press ESC during execution to:

Give new directions
Clarify requirements
Add constraints
Resume or exit

📖 How It Works

The Two Agents

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

Communication Flow

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

Command Format

# If installed globally
claude-master [instruction] [options]

# If running locally
npm start [instruction] [options]
# or
npm run dev [instruction] [options]

Basic Pattern

Put task details in README.md (recommended)
Run with initial instruction:

# 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

Communication Formats

Instructor communicates with Worker using:

# Simple format
Tell worker: [instruction]

# With model selection
Tell worker (use opus): [complex instruction]
Tell worker (model: haiku): [quick command]

# Task completion
**DONE**

Available Models

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

Option 1: .env.local (Recommended)

# Create .env.local file
ANTHROPIC_AUTH_TOKEN=your-api-key-here
ANTHROPIC_BASE_URL=https://api.anthropic.com  # optional

Option 2: Environment Variables

export ANTHROPIC_AUTH_TOKEN="your-key"

Option 3: CLI Arguments

npm start "task" -k your-key -u https://api.anthropic.com

📝 CLI Options

# Global installation
claude-master <instruction> [options]

# Local installation
npm start <instruction> [options]

Arguments:

<instruction> - Initial instruction for Instructor (optional, can be provided interactively)

Options:

-V, --version - Output the version number
-d, --work-dir <path> - Working directory (default: current)
-r, --max-rounds <number> - Maximum conversation rounds
-i, --instructor-model <model> - Instructor model
-w, --worker-model <model> - Worker default model
-k, --api-key <key> - Anthropic API key
-u, --base-url <url> - API base URL
--no-thinking - Disable thinking display
-h, --help - Display help

🎯 Example Use Cases

1. Simple Calculator (TDD)

# 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

2. Todo List Application

# 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. HTTP API Client Library

claude-master "Read README.md to understand your task" \
  -d tests/cases/api-client-library \
  --no-thinking

4. Expense Tracker (Advanced)

claude-master "Read README.md to understand your task" \
  -d tests/cases/expense-tracker \
  --no-thinking

5. Blog CMS Backend (Complex)

claude-master "Read README.md to understand your task" \
  -d tests/cases/blog-cms-backend \
  --no-thinking

6. Use with Any Project

# 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

Setup for Development

# Clone and install
git clone https://github.com/yourusername/claude-master.git
cd claude-master
npm install

Development Commands

# 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

Publishing (for maintainers)

# 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

File Operations

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

Execution

bash_command - Execute safe bash commands (git blocked)

Research

web_search - Search the internet for information

💡 Tips

Start Simple: Use test cases to understand the system
Use README.md: Put task details in README for better context
Watch Thinking: Don't use --no-thinking initially to see planning
Press ESC: Interrupt anytime to provide guidance
Continuous Mode: After "DONE", provide next instruction to continue
Model Selection: Let Instructor choose models, or guide when needed

🐛 Troubleshooting

"readline was closed"

Normal when running in background mode or when session ends
Not an error in interactive mode

Network Issues with Web Search

Set proxy: export https_proxy=http://localhost:1091
Web search uses curl, requires network access

Tests Not Found

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