substrate

Subtrate

Subtrate is a command center for orchestrating multiple Claude Code agents. It provides the messaging infrastructure that allows agents to communicate, coordinate, and persist across context compactions, turning isolated coding assistants into a collaborative workforce.

The Problem

When you run multiple Claude Code agents (perhaps one reviewing code while another implements features), they operate in complete isolation. They can't ask each other questions, share discoveries, or coordinate their work. Each agent is also ephemeral: when its context window fills up and compacts, it loses track of what it was doing.

Subtrate solves both problems. It gives agents a mail system to communicate and a hook system that keeps them alive and responsive. An agent working on authentication can message the agent handling the database schema. When you step away, agents don't just exit. They wait for new work, checking their inbox periodically.

How It Works

Subtrate integrates with Claude Code through its hook system. When an agent starts, Subtrate assigns it a persistent identity (like NobleLion@subtrate.e2e-testing) that survives across context compactions. The Stop hook keeps agents alive indefinitely, polling for new messages. When mail arrives, it gets injected into the agent's context as actionable work.

flowchart TB
    subgraph Agents["Claude Code Agents"]
        A1["Agent: NobleLion<br/>Working on: auth"]
        A2["Agent: SilverWolf<br/>Working on: api"]
        A3["Agent: CrimsonFox<br/>Working on: tests"]
    end

    subgraph Subtrate["Subtrate"]
        CLI["substrate CLI"]
        GRPC["gRPC Server :10009"]
        REST["REST Gateway /api/v1/"]
        Mail["Mail Service<br/>(Actor Pattern)"]
        Review["Review Service<br/>(FSM + Claude SDK)"]
        Queue["Local Queue<br/>(Store-and-Forward)"]
        DB[(SQLite<br/>WAL + FTS5)]
    end

    subgraph Web["Web UI :8080"]
        WEB["React SPA"]
        WS["WebSocket /ws"]
    end

    A1 <--> CLI
    A2 <--> CLI
    A3 <--> CLI

    CLI -->|online| GRPC
    CLI -.->|offline| Queue
    Queue -.->|reconnect| GRPC
    GRPC --> Mail
    GRPC --> Review
    REST --> GRPC
    WEB --> REST
    WEB --> WS
    Mail --> DB
    Review --> DB

The architecture is straightforward: agents communicate via the substrate CLI with a 3-tier fallback (gRPC → direct DB → local queue). Messages flow through an actor-based mail service into a SQLite database. The hook system ensures agents stay responsive and messages get delivered even when the daemon is unavailable.

Features

Code Reviews

Subtrate includes a native code review system that spawns isolated Claude Agent SDK reviewer agents to analyze diffs and return structured feedback.

• 4 review types: full, security, performance, architecture
• FSM-based workflow with iteration tracking
• Structured issue tracking with severity, file path, and line ranges
• Web UI for browsing reviews, iterations, and issues

See Code Reviews for the full workflow and CLI usage.

Diff Viewer

Send git diffs as messages with syntax highlighting in the web UI. Supports unified/split modes and fullscreen navigation with file sidebar.

substrate send-diff --session-id "$CLAUDE_SESSION_ID" --to User --base main

Store-and-Forward Queue

The CLI uses a 3-tier connection fallback so agents can operate even when the daemon is unavailable:

1. gRPC — Connects to the substrated daemon (preferred)
2. Direct DB — Opens the SQLite database directly
3. Local Queue — Stores operations offline with automatic delivery on reconnect

Queued operations include idempotency keys to prevent duplicates and TTL-based expiry.

Web UI

A React + TypeScript SPA with real-time WebSocket updates for inbox, agent status, sessions, reviews, and activity feed.

Quick Start

Installation

# Clone and build
git clone https://github.com/roasbeef/subtrate
cd subtrate
make build-all
make install

# Install Claude Code hooks (sets up persistent agent behavior)
substrate hooks install

# Verify installation
substrate hooks status

Basic Usage

# Check your inbox
substrate inbox

# Send a message to another agent
substrate send --to SilverWolf --subject "Need API review" --body "Can you look at the auth endpoints?"

# Read a specific message
substrate read 42

# Request a code review
substrate review request --session-id "$CLAUDE_SESSION_ID"

# Send a diff to the User
substrate send-diff --session-id "$CLAUDE_SESSION_ID" --to User

# Check overall status
substrate status

Starting the Web UI

make run    # Starts substrated with web UI on http://localhost:8080