Claude Orchestrator

THIS IS NOT OFFICIAL CLAUDE CODE TOOL

Stop developing. Let Claude Code handle everything.

Features

• 4-Agent Pipeline: Coordinate Planner, Designer, Tech Lead, and Developer agents
• Design Token Verification: Automatically compare design specifications with implementation
• Project Management: Initialize and manage development projects
• Task Queue: Automatic task discovery, assignment, and tracking
• Progress Monitoring: Real-time status updates and logging
• Checkpoint Recovery: Stop and resume workflows at any point
• Figma Integration (Optional): Extract design tokens from Figma files

Prerequisites

• Node.js >= 18.0.0
• Claude Code CLI installed and authenticated

Installation

# Install globally
npm install -g @graygate/claude-orchestrator

# Or run directly with npx
npx @graygate/claude-orchestrator

Quick Start

1. Initialize a Project

cd your-project
claude-orchestrator init

2. Start Development

claude-orchestrator start --scope "Implement user authentication" --goals "Login,Register,Password Reset"

3. Monitor Progress

# View current status
claude-orchestrator status

# Watch logs
claude-orchestrator logs --follow

4-Agent Pipeline

Claude Orchestrator uses a sophisticated 4-agent pipeline to handle development tasks:

┌─────────────────────────────────┐
│ 1. DISCOVERY                    │
│    - Scan project structure     │
│    - Identify tasks             │
│    - Create tasks in queue      │
└───────────────┬─────────────────┘
                ▼
┌─────────────────────────────────┐
│ 2. PLANNER                      │
│    - Define product vision      │
│    - Break down features        │
│    - Design user flows          │
│    - Document requirements      │
└───────────────┬─────────────────┘
                ▼
┌─────────────────────────────────┐
│ 3. DESIGNER                     │
│    - Create design tokens       │
│    - Define color, typography   │
│    - Specify component styles   │
│    - (Optional) Figma sync      │
└───────────────┬─────────────────┘
                ▼
┌─────────────────────────────────┐
│ 4. TECH LEAD                    │
│    - Analyze planning docs      │
│    - Review design specs        │
│    - Write implementation guide │
│    - Define architecture        │
└───────────────┬─────────────────┘
                ▼
┌─────────────────────────────────┐
│ 5. DEVELOPER                    │
│    - Read instructions          │
│    - Implement features         │
│    - Apply design tokens        │
│    - Run build verification     │
└───────────────┬─────────────────┘
                ▼
┌─────────────────────────────────┐
│ 6. REVIEW & VERIFICATION        │
│    - Tech Lead reviews code     │
│    - Compare design tokens      │
│    - Report discrepancies       │
│    - Log completion             │
└─────────────────────────────────┘

Commands

claude-orchestrator init

Initialize the orchestrator in a project directory.

claude-orchestrator init [directory]

Options:

• [directory] - Target project directory (default: current directory)

claude-orchestrator start

Start the orchestration process.

claude-orchestrator start [options]

Options:

• --scope <scope> - Development scope description
• --goals <goals> - Comma-separated development goals
• --max-tasks <n> - Maximum tasks per cycle (default: 10)
• --platform <platform> - Target platform (android, ios, web, custom)
• --continuous - Enable continuous discovery and implementation
• --dry-run - Preview without execution

claude-orchestrator status

Show current orchestration status.

claude-orchestrator status

Displays:

• Active agents (Planner, Designer, Tech Lead, Developer)
• Current task being processed
• Queue statistics
• Recent activity

claude-orchestrator logs

View development logs.

claude-orchestrator logs [options]

Options:

• --tail <n> - Show last n entries
• --follow - Stream new log entries in real-time
• --task <id> - Filter logs by task ID

claude-orchestrator stop

Stop running agents gracefully.

claude-orchestrator stop

claude-orchestrator resume

Resume from the last checkpoint.

claude-orchestrator resume

Interactive Mode

During orchestration, you can use these keyboard shortcuts:

| Key | Action | |-----|--------| | l | Show recent log entries | | s | Show current status | | p | Pause after current task | | q | Stop gracefully | | r | Resume paused work |

Configuration

The orchestrator creates a .claude-orchestrator/ directory in your project with:

.claude-orchestrator/
├── config.json           # Project configuration
├── status.json           # Current agent status
├── queue.json            # Task queue
├── messages/             # Inter-agent communication
│   ├── to-designer.json  # Planner → Designer
│   ├── to-tech-lead.json # Designer → Tech Lead
│   └── to-developer.json # Tech Lead → Developer
├── design/               # Design artifacts
│   ├── tokens.json       # Design tokens
│   └── verification-report.json
└── logs/
    └── log.md            # Development log

config.json

{
  "project": {
    "name": "your-project",
    "path": "/absolute/path/to/project"
  },
  "scope": "Development scope description",
  "goals": ["goal1", "goal2"],
  "platform": "web",
  "maxTasks": 10,
  "continuous": false,
  "figma": {
    "enabled": false,
    "fileKey": "optional-figma-file-key",
    "accessToken": "optional-figma-access-token"
  }
}

Design Token Verification

The Designer agent creates design tokens that are verified against the implementation:

Design Tokens Structure

{
  "colors": {
    "primary": "#1E88E5",
    "secondary": "#FF5722",
    "background": "#FFFFFF"
  },
  "fonts": {
    "heading": {
      "family": "Inter",
      "size": "24px",
      "weight": "700"
    }
  },
  "spacing": {
    "sm": "8px",
    "md": "16px",
    "lg": "24px"
  }
}

Verification Process

1. Designer creates design specification with tokens
2. Developer implements using the tokens
3. After implementation, CSS tokens are extracted from the code
4. Tokens are compared with tolerance levels
5. Discrepancies are reported (warnings only, won't block completion)

Task States

Tasks move through these states:

pending → in_progress → awaiting_review → completed
                    ↓
                 rejected

Development

Build from Source

# Clone the repository
git clone https://github.com/graygate/claude-orchestrator.git
cd claude-orchestrator

# Install dependencies
npm install

# Build
npm run build

# Run locally
node bin/cli.js

Run Tests

npm test

Troubleshooting

Claude Code Not Found

If you see "Claude Code CLI not found", install it with:

npm install -g @anthropic-ai/claude-code

Authentication Required

If Claude Code is not authenticated, run:

claude login

Task Stuck

If a task appears stuck:

1. Check status: claude-orchestrator status
2. View logs: claude-orchestrator logs --tail 50
3. Stop and resume: claude-orchestrator stop && claude-orchestrator resume

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Made by Sanghoon Han from Parallax AI LLC