<h1 align="center">🎀 AgenticMail (Codex plugin)</h1>

> Drop-in OpenAI Codex CLI plugin for AgenticMail.
>
> Give every Codex agent its own real email address and phone number. Self-hosted. Runs entirely on the user's machine. Coordinate work across multiple agents using ordinary email threads.

## What this folder is

A complete Codex CLI plugin manifest that Codex's plugin loader can discover from `<CODEX_HOME>/plugins/agenticmail/`. Three flavors of install:

| Path | What gets written |
|---|---|
| **`npm install -g @agenticmail/codex` + `agenticmail-codex install`** *(recommended)* | Writes `[mcp_servers.agenticmail]` + `features.multi_agent_v2.enabled` into `~/.codex/config.toml`, registers SessionStart/UserPromptSubmit/Stop hooks in `~/.codex/hooks.json`, generates one `agenticmail-<name>.toml` per AgenticMail account into `~/.codex/agents/`. Idempotent. Bin name `agenticmail-codex-mail-hook`. |
| **`./scripts/install.sh`** | Same end state — script is a thin wrapper around `npx -y @agenticmail/codex install` so users without a global npm install can still run it. |
| **Marketplace / manual drop-in** | Copy this whole folder to `~/.codex/plugins/agenticmail/`. Codex's plugin loader auto-discovers `hooks/hooks.json` and `agents/*.toml` from plugin directories. You'll still need to copy the `[mcp_servers.agenticmail]` block from `mcp_servers.toml` into your `~/.codex/config.toml` (Codex doesn't currently merge plugin-shipped MCP entries automatically). |

The `npm install` path is the only one that writes a bridge agent into AgenticMail (so the MCP server has an identity to authenticate AS). The marketplace path leaves bridge provisioning as a manual step — `agenticmail account create codex --role=bridge`.

## Layout

```
plugin-codex/
  .codex-plugin/
    plugin.json           # plugin manifest (name, version, host, requires, writes, tools)
  hooks/
    hooks.json            # SessionStart + UserPromptSubmit + Stop entries
  agents/
    agenticmail-bridge.example.toml   # documentation template — NOT auto-discovered
                                       # (the real per-account .toml files are
                                       # generated by `agenticmail-codex install`
                                       # into ~/.codex/agents/)
  mcp_servers.toml        # TOML snippet to copy into ~/.codex/config.toml
  scripts/
    install.sh            # thin wrapper around `npx -y @agenticmail/codex install`
  README.md               # this file
```

## What Codex sees after install

1. **MCP tools** under `mcp__agenticmail__*` — the full ~60-tool surface (read/send/reply mail, manage folders/contacts/templates, dispatch tasks, manage SMS, gateway/domain setup). Tools that need a specific identity take an `_account` arg; the MCP server reads `AGENTICMAIL_ACCOUNT_KEYS_JSON` and authenticates as the named agent transparently.

2. **`spawn_agent` subagents** — one per AgenticMail account, listed in `~/.codex/agents/agenticmail-<name>.toml`. Invoke from inside any Codex session:

   ```
   spawn_agent({
     agent_type: "agenticmail-vesper",
     message: "Read the latest thread and reply if it's your turn."
   })
   ```

   The spawned subagent inherits the persona body written into its `developer_instructions` — it knows it's Vesper, its email is vesper@localhost, and every MCP call it makes carries `_account: "Vesper"`. Identity is enforced by the MCP server.

3. **Lifecycle hooks** — capabilities preamble re-injected on every `SessionStart` (including after auto-compact), inbox digest on `UserPromptSubmit`, force-continue on `Stop` when the bridge inbox has pending mail.

## What's NOT shipped in v0.1.0

- **No warm-process pool** for the dispatcher. Today every wake spawns a fresh `codex exec` process via `@openai/codex-sdk`. Keeping one Codex process alive per agent across wakes is a per-wake-latency optimization that we'll measure before building.
- **No `send_message` / `wait_agent` shortcut path.** When a Codex-hosted AgenticMail agent emails another Codex-hosted AgenticMail agent on the same machine, the message goes through SMTP/IMAP/IDLE/SSE like any other email rather than Codex's intra-runtime peer messaging. That's deliberate — the email audit trail survives across hosts (Claude Code teammate joining the thread, Hermes teammate joining the thread). v2 may add an opt-in fast-path for same-runtime peers if telemetry shows it matters.
- **No marketplace listing yet.** OpenAI hasn't published a plugin marketplace for Codex equivalent to Anthropic's plugin store; this manifest is the spec we'll submit when it ships.

## Links

- Main repo: https://github.com/agenticmail/agenticmail
- npm package that drives this plugin: [`@agenticmail/codex`](https://www.npmjs.com/package/@agenticmail/codex)
- Codex CLI (the host): https://github.com/openai/codex
- AgenticMail wiki (architecture, roadmap): https://github.com/agenticmail/agenticmail/wiki

## License

MIT. See LICENSE.
