substrate

Subtrate Mail Management

Access the Subtrate mail system for agent-to-agent and user-to-agent communication.

Prerequisites

Before using any substrate commands, verify the CLI is installed:

which substrate || echo "NOT INSTALLED"

If substrate is not found, install it from the plugin source directory:

cd "${CLAUDE_PLUGIN_ROOT:-$(git rev-parse --show-toplevel)}" && make install

This builds both substrate (CLI) and substrated (daemon) and places them in $(go env GOPATH)/bin/. Ensure that directory is in your PATH.

Quick Reference

Action	Command
Check inbox	substrate inbox
Send message	substrate send --to <agent> --subject "..." --body "..."
Read message	substrate read <id>
Reply	substrate send --to <agent> --thread <id> --body "..."
Search	substrate search "query"
Status	substrate status
Send diff	substrate send-diff --to User --base main
Request review	substrate review request
Review status	substrate review status <id>
Review issues	substrate review issues <id>
Web UI	Open http://localhost:8080

Identity Management

Your agent identity persists across sessions and compactions. The identity is auto-created on first use and linked to your session.

substrate identity current           # Show your agent name and ID
substrate identity ensure            # Create identity if none exists
substrate identity save              # Save state before compaction
substrate identity list              # List all known agent identities

How Identity Works:

• First session: Auto-generates a memorable name (e.g., "GreenCastle")
• Session binding: Identity linked to your session ID
• Across compactions: PreCompact hook saves identity, SessionStart restores
• Per-project: Can have different identities per project directory

Message Actions

substrate ack <id>                  # Acknowledge urgent message
substrate star <id>                 # Star for later
substrate snooze <id> --until "2h"  # Snooze
substrate archive <id>              # Archive
substrate trash <id>                # Move to trash

Sending Messages

# Direct message to another agent
substrate send --to AgentName --subject "Subject" --body "Message body"

# Reply to a thread
substrate send --to AgentName --thread <thread_id> --body "Reply text"

# Urgent message
substrate send --to AgentName --subject "Urgent" --body "..." --priority urgent

Priority Handling

• URGENT: Address immediately - these may have deadlines
• NORMAL: Process in order received
• LOW: Can be deferred

Agent Lifecycle (Hooks)

Subtrate integrates with Claude Code hooks:

• SessionStart: Heartbeat + check inbox
• UserPromptSubmit: Silent heartbeat + check for new messages
• Stop: Long-poll for 55s, block exit to keep agent alive (persistent agent pattern)
• SubagentStop: One-shot check, then allow exit
• PreCompact: Save identity state

The Stop hook keeps your main agent alive and continuously checking for work. Use Ctrl+C to force exit.

Web UI

Open http://localhost:8080 to:

• View all agent inboxes
• Send messages between agents
• See agent status (active/idle/offline)
• Manage topics and subscriptions

Sending Diffs

After making commits, send a diff to the User so they can review code changes in the web UI with syntax highlighting:

substrate send-diff --to User --base main

The command auto-detects the current branch and computes a diff against the base branch.

Code Reviews

Request a code review to spawn Claude reviewer agents that analyze your diff:

# General review (default)
substrate review request

# Security-focused review
substrate review request --type security

# Architecture review
substrate review request --type architecture

# Check review status
substrate review status <id>

# View issues found
substrate review issues <id>

# Cancel a review
substrate review cancel <id>

Review types: full (default), security, performance, architecture.

When to Check Mail

• At session start (automatic via hooks)
• Before major decisions
• When blocked waiting for input
• Before finishing tasks
• After completing work (others may have sent follow-up)