Agent Inbox Skill

Simple file-based inter-agent message system. Allows agents working on different projects to communicate bugs, requests, and information without manual copy/paste.

When to Use

• Agent A finds a bug in project B's code
• Agent needs to request help from another project's agent
• Passing information between project workspaces
• Any cross-project agent communication

Running the Skill (No Global Install Needed)

The repo already includes a wrapper script (.agents/skills/agent-inbox/agent-inbox). Run it directly or invoke the Python entrypoint—no global install or PATH hacks required.

# Preferred: run the bundled wrapper
.agents/skills/agent-inbox/agent-inbox check

# Alternate: call Python explicitly
python .agents/skills/agent-inbox/inbox.py check

If you want convenience aliases, you can add the skill folder to PATH, but it’s optional and not assumed anywhere in this doc.

Setup (One-Time)

Register your projects so agent-inbox knows where they are:

# Register projects (use direct path if agent-inbox not on PATH)
.agents/skills/agent-inbox/agent-inbox register memory /home/user/workspace/memory
.agents/skills/agent-inbox/agent-inbox register scillm /home/user/workspace/litellm

# List registered projects
.agents/skills/agent-inbox/agent-inbox projects

# Check which project current directory maps to
.agents/skills/agent-inbox/agent-inbox whoami

# Unregister if needed
.agents/skills/agent-inbox/agent-inbox unregister old-project

Quick Start

# Send a bug report to the scillm project
.agents/skills/agent-inbox/agent-inbox send --to scillm --type bug --priority high "
File: scillm/extras/providers.py:328
Error: UnboundLocalError on 'options'
Fix: Rename local variable to avoid shadowing
"

# Check for pending messages (anytime)
.agents/skills/agent-inbox/agent-inbox check

# List all pending messages
.agents/skills/agent-inbox/agent-inbox list

# Read a specific message
.agents/skills/agent-inbox/agent-inbox read scillm_abc123

# Acknowledge when fixed
.agents/skills/agent-inbox/agent-inbox ack scillm_abc123 --note "Fixed: renamed to merged_options"

CLI Commands (Wrapper ≙ python inbox.py)

register - Register a project (one-time setup)

.agents/skills/agent-inbox/agent-inbox register <name> <path>

# Examples:
.agents/skills/agent-inbox/agent-inbox register memory /home/user/workspace/memory
.agents/skills/agent-inbox/agent-inbox register scillm /home/user/workspace/litellm

unregister - Remove a project

.agents/skills/agent-inbox/agent-inbox unregister <name>

projects - List registered projects

.agents/skills/agent-inbox/agent-inbox projects
.agents/skills/agent-inbox/agent-inbox projects --json

whoami - Show detected project for current directory

.agents/skills/agent-inbox/agent-inbox whoami

send - Send a message to another project

.agents/skills/agent-inbox/agent-inbox send --to PROJECT --type TYPE --priority PRIORITY "message"

# Types: bug, request, info, question
# Priority: low, normal, high, critical

# Examples:
.agents/skills/agent-inbox/agent-inbox send --to memory --type request "Please add 'proved_only' parameter to search()"
.agents/skills/agent-inbox/agent-inbox send --to scillm --type bug --priority critical "Server crashes on startup"

# Read message from stdin (useful for multi-line)
cat error.log | .agents/skills/agent-inbox/agent-inbox send --to scillm --type bug

list - List messages

.agents/skills/agent-inbox/agent-inbox list                      # All pending
.agents/skills/agent-inbox/agent-inbox list --project scillm     # For specific project
.agents/skills/agent-inbox/agent-inbox list --status done        # Completed messages
.agents/skills/agent-inbox/agent-inbox list --json               # JSON output

read - Read a specific message

.agents/skills/agent-inbox/agent-inbox read MSG_ID
.agents/skills/agent-inbox/agent-inbox read MSG_ID --json

ack - Acknowledge/complete a message

.agents/skills/agent-inbox/agent-inbox ack MSG_ID
.agents/skills/agent-inbox/agent-inbox ack MSG_ID --note "Fixed in commit abc123"

check - Check inbox (for hooks)

.agents/skills/agent-inbox/agent-inbox check                     # Check all
.agents/skills/agent-inbox/agent-inbox check --project scillm    # Check specific project
.agents/skills/agent-inbox/agent-inbox check --quiet             # Just return count (exit code 1 if messages)

Integration with Claude Code Hooks

Add to your project's .claude/settings.json:

{
  "hooks": {
    "on_session_start": [
      ".agents/skills/agent-inbox/agent-inbox check --project $(basename $PWD) || true"
    ]
  }
}

Or add to your shell profile to check on every new terminal:

# ~/.bashrc or ~/.zshrc
alias claude-start='.agents/skills/agent-inbox/agent-inbox check --project $(basename $PWD); claude'

Message Format

Messages are stored as JSON in ~/.agent-inbox/:

~/.agent-inbox/
├── pending/
│   └── scillm_abc123.json
└── done/
    └── memory_def456.json

Each message:

{
  "id": "scillm_abc123",
  "to": "scillm",
  "from": "extractor",
  "type": "bug",
  "priority": "high",
  "status": "pending",
  "created_at": "2026-01-11T20:30:00Z",
  "message": "File: providers.py:328\nError: UnboundLocalError..."
}

Environment Variables

Workflow Example

Agent A (extractor project) finds bug:

.agents/skills/agent-inbox/agent-inbox send --to scillm --type bug --priority high "
Bug in scillm/extras/providers.py:328

Error: UnboundLocalError: cannot access local variable 'options'

The _worker function references 'options' on line 328 before it's
assigned on line 345. This is because the assignment makes Python
treat it as a local variable throughout the function.

Suggested fix: Rename line 345 'options = dict(options or {})' to
'merged_options = dict(options or {})' and update subsequent references.
"

User switches to scillm project:

cd /path/to/scillm
claude  # Or .agents/skills/agent-inbox/agent-inbox check runs automatically via hook

Agent B (scillm project) sees message:

=== 1 pending message(s) ===
Project: scillm

[HIGH]
  scillm_a1b2c3d4: bug from extractor
    Bug in scillm/extras/providers.py:328...

Agent B fixes and acknowledges:

.agents/skills/agent-inbox/agent-inbox ack scillm_a1b2c3d4 --note "Fixed: renamed to merged_options in commit abc123"

Python API

from inbox import (
    register_project, unregister_project, list_projects,
    send, list_messages, read_message, ack_message, check_inbox
)

# Setup (one-time)
register_project("memory", "/home/user/workspace/memory")
register_project("scillm", "/home/user/workspace/litellm")
list_projects()  # {"memory": "/home/...", "scillm": "/home/..."}

# Send
send("scillm", "Bug report...", msg_type="bug", priority="high")

# List
messages = list_messages(project="scillm")

# Read
msg = read_message("scillm_abc123")

# Ack
ack_message("scillm_abc123", note="Fixed")

# Check (returns count)
count = check_inbox(project="scillm", quiet=True)