claude-colony

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:

• Create agents in Claude Code using .claude/agents/*.md files
• 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