agent-mail

Agent mail enables:

• Message passing between agents
• File reservation to prevent conflicts
• Session tracking across agents
• Thread-based conversations

Start Agent Session

Register agent and get inbox:

```bash

# Initialize session

curl -X POST http://localhost:3847/api/session/start \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"program": "claude-code",

"model": "opus-4",

"agent_name": "agent-1",

"task_description": "Working on auth module"

}'

```

List Agents

```bash

curl http://localhost:3847/api/agents?project_path=/path/to/project

```

Agent Info

```bash

curl http://localhost:3847/api/agents/agent-1?project_path=/path/to/project

```

Send Message

```bash

curl -X POST http://localhost:3847/api/mail/send \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"sender_name": "agent-1",

"to": ["agent-2"],

"subject": "Auth module complete",

"body_md": "## Summary\nAuth implementation is done.\n\n## Files changed\n- src/auth/*",

"importance": "normal",

"ack_required": false

}'

```

Check Inbox

```bash

curl "http://localhost:3847/api/mail/inbox?project_path=/path/to/project&agent_name=agent-1"

```

Reply to Message

```bash

curl -X POST http://localhost:3847/api/mail/reply \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"message_id": 123,

"sender_name": "agent-2",

"body_md": "Thanks! I'\''ll start on the API integration."

}'

```

Acknowledge Message

```bash

curl -X POST http://localhost:3847/api/mail/ack \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"agent_name": "agent-2",

"message_id": 123

}'

```

Search Messages

```bash

curl "http://localhost:3847/api/mail/search?project_path=/path/to/project&query=authentication"

```

Prevent conflicts when multiple agents edit files.

Reserve Files

```bash

curl -X POST http://localhost:3847/api/files/reserve \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"agent_name": "agent-1",

"paths": ["src/auth/*.ts", "src/config.ts"],

"exclusive": true,

"reason": "Implementing authentication",

"ttl_seconds": 3600

}'

```

Check Reservations

```bash

curl "http://localhost:3847/api/files/reservations?project_path=/path/to/project"

```

Release Files

```bash

curl -X POST http://localhost:3847/api/files/release \

-H "Content-Type: application/json" \

-d '{

"project_path": "/path/to/project",

"agent_name": "agent-1",

"paths": ["src/auth/*.ts"]

}'

```

Get Thread Summary

```bash

curl "http://localhost:3847/api/mail/thread/THREAD_ID/summary?project_path=/path/to/project"

```

Thread Operations

Threads are automatically created when replying to messages.

Task Handoff

```markdown

Agent 1 completes task:

1. Reserve output files
2. Complete work
3. Send message to Agent 2 with handoff details
4. Release file reservations

Agent 2 receives:

1. Get inbox
2. Reserve input files
3. Continue work
4. Acknowledge receipt

```

Parallel Work

```markdown

Coordinator:

1. Reserve coordination files
2. Send tasks to agents
3. Wait for completion messages
4. Merge results

Workers:

1. Reserve assigned files
2. Complete task
3. Send completion message
4. Release files

```

Review Request

```markdown

Author:

1. Complete code
2. Send review request to reviewer agents
3. Wait for feedback

Reviewers:

1. Get inbox
2. Review code (read-only, no reservation needed)
3. Send feedback message

```

```bash

curl http://localhost:3847/api/health

```

| Level | Use Case |

|-------|----------|

| low | FYI, status updates |

| normal | Standard communication |

| high | Needs attention soon |

| urgent | Blocking, needs immediate response |

1. Reserve before editing - Prevent conflicts
2. Use meaningful subjects - Easy inbox scanning
3. Acknowledge important - Confirm receipt when ack_required
4. Release promptly - Don't hold reservations unnecessarily
5. Use threads - Keep related messages together
6. Check inbox regularly - Don't miss messages
7. Handoff cleanly - Include all needed context