GitHub - bobum/Claude-Nine: The Site

╔═══════════════════════════════════════════════════════════════════════╗
║                                                                       ║
║  ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗      █████╗       ║
║ ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝     ██╔══██╗      ║
║ ██║     ██║     ███████║██║   ██║██║  ██║█████╗ █████╗╚██████║      ║
║ ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝ ╚════╝ ╚═══██║      ║
║ ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗     █████╔╝       ║
║  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝     ╚════╝        ║
║                                                                       ║
║            Multi-Agent Orchestration Powered by Claude                ║
║                                                                       ║
╚═══════════════════════════════════════════════════════════════════════╝

Where Claude agents soar together in perfect harmony ☁️

Features • Quick Start • How It Works • Documentation • Contributing

🏠 Runs 100% Locally

Claude-Nine runs entirely on your machine - no cloud infrastructure required!

# One-line installation
./install.sh

# Start Claude-Nine
./start.sh

# Open http://localhost:3000

✅ Local database (SQLite - no setup needed) ✅ Local API server (FastAPI on localhost:8000) ✅ Local dashboard (Next.js on localhost:3000) ✅ Your git repos stay local ⚡ Only dependency: Anthropic API for Claude AI

📖 Local Setup Guide | 🚀 Quick Start

🌟 What is CLAUDE-9?

CLAUDE-9 is a revolutionary multi-agent orchestration platform that enables multiple Claude AI agents to work simultaneously on different features in the same codebase—without stepping on each other's toes.

Think of it as your personal AI development team in a box, complete with:

🎛️ Web Dashboard - Manage teams, assign work, monitor progress
🤖 AI Agents - Claude-powered developers working in parallel
📋 Work Queue - Integrate with Azure DevOps, Jira, GitHub, or create manual tasks
📊 Real-time Monitoring - Watch your AI team code in real-time
🔄 Git Worktrees - Each agent works in isolated directories

🎭 The Magic

                         📋 Work Queue
                    (3 items queued)
                              │
                    ┌─────────▼─────────┐
                    │   🎼 Orchestrator  │
                    │  Creates 1 agent   │
                    │   per work item    │
                    └─────────┬─────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   🤖 Agent 1            🤖 Agent 2            🤖 Agent 3
  (Auth System)        (API Logging)        (Swagger Docs)
        │                     │                     │
        ▼                     ▼                     ▼
   📁 Worktree 1         📁 Worktree 2         📁 Worktree 3
   (Isolated)            (Isolated)            (Isolated)
        │                     │                     │
        └─────────────────────┴─────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  🔀 Post-Completion │
                    │  Merge + PR Create  │
                    └─────────┬─────────┘
                              │
                    ✨ Integration Branch → PR

Agents are transitory: Created automatically per work item, visible during execution, cleaned up after completion.

✨ Features

🚀 True Parallel Development

Each agent works in its own isolated git worktree, enabling genuine simultaneous development without conflicts.

🧠 Intelligent Conflict Resolution

A dedicated Resolver Agent is spawned on-demand when merge conflicts occur during the post-completion phase, using Claude to intelligently merge code.

🔄 Automatic Orchestration

Define features in YAML, run one command, and watch multiple agents implement them in parallel—complete with commits and merges.

🛡️ Production-Ready Safety

Atomic git operations
Automatic worktree cleanup
Comprehensive error handling
Detailed logging
Graceful shutdown (Ctrl+C safe)

📦 Zero Directory Conflicts

Git worktrees give each agent its own physical workspace—no more agents fighting over the same files!

🎯 YAML-Driven Configuration

Simple, declarative task definitions make it easy to specify exactly what you want built.

🎯 Use Cases

Scenario	Description	Benefit
🏗️ Rapid Prototyping	Develop multiple features simultaneously	3x faster development
🔧 Legacy Modernization	Add auth, logging, docs in parallel	Coordinate complex changes
🧪 Experimental Features	Try multiple approaches at once	Compare solutions easily
📚 Documentation Sprints	Generate docs while building features	Never fall behind
🎨 Refactoring	Modernize multiple modules together	Maintain consistency

🚀 Quick Start

Prerequisites

✓ Python 3.12+
✓ Node.js 18+
✓ Git 2.7+
✓ Anthropic API key (get one at console.anthropic.com)

One-Command Installation

# 1. Clone Claude-Nine
git clone https://github.com/bobum/Claude-Nine.git
cd Claude-Nine

# 2. Run the installer (checks everything and sets up automatically)
./install.sh

# 3. Start Claude-Nine
./start.sh

The installer will:

