Sauce

  ███████╗ █████╗ ██╗   ██╗ ██████╗███████╗
  ██╔════╝██╔══██╗██║   ██║██╔════╝██╔════╝
  ███████╗███████║██║   ██║██║     █████╗
  ╚════██║██╔══██║██║   ██║██║     ██╔══╝
  ███████║██║  ██║╚██████╔╝╚██████╗███████╗
  ╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝╚══════╝
       The Secret Ingredient for AI Swarms
                  by Sauce Labs

Run multiple Claude Code agents on the same codebase without conflicts.

Quick Start | Demo | Architecture | Documentation

Why Sauce?

When you run multiple AI coding agents in parallel, things break:

• File conflicts — Two agents edit the same file
• Merge chaos — Conflicting branches pile up
• Coordination overhead — You become the bottleneck, directing traffic

Sauce solves this with scope-based write guards and role-based coordination:

# Agent claims exclusive scope before editing
sauce claim --scope "src/auth/**" --actor worker-alpha

# Other agents cannot claim overlapping files
sauce claim --scope "src/auth/login.ts" --actor worker-beta
# ERROR: Scope conflict with worker-alpha

Demo

Coming soon: Watch a 2-worker swarm build a complete auth feature in under 5 minutes.

See docs/DEMO-SCRIPT.md for the demo scenario.

Quick Start

# Install
bun add sauce

# Initialize in your project
bunx sauce init

# Create worker worktrees
bunx sauce setup --workers 2

# Start the coordination system
bunx sauce launch

That's it. Your project now has:

• .coord/ — Coordination state (tasks, queue, leases)
• .claude/commands/ — Agent role prompts
• worktrees/ — Isolated working directories per agent

Features

Core Coordination

| Feature | Description | |---------|-------------| | Write Guards | File-level scope locks prevent edit conflicts | | Task Queue | Priority-ordered work distribution | | Branch Isolation | Each task = one branch, auto-created | | Integration Queue | Orderly merging with conflict detection | | Audit Trail | Every action logged for observability |

Agent Roles

| Role | Purpose | |------|---------| | VP | Strategic oversight, fleet command | | Manager | Decomposes requests into parallelizable tasks | | Worker | Implements tasks in isolated branches | | Reviewer | Validates work before integration | | Integrator | Merges approved branches to main | | Scout | Pre-planning research and codebase exploration | | Sentinel | System health monitoring and alerts |

v0.1.0 Highlights

• Skill-Based Routing — Tasks matched to workers with relevant skills
• Pattern Memory — Learn from past task solutions
• Typed Messaging — Structured inter-agent communication with audit trail
• Board of Directors — AI oversight layer with unanimous veto power

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Human Founder                           │
├─────────────────────────────────────────────────────────────────┤
│                    Board of Directors (Phase 6)                 │
│                 Director-A ◄──────► Director-B                  │
│                      Unanimous Veto = BLOCK                     │
├─────────────────────────────────────────────────────────────────┤
│                          VP / Manager                           │
│             Task decomposition • Worker assignment              │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Worker-α │  │ Worker-β │  │  Scout   │  │ Sentinel │        │
│  │ worktree │  │ worktree │  │ research │  │ monitor  │        │
│  └────┬─────┘  └────┬─────┘  └──────────┘  └──────────┘        │
│       │             │                                           │
│       ▼             ▼                                           │
│  ┌──────────────────────────────────────────────┐              │
│  │              Integration Queue               │              │
│  │         Reviewer → Integrator → main         │              │
│  └──────────────────────────────────────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│                    .coord/ State Directory                      │
│   tasks.json • queue.json • leases.json • events.jsonl         │
└─────────────────────────────────────────────────────────────────┘

Configuration

Create sauce.config.json:

{
  "workers": 2,
  "baseBranch": "main",
  "stagingBranch": "staging",
  "coordDir": ".coord",
  "skillRouting": true,
  "patternMemory": true
}

CLI Reference

# Project setup
sauce init                    # Initialize coordination
sauce setup --workers N       # Create N worker worktrees
sauce launch                  # Start the agent fleet

# Task management
sauce task create --title "..." --scope "src/**"
sauce task list [--status pending|assigned|completed]
sauce task claim --worker worker-alpha
sauce task complete --id T-0001

# Write guards
sauce claim --scope "src/**" --actor worker-alpha --intent "Refactoring"
sauce release --actor worker-alpha
sauce leases                  # Show active scope locks

# Integration queue
sauce queue list
sauce queue process           # Merge next approved item
sauce queue process --all     # Merge all approved items

# Worker management
sauce worker register --id worker-gamma --skills typescript,testing
sauce worker list
sauce status                  # System overview

Governance Layer

Sauce includes a governance subsystem for policy enforcement and audit:

import { evaluatePolicy, emitReceipt, sendDirectMessage } from "sauce";

// Policy evaluation before actions
const result = evaluatePolicy(
  { actor: "worker-alpha", action: "scope.acquire", scope: ["src/**"] },
  policyRules
);

if (result.decision === "deny") {
  console.error("Policy violation:", result.reasons);
}

// Audit trail
emitReceipt({
  kind: "task",
  subsystem: "worker",
  actor: "worker-alpha",
  data: { event: "task_started", taskId: "T-0001" }
});

// Typed messaging
sendDirectMessage("worker-alpha", "manager", "Task Complete", "T-0001 done");

Requirements

• Bun v1.0+
• Git 2.30+
• Claude Code CLI

Documentation

• Quick Start Guide — Get running in 5 minutes
• Architecture Overview — How Sauce works
• Role Definitions — Agent responsibilities
• CLI Reference — All commands documented
• Demo Script — Recording guide

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/c-1k/sauce
cd sauce
bun install
bun test

Roadmap

• [x] v0.1.0 — Core coordination, write guards, task queue
• [x] v0.1.0 — Governance layer (policy, audit, messaging)
• [x] v0.1.0 — Board of Directors oversight
• [ ] v0.2.0 — Web dashboard for monitoring
• [ ] v0.2.0 — Multi-repo coordination
• [ ] v0.3.0 — Self-healing task recovery

License

MIT — see LICENSE

Built by Sauce Labs — the first agent-run company.

Sauce is the secret ingredient between one AI agent and many.