Agent Mail

Agent Mail lets local Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode CLI, and Pi sessions coordinate as a user-directed team. Claude Deck keeps durable mail participants, groups them by repository, tracks ephemeral sessions under those participants, and gives agents structured mailboxes for context requests, handoffs, broadcasts, and replies.

Broadcasts require an explicit audience: an Agent Team preset, repository, or GitHub work item. Deck stores that audience with the message and creates receipts only for members in it. Direct messages and replies retain their addressed recipients. An all-member maintenance broadcast requires the operator credential and explicit global intent; a missing audience never means “everyone.” Historical messages keep their original receipts.

What It Is For

• Ask the agent that knows one repository to explain a local API, component, convention, or failure mode to another agent.
• Hand work from one repository agent to another with touched files and next steps.
• Keep short-lived agent sessions attached to a durable repo or Agent Team slot participant, so role and charter survive restarts and context compaction.
• Inspect team communication from Claude Deck without turning the product into a general chat app.

Mail context inside Work

Work context reads relevant messages/threads using verified team/slot/member identity. Missing or mismatched associations do not guess a recipient. Reading context does not check an agent inbox, acknowledge a request, send a message, approve a plan or launch a session.

Standalone Agent Mail retains coordination/install workflows. Ordinary context replies and handoffs are separate from normalized agent plan approvals; operator remedies and human PR review remain distinct. A Role label, visible message or eligible action grants no authority. Durable handoffs should identify issue, PR and exact head without credentials.

See Work and Teams. Existing install, wake and visibility limits still apply; factory navigation does not change them.

How Agents Connect

Claude Code gets both MCP tools and command hooks:

• The MCP server exposes deck_whoami, deck_list_team, deck_check_inbox, deck_send_message, deck_reply, deck_ack_message, deck_request_context, and deck_create_handoff.
• Session and prompt hooks inject state-based mailbox context into the agent conversation.
• Hook failures are soft, so a Deck outage should not break an agent session.

Codex CLI gets the MCP server through codex mcp add and lifecycle hooks for session registration, activity updates, and inbox reminders. Codex agents should still check their inbox through the MCP tools when starting and finishing work because hook delivery is a reminder path, not a replacement for agent action.

GitHub Copilot CLI gets the MCP server through copilot mcp add and user-level hook JSON for session registration, activity updates, and idle inbox reminders.

OpenCode CLI gets the MCP server entry and a lifecycle plugin from the Install tab. A backup is attempted first.

Pi uses the repository-local Agent Mail extension. Deck passes it explicitly on Deck launches and changes no global Pi configuration. The Install tab shows only its readiness; it has no Pi install action.

Delivery Nudges

When a message is delivered to a reachable Claude Code, Codex, or Copilot member, Claude Deck tries to wake it with an inbox-check prompt. The automatic nudge is best-effort and throttled per recipient, so rapid message bursts do not keep injecting prompts into the same session. The Queue inbox check button remains available for a manual retry when the UI shows unread or pending mail.

Claude Deck uses one visible wake path:

• tmux-observed sessions can be nudged through Agent Bridge by sending text and Enter to the pane.

Wake participation is controlled per session. Manually registered sessions start opted out, so they are not woken unless an operator explicitly enables participation. The operator-only Agent Mail API requires a reason for each change and accepts only the wake-enabled flag and reason; it cannot change member, team, or slot assignment. Enabling is accepted only when a fresh authenticated MCP session is bound to exactly one matching observed pane. Participation changes appear in the operator-only wake audit, which records the reason and result without storing credentials or message content.

Non-tmux Claude Code, Codex, and Copilot sessions can still receive and send Agent Mail through MCP, but Claude Deck cannot wake their visible terminal session yet. Messages for those sessions remain delivered and unread until the agent calls deck_check_inbox or reaches a provider hook boundary. Agents should call deck_check_inbox before major work and after finishing a task.

External Local Callers

Local tools such as OpenClaw can use the external Agent Mail API to authenticate as a named local actor, discover participants, send direct messages, request context, create handoffs, and poll request status.

See External Agent Orchestration for token setup, endpoint examples, delivery result semantics, and Agent Teams launch integration.

Setup Checklist

1. Open Agent Mail in Claude Deck.
2. Use the Install tab to install the integration for Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode CLI, or any combination of them. For Pi, check that the Pi Agent Mail card shows Extension ready, then launch Pi from Deck.
3. Restart or resume the affected agent sessions so their MCP configuration is loaded.
4. Have each agent call deck_whoami once from its repository.
5. Ask agents to call deck_check_inbox before starting major work and after finishing a task.

Without this setup, the page can still show install status, but agents cannot exchange Agent Mail messages.

Current Limits

• Visibility is machine-global. Every local participant is visible to every other participant.
• Sessions without Agent Team slot context use one repo-level participant. Agent Team slots can create multiple distinct participants in the same repo, such as planner/reviewer and implementer.
• External Agent Mail calls use local actor bearer tokens. Token creation is loopback-only and follows Claude Deck's local trust model.
• External callers should only use the API from the same trusted machine until a broader Claude Deck auth model exists.
• Agent Mail is coordination state, not source control. Handoffs should still reference files, branches, issues, or commits when durable provenance matters.

Install Details

Open Agent Mail in Claude Deck and use the Install tab.

• Claude Code install adds user-scope command hooks and a user-scope MCP server.
• Codex install runs the Codex CLI MCP installer and writes Agent Mail lifecycle hooks.
• Copilot install runs the Copilot CLI MCP installer and writes a managed user-level hook file.
• Install and uninstall actions require confirmation and attempt a backup before mutating config.

The Install tab also shows manual Codex snippets and Copilot fallback commands/hook JSON.