Perpendicular

Multi-agent collaboration framework using Claude Code, Tmux, and MCP (Model Context Protocol).

Overview

Perpendicular enables multiple AI agents to work in parallel on the same codebase without conflicts. Each agent gets its own git worktree, sparse-checkout, and dedicated workspace.

Quick Start

# Launch the admin agent
./admin

# From within admin, spawn workers
spawn_agent worker
spawn_agent memory

Architecture

perpendicular/
├── admin                 # Launch admin agent in tmux
├── perp <type>           # Spawn agent (admin|worker|memory|monitor)
├── perpendicular         # Launch tmux workspace
├── .claude/              # Auto-loaded MCP configs for Claude Code
├── .env.example          # Environment variables template
├── src/
│   ├── agent_tools.sh    # Tools for agents (source this!)
│   ├── tmux.conf         # Tmux configuration
│   └── mcp_profiles/     # Agent type descriptions (not MCP configs)
│       ├── admin.conf
│       ├── worker.conf
│       ├── memory.conf
│       └── monitor.conf
├── tests/                # Unit tests
└── __perpendicular_agent/ # Git worktrees (created at runtime)

Setup

1. Clone and navigate:

   git clone <repo>
   cd perpendicular

2. Configure environment (optional, for full MCP features):

   cp .env.example .env
   # Edit .env with your Upstash/Supabase credentials

3. Run tests to verify:

   ./tests/run_tests

4. Launch admin:

   ./admin

MCP servers (Context7, Supabase) are auto-loaded from .claude/mcp_servers.json.

Agent Types

Type	Purpose	MCP Servers
admin	Coordinates workers, assigns tasks	Agent-MCP, Context7
worker	Implementation, code changes	Context7, Supabase
memory	RAG management, knowledge graph	Agent-MCP, Context7
monitor	Self-healing, watches admin	(minimal)

Agent Tools

After spawning an agent, source the tools:

source agent_tools.sh

Available tools:

• get_directory [depth] - List all repo files from git
• download_file <path> - Copy to workspace + add to sparse-checkout
• upload [message] - Commit and push changes
• spawn_agent <type> - Spawn new agent (admin only)
• send_message <id> <msg> - Send tmux message to agent
• check_status - Show all agent statuses
• query_context <query> - Query knowledge graph (context7)

MCP Integration

MCP servers are auto-configured from .claude/mcp_servers.json. No manual setup needed!

Included MCPs

MCP	Purpose
Context7	Shared knowledge graph for all agents
Supabase	Database, file locking, task queues

Optional: Agent-MCP

For advanced multi-agent orchestration (task management, conflict resolution):

uv venv && uv install
uv run -m agent_mcp.cli --port 8080

Then add to .claude/mcp_servers.json:

{
  "agent-mcp": {
    "command": "uv",
    "args": ["run", "-m", "agent_mcp.cli", "--port", "8080"]
  }
}

Inter-Agent Communication

CRITICAL: When agents communicate via tmux, use TWO separate commands:

1. Type message: tmux send-keys -t agent_1 "Hello"
2. Press enter: tmux send-keys -t agent_1 Enter

Trying to do both at once doesn't work reliably.

Testing

./tests/run_tests

Workflow Example

1. Start admin: ./admin
2. Admin spawns workers: spawn_agent worker
3. Worker queries context: query_context "auth system design"
4. Worker downloads file: download_file src/auth.rs
5. Worker edits file in __agent_environment/
6. Worker uploads: upload "Implement login"
7. Admin monitors: check_status

Self-Healing Swarm

The monitor agent watches the admin and reinitializes if it dies:

# From admin
spawn_agent monitor

Monitor sleeps 120s, checks admin status, reinitializes if needed. Loops forever.

License

MIT