STOP. READ THIS ENTIRE SKILL.MD BEFORE CALLING ANY ENDPOINT.
Agent Inbox
File-based inter-agent messaging with headless dispatch and task-monitor integration.
Core Workflow
- Send: Agent A sends bug/request to project B with model + verification command
- Triage: AI classifies severity, adjusts priority/model, routes to project
- Dispatch: Headless agent spawns with specified model to fix the issue
- Track: Task-monitor shows real-time progress (0% → 25% → 50% → 75% → 100%)
- Verify: Test command runs before auto-ack — fails loop back to agent
- Thread: Reply/exchange threading for multi-message conversations
Setup
# Register projects (one-time)
.pi/skills/agent-inbox/agent-inbox register memory /home/user/workspace/memory
.pi/skills/agent-inbox/agent-inbox register scillm /home/user/workspace/litellm
# List / check
.pi/skills/agent-inbox/agent-inbox projects
.pi/skills/agent-inbox/agent-inbox whoami
Commands
| Command | Description |
|---|---|
register <name> <path> | Register a project |
unregister <name> | Remove a project |
projects [--json] | List registered projects |
whoami | Show detected project for cwd |
send --to PROJECT --type TYPE "msg" | Send message (types: bug, request, info, question) |
check [--project P] [--all] [--quiet] | Check inbox |
list [--project P] [--status S] [--json] | List messages |
read MSG_ID [--json] | Read a message |
ack MSG_ID [--note "..."] | Acknowledge/complete |
reply MSG_ID "msg" | Reply (auto-threads) |
thread THREAD_ID | View full exchange thread |
update-status MSG_ID STATUS [--note] | Update status manually |
triage classify --message "..." [--no-llm] | Manual triage classification |
triage route --message "..." | Auto-route by file paths |
triage log --msg-id ID | View triage decision log |
triage webhook-add --url URL --events E | Register webhook |
Send Options
| Option | Description | Default |
|---|---|---|
--model MODEL | AI model: sonnet, opus-4.5, codex-5.2, codex-5.2-high | sonnet |
--timeout MINUTES | Max agent work time | 30 |
--test COMMAND | Verification command before auto-ack | None |
--no-dispatch | Disable auto-spawn | False |
--context-file FILE | Attach file as context (repeatable) | None |
--priority PRIORITY | low, normal, high, critical | normal |
--no-triage | Skip AI triage | False |
--dry-run | Show message JSON without sending | False |
Model Selection
| Model | Use Case |
|---|---|
sonnet | Simple fixes, typos |
opus-4.5 | Complex analysis, architecture |
codex-5.2 | Standard bug fixes |
codex-5.2-high | Deep reasoning, race conditions |
AI Triage
Messages are auto-classified by severity:
- critical: crash, data loss, security, production down →
opus-4.5 - high: error, exception, failure, broken, regression →
opus-4.5 - medium: bug, issue, incorrect, unexpected →
sonnet - low: typo, cosmetic, enhancement, minor →
sonnet
Auto-routing extracts file paths from messages and matches against registered projects.
Status Progression
pending → dispatched (25%) → in_progress (50%) → needs_verification (75%) → done (100%)
Memory Pre-Hook
Dispatcher queries /memory before spawning to find similar bugs and prior solutions.
Proactive Checking
Agents should check inbox on session start, when switching projects, before major work, and when users mention another agent or project.
Storage
~/.agent-inbox/
├── pending/ # Unprocessed messages
├── done/ # Acknowledged messages
├── logs/ # Dispatch logs
├── task_states/ # Task-monitor state files
├── triage_logs/ # AI triage decision logs
├── webhooks.json # Registered webhooks
└── projects.json # Project registry
Examples
# Send bug with verification (spawns headless Opus agent, auto-acks if test passes)
python inbox.py send --to scillm --type bug --model opus-4.5 \
--test "pytest tests/test_providers.py -x" \
"Race condition in provider initialization"
# Attach context files
python inbox.py send --to scillm --type bug --model opus-4.5 \
--context-file src/server.py --context-file /tmp/traceback.txt \
"Server crash on startup"
# Check and process inbox
python inbox.py check --all
python inbox.py read scillm_abc123
python inbox.py ack scillm_abc123 --note "Fixed in commit abc123"
# Threaded exchange
python inbox.py reply scillm_abc123 "Can you provide the stack trace?"
python inbox.py thread scillm_abc123
Dispatcher Daemon
python dispatcher.py start # Background
python dispatcher.py start --foreground # Debug
python dispatcher.py status
python dispatcher.py stop
Environment Variables
| Variable | Description | Default |
|---|---|---|
AGENT_INBOX_DIR | Inbox directory | ~/.agent-inbox |
TASK_MONITOR_API_URL | Task-monitor URL | http://localhost:8765 |
CLAUDE_PROJECT | Current project name | auto-detected |
Integration with Claude Code Hooks
{
"hooks": {
"on_session_start": [
".pi/skills/agent-inbox/agent-inbox check --project $(basename $PWD) || true"
]
}
}