✓ Check Python, Node.js, and Git are installed
✓ Prompt for your Anthropic API key
✓ Set up the API server with local SQLite database
✓ Install dashboard dependencies
✓ Create helper scripts (start.sh, stop.sh)

Your First Claude-Nine Session 🚀

# Start everything
./start.sh

# Open your browser
open http://localhost:3000  # macOS
# or visit http://localhost:3000 in your browser

What you'll see:

🎯 Interactive Tutorial - Guides you through all features
👥 Teams Page - Create teams linked to your git repos
📋 Work Queue - Add tasks from DevOps/Jira or create manually
📊 Real-time Dashboard - Monitor agents as they work (live telemetry)

That's it! Queue your work items, click Start, and watch agents spin up automatically—one per task.

🎬 Example: Building an Express API

Let's add authentication, logging, and documentation to an Express.js API—all at once:

1. Create your mission brief (tasks/api-enhancement.yaml):

features:
  - name: jwt_authentication
    branch: feature/auth
    description: |
      Implement JWT authentication with:
      - User registration endpoint
      - Login endpoint
      - Token verification middleware
      - Password hashing with bcrypt

  - name: winston_logging
    branch: feature/logging
    description: |
      Add comprehensive logging with:
      - Request/response logging
      - Error tracking
      - Performance metrics
      - Log rotation

  - name: swagger_docs
    branch: feature/docs
    description: |
      Create OpenAPI documentation:
      - Interactive Swagger UI
      - All endpoint documentation
      - Schema definitions
      - Authentication examples

2. Launch CLAUDE-9:

cd my-express-api
python /path/to/orchestrator.py --tasks tasks/api-enhancement.yaml

3. Watch the magic ✨:

🎼 Starting Multi-Agent Orchestrator with Worktrees
================================================================================
Creating 3 feature agents (each with isolated worktree)
Created 1 monitor agent (working in main repo)

Worktrees created at:
  - .agent-workspace/worktree-jwt_authentication
  - .agent-workspace/worktree-winston_logging
  - .agent-workspace/worktree-swagger_docs

🚀 Starting crew execution...

[Agent jwt_authentication] Creating src/auth/auth.js...
[Agent winston_logging] Installing winston dependency...
[Agent swagger_docs] Setting up Swagger UI...
[Monitor Agent] Checking for conflicts...
[Agent jwt_authentication] Implementing user registration...
[Monitor Agent] No conflicts detected ✓
[Agent winston_logging] Adding request logger middleware...
...

4. Result: Three features developed in parallel, conflicts resolved, merged to main! 🎉

🏗️ How It Works

The Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        🎼 ORCHESTRATOR                            │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │     CrewAI Parallel Process (async_execution=True)          │  │
│  │         1 Agent per Work Item - All run simultaneously      │  │
│  └────────────────────────────────────────────────────────────┘  │
│              │                    │                    │          │
│         ┌────▼────┐          ┌────▼────┐          ┌────▼────┐    │
│         │ Agent 1 │          │ Agent 2 │          │ Agent N │    │
│         │  🤖     │          │  🤖     │          │  🤖     │    │
│         └────┬────┘          └────┬────┘          └────┬────┘    │
└──────────────┼────────────────────┼────────────────────┼─────────┘
               │                    │                    │
          ┌────▼────┐          ┌────▼────┐          ┌────▼────┐
          │Worktree │          │Worktree │          │Worktree │
          │   1     │          │   2     │          │   N     │
          │ 📁      │          │ 📁      │          │ 📁      │
          └────┬────┘          └────┬────┘          └────┬────┘
               │                    │                    │
               └────────────────────┴────────────────────┘
                                    │
                          ┌─────────▼─────────┐
                          │   POST-COMPLETION  │
                          │ ┌───────────────┐ │
                          │ │ Push branches │ │
                          │ │ Merge → integration │
                          │ │ Resolve conflicts │◄── 🔧 Resolver Agent
                          │ │ Create PR     │ │     (spawned if needed)
                          │ └───────────────┘ │
                          └─────────┬─────────┘
                                    │
                          ┌─────────▼─────────┐
                          │   Shared .git DB   │
                          │        🗄️          │
                          └───────────────────┘

The Secret Sauce: Git Worktrees

The Problem ❌:

my-project/          # All agents fight over this directory!
├── src/
└── .git/

→ Agent 1 checks out feature/auth → Agent 2 tries to check out feature/logging → CHAOS! Files constantly switching, work overwritten

The Solution ✅:

my-project/
├── .git/                        # Shared git database
├── src/                         # Main directory (untouched)
└── .agent-workspace/
    ├── worktree-auth/           # Agent 1's private workspace
    │   └── src/                 # Independent file copy
    ├── worktree-logging/        # Agent 2's private workspace
    │   └── src/                 # Independent file copy
    └── worktree-docs/           # Agent 3's private workspace
        └── src/                 # Independent file copy

