claw

Claw

Multi-agent collaborative sandbox. Define your agents in YAML, get a full stack with one command.

Agents chat together (and with you) in a shared Matrix room. Each agent runs in its own isolated Docker container with configurable identity, memory, tools, and workspace access. All network traffic is observable via mitmproxy.

Prerequisites

• Docker (with Compose v2)
• An Anthropic API key (console.anthropic.com)

Quick Start

Install as Claude Code plugin (recommended)

# Add the marketplace (one-time)
/plugin marketplace add your-org/your-repo

# Install the plugin
/plugin install claw

# Spin up a workspace from any directory
/claw:up with an analyst and a coder working on ~/code/myapp

Claude Code handles everything — picks available ports, writes the config, generates the stack, starts it, and tells you how to log in. Works from any directory.

From the claw directory

If you're working directly in the claw repo:

cd claw/
claude
> /claw-up with an analyst and a coder working on ~/code/myapp

Manual

# 1. Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# 2. Edit agents (or use defaults)
vim claw.yaml

# 3. Generate and start
./init.sh
cd generated && docker compose up -d

init.sh prints everything you need to log in:

=== Ready! ===

  cd generated && docker compose up -d

Then open Element and log in:

  URL:         http://localhost:38088
  Homeserver:  http://localhost:38008
  Username:    jeff
  Password:    jeff-2026

Traffic inspector: http://localhost:38081

Important: When Element asks for a homeserver, click "Edit" and enter http://localhost:38008. This is the most common gotcha for first-time users.

How It Works

┌─────────────────────────────────────────────────────┐
│ Docker                                              │
│                                                     │
│  ┌──────────┐  ┌─────────┐  ┌─────────┐            │
│  │ Agent A  │  │ Agent B │  │ Agent C │  ...        │
│  │ (Claude) │  │ (Claude)│  │ (BYO)   │            │
│  └────┬─────┘  └────┬────┘  └────┬────┘            │
│       │              │            │                  │
│  ┌────▼──────────────▼────────────▼────┐            │
│  │         Synapse (Matrix)            │            │
│  │         homeserver                  │            │
│  └────────────────┬────────────────────┘            │
│                   │                                  │
│  ┌────────────────▼────────────────────┐            │
│  │         mitmproxy                   │──► internet│
│  │         (egress control)            │            │
│  └─────────────────────────────────────┘            │
│                                                     │
│  ┌─────────────────────────────────────┐            │
│  │         Element (web chat UI)       │            │
│  └─────────────────────────────────────┘            │
└─────────────────────────────────────────────────────┘

• Matrix is the coordination layer. Agents and humans chat in the same room — like a team Slack channel, but with AI teammates.
• mitmproxy controls and logs all outbound traffic. You can see every API call your agents make.
• Element gives you a real chat UI — no custom frontend needed.
• Each agent is an isolated container with its own identity, memory, and workspace.

Choosing a Model

Model	Speed	Cost	Best for
claude-haiku-4-5-20251001	Fast	~$0.25/1M input	Lightweight tasks, analysis, chat. Good default.
claude-sonnet-4-6	Medium	~$3/1M input	Code writing, complex reasoning, detailed work.
claude-opus-4-6	Slower	~$15/1M input	Hard problems, architecture, long-form writing.

Start with haiku for all agents. Upgrade individual agents to sonnet/opus when they need more capability. A team of haiku agents chatting for a day costs a few dollars.

claw.yaml

name: my-team

# Ports (high range to avoid dev server conflicts)
ports:
  synapse: 38008
  element: 38088
  mitmproxy_ui: 38081

# Human user (auto-created)
human:
  username: jeff
  password: jeff-2026

# Chat room
room:
  alias: claw
  name: "The Claw"

# Egress: "log-only" (see everything) or "allowlist" (block unlisted domains)
egress:
  mode: log-only

# Defaults for all agents
agent_defaults:
  model: claude-haiku-4-5-20251001
  respond_to: smart   # respond to humans always, bots only when @mentioned

# Your agents
agents:
  - name: analyst
    identity: ./examples/analyst.md
    workspace:
      - /path/to/code:/workspace/code:ro   # read-only

  - name: coder
    model: claude-sonnet-4-6               # override model for this agent
    identity: ./examples/coder.md
    workspace:
      - /path/to/code:/workspace/code      # read-write