agent-mail

Name: agent-mail
Author: Dicklesworthstone

78installs13forks

How to install agent-mail?

dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations/agent-mail

$npx -y skills add Dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill agent-mail

Installs into the current project.

Summary

MCP Agent Mail - Mail-like coordination layer for multi-agent workflows. Identities, inbox/outbox, file reservations, contact policies, threaded messaging, pre-commit guard, Human Overseer, static exports, disaster recovery. Git+SQLite backed. Python/FastMCP.

Files · 1

View on GitHub

SKILL.md

1	# MCP Agent Mail
2
3	A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).
4
5	## Why This Exists
6
7	Without coordination, multiple agents:
8	- Overwrite each other's edits or panic on unexpected diffs
9	- Miss critical context from parallel workstreams
10	- Require humans to relay messages between tools
11
12	Agent Mail solves this with:
13	- Memorable identities (adjective+noun names like "GreenCastle")
14	- Advisory file reservations to signal editing intent
15	- Threaded messaging with importance levels and acknowledgments
16	- Pre-commit guard to enforce reservations at commit time
17	- Human Overseer for direct human-to-agent communication
18
19	## Starting the Server
20
21	```bash
22	# Quickest way (alias added during install)
23	am
24
25	# Or manually
26	cd ~/projects/mcp_agent_mail
27	./scripts/run_server_with_token.sh
28	```
29
30	Default: `http://127.0.0.1:8765`
31	Web UI for humans: `http://127.0.0.1:8765/mail`
32
33	## Core Concepts
34
35	### Projects
36	Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same `project_key` for agents that need to coordinate.
37
38	### Agent Identity
39	Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.
40
41	### File Reservations (Leases)
42	Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.
43
44	### Contact Policies
45	Per-agent policies control who can message whom:
46
47	\| Policy \| Behavior \|
48	\|--------\|----------\|
49	\| `open` \| Accept any message in the project \|
50	\| `auto` (default) \| Allow if shared context exists (same thread, overlapping reservations, recent contact) \|
51	\| `contacts_only` \| Require explicit contact approval first \|
52	\| `block_all` \| Reject all new contacts \|
53
54	### Messages
55	GitHub-Flavored Markdown with threading, importance levels (`low`, `normal`, `high`, `urgent`), and optional acknowledgment requirements. Images are auto-converted to WebP.
56
57	## Essential Workflow
58
59	### 1. Start Session (One-Call Bootstrap)
60
61	```
62	macro_start_session(
63	human_key="/abs/path/to/project",
64	program="claude-code",
65	model="opus-4.5",
66	task_description="Implementing auth module"
67	)
68	```
69
70	Returns: `{project, agent, file_reservations, inbox}`
71
72	This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.
73
74	### 2. Reserve Files Before Editing
75
76	```
77	file_reservation_paths(
78	project_key="/abs/path/to/project",
79	agent_name="GreenCastle",
80	paths=["src/auth/*/.ts", "src/middleware/auth.ts"],
81	ttl_seconds=3600,
82	exclusive=true,
83	reason="br-123"
84	)
85	```
86
87	Returns: `{granted: [...], conflicts: [...]}`
88
89	Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.
90
91	### 3. Announce Your Work
92
93	```
94	send_message(
95	project_key="/abs/path/to/project",
96	sender_name="GreenCastle",
97	to=["BlueLake"],
98	subject="[br-123] Starting auth refactor",
99	body_md="Reserving src/auth/**. Will update session handling.",
100	thread_id="br-123",
101	importance="normal",
102	ack_required=true
103	)
104	```
105
106	### 4. Check Inbox Periodically
107
108	```
109	fetch_inbox(
110	project_key="/abs/path/to/project",
111	agent_name="GreenCastle",
112	limit=20,
113	urgent_only=false,
114	include_bodies=true
115	)
116	```
117
118	Or use resources for fast reads:
119	```
120	resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true
121	```
122
123	### 5. Release Reservations When Done
124
125	```
126	release_file_reservations(
127	project_key="/abs/path/to/project",
128	agent_name="GreenCastle"
129	)
130	```
131
132	## The Four Macros
133
134	Prefer macros for speed and smaller models. Use granular tools when you need fine control.
135
136	\| Macro \| Purpose \|
137	\|-------\|---------\|
138	\| `macro_start_session` \| Bootstrap: ensure project → register agent → optional file reservations → fetch inbox \|
139	\| `macro_prepare_thread` \| Join existing conversation: register → summarize thread → fetch inbox context \|
140	\| `macro_file_reservation_cycle` \| Reserve files, do work, optionally auto-release when done \|
141	\| `macro_contact_handshake` \| Request contact permission, optionally auto-accept, send welcome message \|
142
143	## Beads Integration (br-### Workflow)
144
145	When using Beads for task management, keep identifiers aligned:
146
147	```
148	1. Pick ready work: br ready --json → choose br-123
149	2. Reserve files: file_reservation_paths(..., reaso

People who liked this also viewed

6 picks

Type

agent-mail

78installs13forks

View on GitHub

How to install agent-mail?

dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations/agent-mail

$npx -y skills add Dicklesworthstone/agent_flywheel_clawdbot_skills_and_integrations --skill agent-mail

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# MCP Agent Mail
2
3	A mail-like coordination layer for coding agents exposed as an HTTP-only FastMCP server. Provides memorable identities, inbox/outbox, file reservation leases, contact policies, searchable message history, and Human Overseer messaging. Backed by Git (human-auditable artifacts) and SQLite (fast queries with FTS5).
4
5	## Why This Exists
6
7	Without coordination, multiple agents:
8	- Overwrite each other's edits or panic on unexpected diffs
9	- Miss critical context from parallel workstreams
10	- Require humans to relay messages between tools
11
12	Agent Mail solves this with:
13	- Memorable identities (adjective+noun names like "GreenCastle")
14	- Advisory file reservations to signal editing intent
15	- Threaded messaging with importance levels and acknowledgments
16	- Pre-commit guard to enforce reservations at commit time
17	- Human Overseer for direct human-to-agent communication
18
19	## Starting the Server
20
21	```bash
22	# Quickest way (alias added during install)
23	am
24
25	# Or manually
26	cd ~/projects/mcp_agent_mail
27	./scripts/run_server_with_token.sh
28	```
29
30	Default: `http://127.0.0.1:8765`
31	Web UI for humans: `http://127.0.0.1:8765/mail`
32
33	## Core Concepts
34
35	### Projects
36	Each working directory (absolute path) is a project. Agents in the same directory share a project namespace. Use the same `project_key` for agents that need to coordinate.
37
38	### Agent Identity
39	Agents register with adjective+noun names (GreenCastle, BlueLake). Names are unique per project, memorable, and appear in inboxes, commit logs, and the web UI.
40
41	### File Reservations (Leases)
42	Advisory locks on file paths or globs. Before editing files, reserve them to signal intent. Other agents see the reservation and can choose different work. The optional pre-commit guard blocks commits that conflict with others' exclusive reservations.
43
44	### Contact Policies
45	Per-agent policies control who can message whom:
46
47	\| Policy \| Behavior \|
48	\|--------\|----------\|
49	\| `open` \| Accept any message in the project \|
50	\| `auto` (default) \| Allow if shared context exists (same thread, overlapping reservations, recent contact) \|
51	\| `contacts_only` \| Require explicit contact approval first \|
52	\| `block_all` \| Reject all new contacts \|
53
54	### Messages
55	GitHub-Flavored Markdown with threading, importance levels (`low`, `normal`, `high`, `urgent`), and optional acknowledgment requirements. Images are auto-converted to WebP.
56
57	## Essential Workflow
58
59	### 1. Start Session (One-Call Bootstrap)
60
61	```
62	macro_start_session(
63	human_key="/abs/path/to/project",
64	program="claude-code",
65	model="opus-4.5",
66	task_description="Implementing auth module"
67	)
68	```
69
70	Returns: `{project, agent, file_reservations, inbox}`
71
72	This single call: ensures project exists, registers your identity, optionally reserves files, fetches your inbox.
73
74	### 2. Reserve Files Before Editing
75
76	```
77	file_reservation_paths(
78	project_key="/abs/path/to/project",
79	agent_name="GreenCastle",
80	paths=["src/auth/*/.ts", "src/middleware/auth.ts"],
81	ttl_seconds=3600,
82	exclusive=true,
83	reason="br-123"
84	)
85	```
86
87	Returns: `{granted: [...], conflicts: [...]}`
88
89	Conflicts are reported but reservations are still granted. Check conflicts and coordinate if needed.
90
91	### 3. Announce Your Work
92
93	```
94	send_message(
95	project_key="/abs/path/to/project",
96	sender_name="GreenCastle",
97	to=["BlueLake"],
98	subject="[br-123] Starting auth refactor",
99	body_md="Reserving src/auth/**. Will update session handling.",
100	thread_id="br-123",
101	importance="normal",
102	ack_required=true
103	)
104	```
105
106	### 4. Check Inbox Periodically
107
108	```
109	fetch_inbox(
110	project_key="/abs/path/to/project",
111	agent_name="GreenCastle",
112	limit=20,
113	urgent_only=false,
114	include_bodies=true
115	)
116	```
117
118	Or use resources for fast reads:
119	```
120	resource://inbox/GreenCastle?project=/abs/path&limit=20&include_bodies=true
121	```
122
123	### 5. Release Reservations When Done
124
125	```
126	release_file_reservations(
127	project_key="/abs/path/to/project",
128	agent_name="GreenCastle"
129	)
130	```
131
132	## The Four Macros
133
134	Prefer macros for speed and smaller models. Use granular tools when you need fine control.
135
136	\| Macro \| Purpose \|
137	\|-------\|---------\|
138	\| `macro_start_session` \| Bootstrap: ensure project → register agent → optional file reservations → fetch inbox \|
139	\| `macro_prepare_thread` \| Join existing conversation: register → summarize thread → fetch inbox context \|
140	\| `macro_file_reservation_cycle` \| Reserve files, do work, optionally auto-release when done \|
141	\| `macro_contact_handshake` \| Request contact permission, optionally auto-accept, send welcome message \|
142
143	## Beads Integration (br-### Workflow)
144
145	When using Beads for task management, keep identifiers aligned:
146
147	```
148	1. Pick ready work: br ready --json → choose br-123
149	2. Reserve files: file_reservation_paths(..., reaso

People who liked this also viewed

6 picks

Type