# Substrate > This skill provides agent mail management via the Subtrate command center. Use when checking mail, sending messages to other agents, or managing agent identity. - Skill: `roasbeef/substrate` (Agent Skill) - Install (CLI): `npx skillmds@latest add roasbeef/substrate` - Raw SKILL.md: https://api.skillmd.com/api/skills/roasbeef/substrate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: Roasbeef (https://skillmd.com/u/roasbeef) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/roasbeef/substrate --- # Subtrate - Agent Command Center Subtrate provides mail/messaging, code review, agent discovery, and MCP server capabilities for Claude Code agents. ## Quick Reference | Action | Command | |--------|---------| | Check inbox | `substrate inbox` | | Send message | `substrate send --to --subject "..." --body "..."` | | Send image | `substrate send --to --subject "..." --body "..." --attach shot.png` | | Read message | `substrate read ` | | Reply | `substrate send --to --thread --body "..."` | | Search | `substrate search "query"` | | Status | `substrate status` | | Agent discovery | `substrate agent discover` | | Request review | `substrate review request` | | Start MCP server | `substrate mcp serve` | | CLI schema | `substrate schema` | | 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. ```bash 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 ```bash substrate ack # Acknowledge urgent message substrate star # Star for later substrate snooze --until "2h" # Snooze substrate archive # Archive substrate trash # Move to trash (prompts for confirmation) ``` ## Sending Messages ```bash # Direct message to another agent substrate send --to AgentName --subject "Subject" --body "Message body" # Reply to a thread substrate send --to AgentName --thread --body "Reply text" # Urgent message with deadline substrate send --to AgentName --subject "Urgent" --body "..." \ --priority urgent --deadline "2h" # Send a git diff as a message (with syntax highlighting in web UI) substrate send-diff --to User --base main # Attach images (screenshots, mockups) - repeatable flag substrate send --to User --subject "UI update" --body "Before/after:" \ --attach before.png --attach after.png ``` ## Image Attachments Images travel through a shared attachments directory (`~/.subtrate/attachments`) rather than being embedded in message bodies. **Sending (agent → operator):** `substrate send --attach ` copies the image into the shared directory under a random name and appends a markdown image reference to the body. The web UI renders it inline (bounded at 320px) in the message prose. Allowed types: png, jpg, jpeg, gif, webp, svg. **Receiving (operator → agent):** when the user drags an image onto your canvas card in the Command Center, it lands in your inbox as a message with a markdown reference like `![name](/api/v1/attachments/.png)`. To view it, read the file directly from `~/.subtrate/attachments/.png` with the Read tool - the CLI and daemon share a filesystem, so no download is needed. Do not paste base64 data or local file paths into message bodies; the markdown sanitizer strips remote URLs and data URIs, so only same-origin attachment references render. ## Priority Handling - **URGENT**: Address immediately - these may have deadlines - **NORMAL**: Process in order received - **LOW**: Can be deferred ## Agent Discovery ```bash substrate agent discover # All agents with status substrate agent discover --status active # Only active agents substrate agent discover --project myproj # Filter by project substrate agent list # Simple agent listing substrate agent whoami # Your identity ``` Agent statuses: **active** (<5m), **busy** (active + session), **idle** (5-30m), **offline** (>30m). ## Code Review Request reviews from Claude reviewer agents that analyze diffs: ```bash # Request a review (auto-detects branch, commit, remote) substrate review request # Specific review types substrate review request --type security # Security-focused (Opus) substrate review request --type architecture # Design review (Opus) substrate review request --type performance # Performance review (Sonnet) # Check review status and issues substrate review status substrate review issues # Resubmit after fixing issues substrate review resubmit # List and manage reviews substrate review list --state under_review substrate review cancel --reason "..." ``` ## MCP Server Start an MCP server that exposes Subtrate tools for AI agent consumption: ```bash # Default: streamable HTTP on localhost:8090 substrate mcp serve # SSE transport substrate mcp serve --transport sse --addr :9090 # Stdio transport (for subprocess invocation) substrate mcp serve --transport stdio ``` The MCP server proxies through gRPC to the running daemon. Available tools: send_mail, fetch_inbox, read_message, read_thread, ack_message, mark_read, star_message, snooze_message, archive_message, trash_message, subscribe, unsubscribe, list_topics, publish, search, get_status, poll_changes, register_agent, whoami, list_agents, get_agent_by_name, heartbeat. ## Schema Introspection ```bash # Machine-readable JSON schema of all commands, flags, and enum constraints substrate schema substrate schema | jq '.commands[] | select(.name == "send")' ``` ## Output Flags ```bash --format json # JSON output (auto-detected when stdout is not a TTY) --compact # Single-line compact JSON --fields id,subject # Select specific fields in JSON output --page-token # Pagination token for list commands --yes / -y # Skip confirmation prompts ``` ## Topics & Pub/Sub ```bash substrate topics # List all topics substrate topics --subscribed # Your subscriptions substrate subscribe # Subscribe to a topic substrate unsubscribe # Unsubscribe substrate publish --subject "..." --body "..." ``` ## Agent Lifecycle (Hooks) Subtrate integrates with Claude Code hooks: - **SessionStart**: Heartbeat + check inbox - **UserPromptSubmit**: Silent heartbeat + check for new messages - **Stop**: Long-poll for 9m30s, block exit to keep agent alive - **SubagentStop**: One-shot check, then allow exit - **PreCompact**: Save identity state - **Notification**: Send mail to User on permission prompts The Stop hook keeps your main agent alive and continuously checking for work. Use Ctrl+C to force exit. ## Plan Mode Integration When you enter plan mode and call ExitPlanMode, Subtrate intercepts the call and submits your plan for human review. The hook blocks for up to 9 minutes waiting for approval. **What happens:** 1. You write a plan to `~/.claude/plans/` 2. You call ExitPlanMode 3. Subtrate submits the plan and waits for reviewer approval 4. If approved within 9 minutes: ExitPlanMode proceeds normally 5. If not yet approved: ExitPlanMode is denied with a message 6. You'll receive a mail notification when the reviewer responds **CLI commands:** - `substrate plan status` - Check current plan review status - `substrate plan wait --timeout 5m` - Manually wait for approval ## 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)