Claude Colony

A tmux-based multi-agent orchestration system where multiple Claude Code instances collaborate on software development tasks.

Overview

Claude Colony enables a team of AI agents to work together on complex tasks. It builds on Claude Code's native agent system (.claude/agents/) — create your agents there, then orchestrate them as a team.

Each agent has a unique persona, role, and area of focus. They communicate via a file-based message broker and are visualized in a tmux session.

┌─────────────────────┬─────────────────────────────┐
│                     │      Specialist Agent 1     │
│                     ├─────────────────────────────┤
│   Manager Agent     │      Specialist Agent 2     │
│      (40%)          ├─────────────────────────────┤
│                     │      Specialist Agent 3     │
│                     ├─────────────────────────────┤
│                     │   Shared Context (10%)      │
└─────────────────────┴─────────────────────────────┘

Installation

# Install globally from npm
npm install -g claude-colony

# Or run directly with npx
npx claude-colony --help

From Source

git clone https://github.com/jamiemurphy/claude-colony.git
cd claude-colony
npm install && npm run build && npm link

Quick Start

# Initialize colony in your project
colony init

# Start a colony with a preset
colony start --preset fullstack

# Check status
colony status

# Stop the colony
colony stop

Tip: For best results, create custom agents in .claude/agents/ tailored to your project, then build a preset that uses them with colony create-team.

CLI Commands

| Command | Description | |---------|-------------| | colony init | Initialize .colony/ directory in current project | | colony start | Start a colony session | | colony stop | Stop the running colony | | colony status | Show colony status | | colony presets | List available presets | | colony presets <name> | Show preset details | | colony agents | List available agents | | colony agents <name> | Show agent details | | colony create <name> | Create a new agent | | colony build | Initialize and configure colony (init + setup) |

Start Command Options

colony start [options]

Options:
  -p, --preset <name>   Use a preset configuration
  -a, --agents <count>  Number of worker panes (default: 4)
  --no-attach           Don't attach to tmux session

Create Command Options

colony create <name> [options]

Options:
  -d, --description <desc>  Agent description
  -m, --model <model>       Model (sonnet, opus, haiku)
  -t, --tools <tools>       Comma-separated tools
  -g, --global              Create in ~/.claude/agents/
  -f, --force               Overwrite existing

Presets

Built-in presets for common team configurations:

| Preset | Description | Agents | |--------|-------------|--------| | fullstack | Full-stack web development | UX, Frontend, Backend, DevOps | | frontend-team | UI-focused development | UX, UI Dev, Logic Dev | | api-team | Backend API development | API Dev, Data Dev, Docs | | mobile-app | Mobile app development | UX, Mobile Dev, API Dev, DevOps | | docs-team | Documentation team | API Docs, Guides, Review |

# List all presets
colony presets

# View preset details
colony presets fullstack

# Start with a preset
colony start --preset fullstack

Agents

Claude Colony uses Claude Code's native agent system. The recommended workflow is:

1. Create agents in Claude Code using .claude/agents/*.md files
2. Use those agents in your colony presets

Creating Agents (Recommended)

Create agents directly in your project's .claude/agents/ directory. These are standard Claude Code agents that work both standalone and in colonies:

<!-- .claude/agents/api-designer.md -->
---
name: api-designer
description: REST API design specialist
model: sonnet
---

# API Designer

You are an API design specialist focused on RESTful best practices...

Agent Locations

| Location | Scope | Description | |----------|-------|-------------| | .claude/agents/*.md | Project | Recommended. Committed to git, works with Claude Code | | ~/.claude/agents/*.md | User | Personal agents, available across all projects | | Built-in | Colony | Fallback defaults (frontend-dev, backend-dev, etc.) |

Using Your Agents

# See all available agents (from .claude/agents/ and built-ins)
colony agents

# View agent details
colony agents api-designer

# Create a preset that uses your agents
colony create-team

Quick Agent Creation

If you need a quick agent without writing markdown:

colony create my-agent -d "My custom agent" -m sonnet

This creates a .claude/agents/my-agent.md file you can then customize.

Project Structure

After running colony init:

.colony/
├── config.yaml    # Colony configuration
├── state/         # Session state
├── messages/      # Agent communication
├── agents/        # Agent prompts
├── shared/        # Shared data channels
└── reviews/       # Code reviews

Architecture

Core Components

• MessageBroker - File-based IPC with @mention routing
• SessionManager - Session state persistence
• TmuxManager - Tmux session and pane management
• CompletionDetector - Monitors worker completion
• ColonyMonitor - Real-time status monitoring
• SharedScratchpad - Typed data channels for agent collaboration
• OwnershipRegistry - File ownership tracking
• ReviewManager - Code review workflow
• DependencyGraph - Task dependency tracking
• FileLock - Concurrent access safety

Communication Protocol

Agents communicate using @mentions:

@frontend: Build the login form with validation
@backend: Create the /auth/login endpoint
@all: Team standup in 5 minutes
@manager: I'm blocked on the API schema

Agent Status

• 🟢 Ready — awaiting work
• 🟡 Working — actively processing
• 🔴 Blocked — needs input/help
• ✅ Done — declared completion

Viewing the Colony

Attach to the tmux session:

tmux attach -t colony

Navigation:

• Ctrl+B then Arrow Keys - Switch panes
• Ctrl+B then D - Detach (colony keeps running)

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests once
npm run test:run

# Type check
npm run typecheck

# Lint
npm run lint

# Full check
npm run check

Requirements

• Node.js 18+
• tmux
• Claude Code CLI (claude)

License

MIT