MCP Agent Mail + Companion Docs

Install in one command

Run the curl installer to set up uv, create a Python 3.14 venv, configure the MCP server, and launch it on port 8765 with a masked bearer token. Use --port, --dir, or --token flags to customize.

curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/mcp_agent_mail/main/scripts/install.sh | bash -s -- --yes

Manual setup

Clone the repo, install uv, create a venv, run uv sync, and execute scripts/automatically_detect_all_installed_coding_agents_and_install_mcp_agent_mail_in_all.sh to wire every local coding agent.

git clone https://github.com/Dicklesworthstone/mcp_agent_mail
cd mcp_agent_mail
uv python install 3.14 && uv venv -p 3.14
source .venv/bin/activate && uv sync

Core capabilities

• Memorable agent identities with inbox/outbox history stored in Git + SQLite (FTS5 search).
• Advisory file reservations (leases) so agents declare edit intent and avoid collisions.
• Human Overseer messaging, attachments, and resources (resource://inbox, thread, etc.).
• Macros for common workflows: macro_start_session, macro_prepare_thread, macro_file_reservation_cycle, macro_contact_handshake.
• Threads aligned with Beads IDs so tasks, commits, and reservations stay in lockstep.

Best practices

• Register an identity per repo (`ensure_project` + `register_agent`).
• Reserve files before editing; release or renew with TTL when done.
• Use shared thread IDs (ticket IDs, Beads IDs) for easy auditing.
• Prefer macros on smaller models; drop to granular tools for fine control.

Mobile control center

SwiftUI app with widgets, Siri shortcuts, offline cache, and push notifications so you can review agent mail, plan docs, and reservations from anywhere.

Message Stacks Composer

Design multi-step prompt cadences (Builder Loop, Reviewer Sweep, Test Focus) with gates, spacing, variable previews, and dry-run audits before launching from your phone.

Preset workflows

Launch tmux-based squads (Claude Code, Codex, Gemini CLI) with declarative YAML/JSON presets. Broadcast grouped prompts and Human Overseer messages without hopping between terminals.

Plan docs + Beads

Edit plan documents, move Beads tasks, and search agent mail directly from the iOS UI. Vibe coding stays mobile while the host keeps executing.

Double-Arm safety

• Typed confirmation + Face ID for destructive runs or large target sets.
• Requires reservations/Limited Mode awareness before impactful steps advance.
• All actions log signed receipts back into Git.

Pricing & trial

• Introductory offer: $1.99 for the first month (App Store auto-renew).
• Standard subscription: $9.99/month, cancel anytime in iOS Settings.
• Works on iPhone/iPad (iOS 17+).

Host prerequisites

• Linux or macOS dev machine with Git 2.38+, tmux 3.0+, and uv.
• 2GB free disk, reliable network connectivity.
• Optional Cloudflare account for named tunnels, optional Tailscale/Headscale.

Installer workflow

Use `mcp-ios install --workspace ~/mcp-companion` to verify prerequisites, run the OSS setup, apply migrations, refresh configs, and generate launchd/systemd units. Pass --dry-run or --prereq-only for audits. Non-interactive runs use `--execute` plus provider flags (cloudflare, tailscale, lan).

Upgrade & status

`mcp-ios upgrade --workspace ~/mcp-companion` reuses the pipeline for in-place updates. `mcp-ios status` prints service and capability summaries with structured logs.

Security hardening

• Double-Arm confirmation: typed phrase + Face ID before destructive actions run.
• JWT/mTLS/HMAC for every request plus optional certificate pinning.
• Audit trail logged back into Git with timestamps and signatures.

Cloudflare Tunnel + Access

Provision named tunnels with Access policies so the iOS app reaches your host without opening ports. The daemon supervises tunnel health, rotates service tokens, and can host pairing QR codes.

Tailscale / Headscale

Use private tailnets for mTLS connectivity when you prefer self-hosted zero-trust. The automation scripts configure services and keep them online.

LAN & Bonjour fallback

For local-only setups, the companion can discover hosts on the same network using Bonjour. Ideal for rapid prototyping or air-gapped labs.

Observability & logs

Structured logging via Python logging, metrics endpoints, and health checks let you monitor the daemon, tmux agents, push relays, and tunnel state.

Stack schema

Stacks are named recipes of steps (messages) with selectors, spacing, repeat counts, and gates (stopOnLimitedMode, requireReservation, maxQueueDepth). Each execution emits immutable batch/run records and idempotent receipts.

Composer UX

• Card-based editor with repeat chips, spacing controls, and `${bead.id}/${thread_id}/${agent.name}` variable previews.
• Target agents by role/labels; preview queue depth and heartbeat before dispatch.
• Dry-run mode shows would-be enqueues and gate outcomes before any message leaves the device.

CLI + API triggers

`mcp-ios stacks run builder_loop --selectors roles=builder --wait-for-ack` launches the same preset from the host CLI. `/mobile/stacks` REST endpoints enable automation from CI or other tooling.

Safety + audit

• Typed phrase + Face ID required when target counts exceed safe thresholds.
• Every enqueue links back to Agent Mail threads and Beads IDs for traceability.
• Limited Mode gates pause stacks until human approval resumes the run.

Bootstrap 4-agent squad

1) Run the OSS installer. 2) Launch `mcp-ios wizard quickstart --provider cloudflare --execute`. 3) Pair iOS via QR. 4) Reserve `backend/**` + `frontend/**`. 5) Trigger Builder Loop + Reviewer Sweep stacks.

Send Human Overseer broadcast

`send_message(project_key, "HumanOverseer", to=["RedCat","BlueLake"], subject="[bd-482] Priority shift", body="...")` and require acknowledgements before stacks resume.

Check mail and leases from CLI

`mcp-ios mail inbox --agent GreenCastle --limit 10` plus `mcp-ios leases list --project /repo --active-only` keeps tmux panes clutter-free.

Trigger stack from CI

`mcp-ios stacks run reviewer_sweep --selectors roles=reviewer --wait-for-ack --thread bd-482` pushes reviewers without opening tmux.