→ Each agent has own directory → No conflicts, true parallelism → HARMONY! ☁️

🔄 Complete Workflow Loop

This is the full operational cycle for CLAUDE-9:

┌─────────────────────────────────────────────────────────────────────────────┐
│                         CLAUDE-9 WORKFLOW LOOP                              │
└─────────────────────────────────────────────────────────────────────────────┘

  ┌─────────────────────────────────────────────────────────────────────────┐
  │  1️⃣  PRE-RUN CHECK                                                       │
  │  ─────────────────                                                       │
  │  • Check if workspace has leftover worktrees/branches from last run     │
  │  • If dirty: prompt to cleanup (or use --cleanup-only)                  │
  │  • Clean slate ensures no conflicts with previous sessions              │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  2️⃣  SESSION SETUP                                                       │
  │  ─────────────────                                                       │
  │  • Generate unique session ID (e.g., a31608fb)                          │
  │  • Create integration branch: integration/{session}                     │
  │  • For each task N:                                                     │
  │    - Create worktree: .agent-workspace/worktree-task-00N-{session}      │
  │    - Create branch: feature/task-00N-{session}                          │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  3️⃣  PARALLEL FEATURE WORK                                               │
  │  ─────────────────────────                                               │
  │  • N agents spawn simultaneously (async_execution=True)                 │
  │  • Each agent works in isolated worktree                                │
  │  • No interference - true parallel development                          │
  │  • Agents commit changes to their feature branches                      │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  4️⃣  POST-COMPLETION PHASE                                               │
  │  ─────────────────────────                                               │
  │  • Push all feature branches to remote                                  │
  │  • Merge each feature branch into integration/{session}:                │
  │                                                                         │
  │    feature/task-001 ──┐                                                 │
  │    feature/task-002 ──┼──► integration/{session}                        │
  │    feature/task-003 ──┤                                                 │
  │    feature/task-004 ──┘                                                 │
  │                                                                         │
  │  • If merge conflict occurs:                                            │
  │    🔧 Resolver Agent spawns automatically                               │
  │    → Reads conflict markers                                             │
  │    → Intelligently merges code using Claude                             │
  │    → Commits resolved files                                             │
  │    → Continues with remaining branches                                  │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  5️⃣  READY FOR PR                                                        │
  │  ─────────────                                                           │
  │  • integration/{session} contains ALL merged feature code               │
  │  • Create PR: integration/{session} → main                              │
  │  • Human review and approval                                            │
  │  • Merge to main when ready                                             │
  └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                        ┌───────────────────────┐
                        │  🔄 RINSE & REPEAT    │
                        │  Run --cleanup-only   │
                        │  Start new session    │
                        └───────────────────────┘

Cleanup Between Runs

# Clean up all worktrees and session branches
python orchestrator.py --cleanup-only

# Or let the orchestrator prompt you if workspace is dirty
python orchestrator.py --tasks my-tasks.yaml
# → "Existing worktrees detected. Clean up? [y/N]"

📚 Documentation

Core Components

claude-multi-agent-orchestrator/ - The main orchestration system
- orchestrator.py - Multi-agent coordinator with worktree support
- git_operations.py - Git operations wrapper with worktree management
- git_tools.py - CrewAI tools for git operations
- tasks/ - YAML task definitions
- README.md - Comprehensive documentation

Key Concepts

🎯 Agents (Transitory)

Feature Agents: Created dynamically by the orchestrator—1 agent per work item. Each works in an isolated worktree and is automatically cleaned up after the run completes.

Resolver Agent: Spawned on-demand during post-completion merge if conflicts are detected. Uses Claude to intelligently resolve merge conflicts.

All agents are powered by Claude Sonnet 4.5 and have access to git tools. Agents are not manually configured—they're created automatically based on your work queue.

📁 Worktrees

Git worktrees enable multiple working directories from the same repository:

Shared .git database (efficient)
Independent file copies (isolated)
Each worktree on different branch
Changes visible across all worktrees
Automatic cleanup on shutdown

🔧 Tasks

Tasks are defined in YAML with:

name: Feature identifier
role: Agent role/specialization
goal: What to accomplish
branch: Git branch name
description: Detailed implementation steps
expected_output: Success criteria

See tasks/example_tasks.yaml for examples.

🔀 Post-Completion & Conflict Resolution

After all feature agents complete their work, the orchestrator runs a post-completion phase:

Push all branches to remote
Create integration branch from main
Merge each feature branch sequentially into integration
If conflicts occur → Spawn Resolver Agent to auto-resolve
Create Pull Request from integration branch to main using gh CLI

