claude-colony

Claude Colony is a tmux-based multi-agent orchestration system that coordinates multiple Claude Code instances to work together on software development tasks. It leverages Claude Code's native agent system, where agents live as markdown prompts in the .claude/agents/ directory and are orchestrated into teams through colony presets. The colony provides a visual, file-based communication workflow via a shared message broker and tmux panes, allowing agents to collaborate in real time, assign roles, and coordinate complex tasks across frontend, backend, API, DevOps, and other specialties. You can start with built-in presets like fullstack, frontend-team, or api-team, or customize your own team by creating agents in your repository and building a corresponding preset. The system emphasizes transparency and parallel work, enabling agents to spawn sub-agents, use Claude Code tools, and communicate through a simple @mention protocol in a conversational, developer-friendly environment.

Prerequisites:

• Node.js 18+ and npm
• tmux installed (e.g., brew install tmux on macOS or apt install tmux on Linux)
• Claude Code installed and authenticated

Installation steps:

1. Install Claude Colony globally (preferred method): npm install -g claude-colony

2. Verify installation or run via npx: npx claude-colony --help

3. If you want to build from source (optional): git clone https://github.com/jamiemurphy/claude-colony.git cd claude-colony npm install npm run build npm link

4. Start using Claude Colony with a preset: colony start --preset fullstack

Prerequisites recap:

• Ensure Node.js and npm are up to date
• Ensure tmux is installed and available in your PATH
• Have Claude Code installed and authenticated so agents can operate

Tips and notes:

• The colony relies on a file-based message broker and @mention style communication; keep your .claude/agents/ and colony presets under version control for reproducibility.
• Be mindful of token usage with Claude Code; large teams or long-running sessions can consume significant tokens.
• Start with a preset that matches your project structure, then customize agents in .claude/agents/ to tailor behavior to your needs.
• If you modify agents or presets, run colony build or colony init as needed to refresh the configuration.
• Common issues often relate to tmux pane management or missing Claude Code authentication; verify that Claude Code commands run correctly in your shell before starting the colony.