Multi-Agent Workflow Kit

Orchestrate parallel AI agents in isolated git worktrees with shared tmux visibility.

Run multiple AI coding agents simultaneously without chaos. Each agent gets its own git branch and workspace (via git worktree), while you supervise all of them in a single tmux session.

⚠️ Proof of Concept - Early Development Stage

This project is currently a proof of concept exploring multi-agent workflows with AI coding assistants. It's actively evolving and may have rough edges. We're experimenting with patterns for coordinating multiple AI agents on the same codebase.

We welcome your help! PRs, issues, and discussions are highly encouraged. If you have ideas for improving agent coordination, workflow patterns, or have encountered interesting use cases, please share them.

Quick Start

Prerequisites: git (≥2.5), tmux (≥3.2), yq, uvx

# Navigate to your project
cd your-project

# Bootstrap everything in one command
uvx --no-cache --from git+https://github.com/Soul-Brews-Studio/multi-agent-workflow-kit.git@v0.5.1 multi-agent-kit init

# Activate the environment
source .envrc

# Attach to your multi-agent session
maw attach

That's it! You now have:

• 3 agent worktrees ready to use
• A tmux session with all agents visible
• maw commands available for managing agents

Next steps:

• Edit .agents/agents.yaml to configure your agents
• Run maw install to provision any new agents
• Use maw hey <agent> <message> to send tasks to agents

How It Works

Each agent gets its own git worktree (separate directory + branch). You see all agents in one tmux session with split panes.

repo/                  ← main worktree (branch: main)
agents/
  ├── 1/              ← agent 1 (branch: agents/1)
  ├── 2/              ← agent 2 (branch: agents/2)
  └── 3/              ← agent 3 (branch: agents/3)

Tmux Layout (default profile):

┌──────────────────────────────┐
│         Agent 1 (top)        │
├──────────────────────────────┤
│       Agent 2 (middle)       │
├──────────────────────────────┤
│        Root (bottom)         │
└──────────────────────────────┘

Essential Commands

# Start/stop
maw attach          # Attach to running session
maw kill            # Stop session

# Send tasks to agents
maw hey 1 "add user authentication"
maw hey 2 "write tests for auth"
maw send "git status"  # broadcast to all

# Focus and zoom
maw zoom 1          # Toggle zoom for agent 1
maw zoom root       # Toggle zoom for root pane

# Sync with main branch
maw sync            # smart sync (context-aware)

# Navigate between worktrees
maw warp 1          # jump to agent 1
maw warp root       # jump to main

# Manage agents
maw agents list     # show all agents
maw remove 3        # delete agent 3

Configuration

Edit .agents/agents.yaml to configure your agents:

agents:
  1:
    branch: agents/1
    worktree_path: agents/1
    model: claude-sonnet-4
    description: "Core backend"

After editing, run maw install to sync worktrees.

Documentation

• Architecture: Design principles and integration patterns
• Operations Checklist: Launch/teardown procedures
• Testing Guide: Smoke tests before releases
• Branching Strategy: RRR workflow (Route, Release, Repair)
• AGENTS.md: Conventions for human+AI collaboration

---

Reference

Full Command List

# Setup
maw install          # Provision worktrees from agents.yaml
maw direnv           # Enable direnv in all worktrees

# Session management
maw start <profile>  # Launch tmux session
maw attach           # Attach to running session
maw kill             # Terminate session

# Agent communication
maw hey <agent> <msg> # Send message to specific agent
maw send "<cmd>"     # Broadcast command to all panes
maw zoom <agent>     # Toggle zoom for agent pane

# Agent management
maw agents list      # List all agents
maw agents create N  # Create new agent
maw remove <agent>   # Delete agent worktree

# Navigation
maw warp <target>    # Navigate to worktree (agent number or 'root')

# Utilities
maw sync             # Smart git sync (context-aware)
maw catlab [gist-url] # Download CLAUDE.md guidelines (optionally from custom gist)
maw version          # Show toolkit version
maw uninstall        # Remove toolkit from repo

Claude Slash Commands

In Claude Code, use these commands:

• /maw.sync - Sync current worktree with main
• /maw.hey <agent> <message> - Send message to specific agent
• /maw.zoom <agent> - Toggle zoom for agent pane
• /maw.issue (alias /maw-issue) - Create a GitHub issue via gh after verifying authentication

Tmux Profiles

6 pre-configured layouts available:

Profile	Layout	Best For
profile0	Top + split bottom	2-3 agents, one dominant
profile1	Left column + stacked right	Primary/secondary split
profile2	Top row + full-width bottom	Pair programming style
profile3	Single full-width top	Focus mode
profile4	Three-pane	Small team
profile5	Six-pane dashboard	Full visibility

Use: maw start profile1

Advanced Topics

Installation Options

Using Specific Version

# Use stable version (recommended)
uvx --no-cache --from git+https://github.com/Soul-Brews-Studio/multi-agent-workflow-kit.git@v0.5.1 multi-agent-kit init

# Use main branch (latest features)
uvx --no-cache --from git+https://github.com/Soul-Brews-Studio/multi-agent-workflow-kit.git@main multi-agent-kit init

# Or with custom prefix (creates: demo-ai-<repo-name>)
uvx --no-cache --from git+https://github.com/Soul-Brews-Studio/multi-agent-workflow-kit.git@v0.5.1 multi-agent-kit init --prefix demo

# Opt in to agents/.gitignore (defaults to not creating it)
uvx --no-cache --from git+https://github.com/Soul-Brews-Studio/multi-agent-workflow-kit.git@v0.5.1 multi-agent-kit init --agents-gitignore

Manual Installation

# 1. Install toolkit assets
maw install

# 2. Edit agent configuration
$EDITOR .agents/agents.yaml

# 3. Launch tmux session
maw start profile0

Using as Template

gh repo create my-project --template Soul-Brews-Studio/multi-agent-workflow-kit --private --clone
cd my-project
maw install

Custom Tmux Profiles

Create .agents/profiles/custom.sh:

#!/bin/bash
PROFILE_NAME="custom"

layout_custom() {
    local session=$1
    local window=$2

    tmux split-window -v -t "$session:$window"
    tmux select-layout -t "$session:$window" even-horizontal
}

Use: maw start custom

Session Naming

# Default: ai-<repo-name>
maw start profile0

# Custom prefix: sprint-ai-<repo-name>
maw start profile0 --prefix sprint

# Change base prefix
export SESSION_PREFIX=research
maw start profile0  # → research-<repo-name>

Troubleshooting

Session Already Exists

tmux list-sessions
maw kill --prefix <prefix>

Worktree Creation Fails

git worktree list
git worktree remove agents/1 --force
git worktree prune
maw install

maw Command Not Found

direnv allow
# Or manually: source .envrc

Merge Conflicts

cd agents/1
git fetch origin main:main
git merge main
# Resolve conflicts, then:
git add . && git commit

Contributing

Contributions welcome! See Testing Guide for smoke tests.

---