The Resolver Agent uses specialized tools:

Read Conflict - Parse conflict markers
Resolve Conflict - Write merged code
List Conflicts - Show unresolved files
Complete Merge - Finalize merge commit

🎨 Advanced Usage

Custom Orchestration

from orchestrator import MultiAgentOrchestrator

# Create orchestrator
orchestrator = MultiAgentOrchestrator(
    config_path="my-config.yaml",
    tasks_path="my-tasks.yaml"
)

# Add custom signal handling
orchestrator.setup_signal_handlers()

# Run it
result = orchestrator.run()

Inspecting Live Progress

Watch your agents work in real-time:

# Terminal 1: Run orchestrator
python orchestrator.py

# Terminal 2: Watch Agent 1
cd .agent-workspace/worktree-auth
watch -n 2 'git log --oneline -5 && echo && git status'

# Terminal 3: Watch Agent 2
cd .agent-workspace/worktree-logging
watch -n 2 'git log --oneline -5 && echo && git status'

Manual Cleanup

If orchestrator crashes or you need to reset:

python orchestrator.py --cleanup-only

Integration with CI/CD

# .github/workflows/multi-agent-dev.yml
name: Multi-Agent Development

on:
  workflow_dispatch:
    inputs:
      tasks_file:
        description: 'Tasks YAML file'
        required: true
        default: 'tasks/features.yaml'

jobs:
  orchestrate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          cd claude-multi-agent-orchestrator
          pip install -r requirements.txt

      - name: Run CLAUDE-9 Orchestrator
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python orchestrator.py --tasks ${{ inputs.tasks_file }}
          python orchestrator.py --cleanup-only

🔍 Troubleshooting

Issue	Solution
🚫 "Not in a git repository"	Run from git repository root
🔑 "API key not found"	Set `ANTHROPIC_API_KEY` environment variable
🌲 "Worktree already exists"	Run `python orchestrator.py --cleanup-only`
⚠️ "Git worktree command not found"	Update git to 2.7+
🔄 Agent stuck/not progressing	Check `.agent-workspace/orchestrator.log` for errors
💥 Crashes leave worktrees	Always safe: run `--cleanup-only` to reset

🤝 Contributing

We welcome contributions! CLAUDE-9 is designed to be extensible:

Ways to Contribute

🐛 Bug Reports: Found an issue? Open a GitHub issue
✨ Feature Requests: Have an idea? We'd love to hear it
🔧 Pull Requests: Improvements welcome!
📚 Documentation: Help others get started
🎨 Examples: Share your task definitions

Development Setup

# Fork and clone
git clone https://github.com/yourusername/Claude-Nine.git
cd Claude-Nine

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes, test, commit
git commit -m "Add amazing feature"

# Push and create PR
git push origin feature/amazing-feature

📊 Performance

Parallel Speedup: 3-5x faster than sequential development
Memory Efficient: Shared .git database minimizes disk usage
Lightweight Worktrees: ~100MB per worktree for typical projects
Cleanup Time: <5 seconds for 10 worktrees
API Efficient: Parallel requests maximize Claude API throughput

🌈 Roadmap

📜 License

This project is provided as-is for educational and development purposes.

🙏 Acknowledgments

Built with love using:

CrewAI - Multi-agent orchestration framework
Claude Sonnet 4.5 - Anthropic's AI model
GitPython - Git operations in Python
Git Worktrees - Isolated workspace magic
PyYAML - Configuration management

💬 Support

📖 Documentation: See claude-multi-agent-orchestrator/README.md
🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions

🌟 Star us on GitHub — it motivates us to keep improving CLAUDE-9!

Made with ☁️ and ❤️ by developers who believe AI should work together, not alone

     ☁️  ☁️  ☁️
  ☁️  ☁️  ☁️  ☁️
    🤖  🤖  🤖
   Working in harmony
    on CLAUDE-9

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 169 Commits
.claude/commands		.claude/commands
api		api
claude-multi-agent-orchestrator		claude-multi-agent-orchestrator
dashboard		dashboard
docs		docs
shared		shared
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
GETTING_STARTED.md		GETTING_STARTED.md
README.md		README.md
ROADMAP.md		ROADMAP.md
TESTING_RESULTS.md		TESTING_RESULTS.md
VISION.md		VISION.md
install.bat		install.bat
install.ps1		install.ps1
install.sh		install.sh
test_config.yaml		test_config.yaml
test_tasks.yaml		test_tasks.yaml
test_telemetry.py		test_telemetry.py

bobum/Claude-Nine

Folders and files

Latest commit

History

Repository files navigation