# Claude Colony

[![npm version](https://img.shields.io/npm/v/claude-colony.svg)](https://www.npmjs.com/package/claude-colony)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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%)      │
└─────────────────────┴─────────────────────────────┘
```

![Claude Colony in action](docs/colony-screenshot.png)

## Why Claude Colony?

| | |
|-|-|
| **True Multi-Agent** | Full Claude Code instances, not sandboxed sub-tasks. Each agent can spawn its own agents, use every tool, and work in parallel—just like a real dev team |
| **Native Integration** | Built on Claude Code's agent system — your `.claude/agents/` work everywhere |
| **Visual Collaboration** | Watch your AI team work in real-time via tmux |
| **Simple Communication** | File-based @mention protocol, no complex setup |
| **Ready-Made Teams** | Start with fullstack, frontend, API, or mobile presets instantly |

> **Note:** Because each agent is a full Claude Code instance with unlimited capability, token usage can add up quickly. We recommend using Claude Colony with a [Max plan](https://www.anthropic.com/pricing) for the best experience.

## Prerequisites

- **Node.js 18+**
- **tmux** — `brew install tmux` (macOS) or `apt install tmux` (Linux)
- **[Claude Code](https://github.com/anthropics/claude-code)** — installed and authenticated

```bash
# Verify Claude Code is working
claude --version
```

## Installation

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

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

### From Source

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

## Quick Start

```bash
# 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

```bash
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

```bash
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 |

```bash
# List all presets
colony presets

# View preset details
colony presets fullstack

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

## Workflow Examples

### Feature Development

```bash
colony start --preset fullstack

# Agents coordinate via @mentions:
# @ux:       "I'll design the login flow wireframes"
# @frontend: "Building the form based on UX specs"
# @backend:  "Creating /auth endpoints"
# @devops:   "Setting up CI for the new routes"
```

### API Sprint

```bash
colony start --preset api-team

# Parallel development:
# @api-dev builds endpoints while @data-dev designs schemas
# @docs documents as features complete
```

### Debug Session

```bash
colony start -p fullstack

# In the shared pane, give context:
# @all: "Users report 500 errors on checkout. @backend investigate
#        the /orders endpoint, @frontend check error handling"
```

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

```markdown
<!-- .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

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

```bash
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:

```bash
tmux attach -t colony
```

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

## How It Compares

| | Claude Colony | Single Claude Code | Generic Orchestrators |
|-|---------------|--------------------|-----------------------|
| Agent architecture | Full instances | Single instance | Task-based sub-agents |
| Agents spawn sub-agents | Yes | Yes | Limited/No |
| Parallel execution | Yes | No | Yes |
| Native `.claude/agents/` | Yes | Yes | No |
| Visual monitoring | tmux real-time | Terminal | Varies |
| Agent communication | @mention protocol | N/A | Custom |
| Setup | `colony init` | N/A | Often complex |

## Development

```bash
# 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
```

## License

MIT