@agenticmail/cli 0.5.62 → 0.6.0

package/README.md

@@ -95,6 +95,7 @@ All commands are available via `agenticmail <command>` or `npx @agenticmail/cli@
 | Command | Description |
 |---------|-------------|
 | `agenticmail openclaw` | **Set up AgenticMail for OpenClaw.** Starts infrastructure, creates an agent, configures the plugin, enables agent auto-spawn via hooks, and restarts the OpenClaw gateway. |
+| `agenticmail claudecode` | **Set up AgenticMail for Claude Code.** ✨ NEW — wires AgenticMail into Claude Code so every agent (Fola, John, …) becomes a callable subagent via the `Agent` tool, AND wakes automatically on incoming mail or tasks. No separate Anthropic key needed — workers ride on your existing Claude OAuth. See the [Claude Code Integration](#claude-code-integration) section below. |
 
 ### Service Management (Auto-Start on Boot)
 
@@ -352,6 +353,73 @@ The `call_agent` tool intelligently spawns sub-agents with:
 
 ---
 
+## Claude Code Integration
+
+> ✨ **New in 0.6** — `@agenticmail/claudecode` brings the full AgenticMail multi-agent platform inside [Claude Code](https://claude.com/claude-code). Every AgenticMail agent becomes a callable Claude Code subagent, and agents auto-wake on incoming mail or tasks. **No separate Anthropic API key required — workers reuse your existing Claude OAuth.**
+
+```bash
+agenticmail claudecode             # install
+agenticmail claudecode --status    # check
+agenticmail claudecode --remove    # uninstall
+```
+
+### What it gives you
+
+- **Every AgenticMail agent is callable from Claude Code via the native `Agent` tool.**
+  Inside any Claude Code session: `Agent { subagent_type: "agenticmail-fola", prompt: "..." }` — the subagent IS Fola, reads Fola's real inbox, sends mail from `fola@localhost`.
+
+- **All 62 AgenticMail MCP tools available in Claude Code.**
+  `mcp__agenticmail__send_email`, `call_agent`, `list_inbox`, `sms_send`, … — works in any Claude Code session, no further setup.
+
+- **Auto-wake on inbox / task events.**
+  Send an email to `fola@localhost`, post a `/tasks/rpc` for Fola, or `CC` her on a thread — a background dispatcher daemon (managed by PM2) spawns a Claude-powered worker to handle it. The worker submits results / replies; threads keep flowing.
+
+- **Multi-agent coordination on email threads.**
+  Because every cross-agent reply lands in the recipient's inbox and wakes them, fan-out (CC three teammates) and reply chains "just work." No new infrastructure to learn — it's email.
+
+- **Provision agents on the fly.**
+  `mcp__agenticmail__create_account({ name: "worker-7" })` — the new agent's API key is resolved on-demand by the MCP server, and the dispatcher picks it up within ~1 minute. No restart required.
+
+- **Headless HTTP install endpoint** at `POST /api/agenticmail/integrations/claudecode/install`.
+  Lets an agent (or any script) wire itself in with a single curl. No master key needed for the install endpoint — see security model in the [package README](https://www.npmjs.com/package/@agenticmail/claudecode).
+
+### The "Claude Code is the brain" architecture
+
+Each AgenticMail agent is a mailbox + persistent state + identity inside AgenticMail. This integration supplies the *thinking* by spawning a fresh Claude Code session for each wake — that session uses Claude Code's own Claude OAuth (the same auth `claude` itself uses), operates the target agent's mailbox via MCP tools scoped with `_account: "<name>"`, and exits when done.
+
+```
+Anyone (you, an agent, a curl):
+   send mail to fola@localhost         POST /tasks/rpc { target: "Fola", task: ... }
+              │                                      │
+              ▼                                      ▼
+   AgenticMail master API           ──── task event ────→ dispatcher daemon (PM2)
+              │                                      │
+              │           SSE for fola's inbox       ▼
+              └──────────────────────────────→ spawns worker via Claude Agent SDK
+                                                     │
+                                                     ▼
+                                         Worker IS Fola for this turn:
+                                         - reads inbox / claims task
+                                         - sends mail / submits result
+                                         - exits
+```
+
+One Anthropic connection (your Claude OAuth). Many AgenticMail identities. Real email between them, real task RPC, real persistence.
+
+### Quick example
+
+After `agenticmail claudecode`, restart Claude Code and try in any session:
+
+```
+Agent { subagent_type: "agenticmail-fola", prompt: "Use call_agent to ask the 'researcher' agent to summarise AgenticMail in two sentences, then email me the summary." }
+```
+
+Fola will use the AgenticMail RPC pipeline to delegate to `researcher`, get a structured result back, and email the summary to her caller — all powered by Claude Code's OAuth, no separate keys, no broken enterprise dependencies.
+
+See [`@agenticmail/claudecode` on npm](https://www.npmjs.com/package/@agenticmail/claudecode) for the full design doc, security model, and HTTP API reference.
+
+---
+
 ## Programmatic Usage
 
 The package re-exports everything from `@agenticmail/core`, so you can use it as an SDK:

package/dist/cli.js

@@ -5591,6 +5591,117 @@ function mergePluginConfig(existing, apiUrl, masterKey, agentApiKey, pluginDir)
   }
   return result;
 }
+async function cmdClaudeCode() {
+  const sub = process.argv.slice(3);
+  if (sub.includes("--help") || sub.includes("-h") || sub.includes("help")) {
+    log2("");
+    log2(`  ${c2.pinkBg(" \u{1F380} AgenticMail for Claude Code ")}`);
+    log2("");
+    log2(`  ${c2.bold("Usage:")} agenticmail claudecode [flags]`);
+    log2("");
+    log2("  Registers AgenticMail with Claude Code so every Claude Code session");
+    log2("  can call AgenticMail agents (Fola, John, \u2026) the same way it calls");
+    log2("  native subagents via the Agent tool.");
+    log2("");
+    log2("  Specifically, this command:");
+    log2(`    ${c2.dim("1.")} Provisions a dedicated "claudecode" AgenticMail agent (Claude Code's identity)`);
+    log2(`    ${c2.dim("2.")} Writes an MCP server entry into ~/.claude.json`);
+    log2(`    ${c2.dim("3.")} Generates one Claude Code subagent file per AgenticMail agent`);
+    log2(`        (in ${c2.cyan("~/.claude/agents/agenticmail-<name>.md")})`);
+    log2("");
+    log2(`  ${c2.bold("Flags:")}`);
+    log2(`    ${c2.green("--status")}        Show what's currently installed and exit`);
+    log2(`    ${c2.green("--remove")}        Uninstall (keeps the bridge agent by default)`);
+    log2(`    ${c2.green("--purge-bridge")}  When used with --remove, also delete the bridge agent`);
+    log2(`    ${c2.green("-h, --help")}      Show this help and exit`);
+    log2("");
+    log2(`  After install, restart Claude Code so it picks up the new MCP server.`);
+    log2("");
+    return;
+  }
+  let mod;
+  try {
+    mod = await import("@agenticmail/claudecode");
+  } catch (err) {
+    fail2(`Could not load @agenticmail/claudecode: ${err.message}`);
+    log2("");
+    info2(`Install it with: ${c2.green("npm install -g @agenticmail/claudecode")}`);
+    process.exit(1);
+    return;
+  }
+  if (sub.includes("--status")) {
+    const s = await mod.status();
+    log2("");
+    log2(`  ${c2.pinkBg(" \u{1F380} AgenticMail for Claude Code ")}`);
+    log2("");
+    const stateLabel = s.state === "installed" ? c2.green("installed") : s.state === "partial" ? c2.yellow("partial") : c2.dim("not installed");
+    log2(`  Status: ${stateLabel}`);
+    log2(`  MCP server registered: ${s.mcpInstalled ? c2.green("yes") : c2.dim("no")}`);
+    log2(`  Bridge agent in AgenticMail: ${s.bridgeAgentExists ? c2.green("yes") : c2.dim("no")}`);
+    log2(`  Subagent files: ${s.subagents.length > 0 ? c2.green(String(s.subagents.length)) : c2.dim("0")}`);
+    if (s.subagents.length > 0) for (const name of s.subagents) info2(`  \u2022 ${name}`);
+    if (s.notes.length > 0) {
+      log2("");
+      log2(`  ${c2.bold("Notes:")}`);
+      for (const n of s.notes) info2(`  \u2022 ${n}`);
+    }
+    log2("");
+    process.exit(s.state === "installed" ? 0 : 1);
+  }
+  if (sub.includes("--remove") || sub.includes("--uninstall")) {
+    log2("");
+    log2(`  ${c2.pinkBg(" \u{1F380} Removing AgenticMail from Claude Code ")}`);
+    log2("");
+    const purgeBridge = sub.includes("--purge-bridge");
+    const result2 = await mod.uninstall({ purgeBridgeAgent: purgeBridge });
+    if (result2.mcpBlockRemoved) ok2("Removed MCP server entry from Claude Code config");
+    else info2("No MCP server entry was registered.");
+    if (result2.removedSubagents.length > 0) ok2(`Removed ${result2.removedSubagents.length} subagent file(s)`);
+    else info2("No subagent files were registered.");
+    if (result2.bridgeAgentDeleted) ok2("Deleted bridge agent from AgenticMail");
+    else if (purgeBridge) info2("Bridge agent could not be deleted (already gone or AgenticMail unreachable).");
+    log2("");
+    if (!result2.changed) info2("Nothing to remove.");
+    log2("");
+    return;
+  }
+  log2("");
+  log2(`  ${c2.pinkBg(" \u{1F380} AgenticMail for Claude Code ")}`);
+  log2("");
+  log2(`  ${c2.bold("Wiring AgenticMail into Claude Code.")} This will:`);
+  log2(`    ${c2.dim("1.")} Provision a "claudecode" agent inside AgenticMail`);
+  log2(`    ${c2.dim("2.")} Add an MCP server entry to ~/.claude.json`);
+  log2(`    ${c2.dim("3.")} Generate one Claude Code subagent file per AgenticMail agent`);
+  log2("");
+  const spinner = new Spinner("general", "Talking to AgenticMail\u2026");
+  spinner.start();
+  let result;
+  try {
+    result = await mod.install();
+    spinner.succeed("Integration installed");
+  } catch (err) {
+    spinner.fail(`Install failed: ${err.message}`);
+    log2("");
+    if (err.status === 0) {
+      info2(`Is the AgenticMail server running? Try: ${c2.green("agenticmail start")}`);
+    }
+    log2("");
+    process.exit(1);
+    return;
+  }
+  ok2(`Bridge agent ${c2.bold(result.bridgeAgent.name)} ${c2.dim("(" + result.bridgeAgent.email + ")")}`);
+  ok2(`MCP server registered in ${c2.cyan(result.claudeConfigPath)}`);
+  ok2(`${result.registeredAgents.length} Claude Code subagent${result.registeredAgents.length === 1 ? "" : "s"} written to ${c2.cyan(result.agentsDir)}`);
+  for (const a of result.registeredAgents) info2(`  \u2022 agenticmail-${a.name.toLowerCase()}  \u2192  ${a.email}`);
+  log2("");
+  if (!result.changed) {
+    info2("Already up to date \u2014 no files were modified.");
+  } else {
+    log2(`  ${c2.bold("Next:")} restart Claude Code so it picks up the new MCP server.`);
+    info2(`Try inside Claude Code: ${c2.green('Agent { subagent_type: "agenticmail-fola", prompt: "hi" }')}`);
+  }
+  log2("");
+}
 async function cmdOpenClaw() {
   const sub = process.argv.slice(3);
   if (sub.includes("--help") || sub.includes("-h") || sub.includes("help")) {
@@ -6732,6 +6843,14 @@ switch (command) {
       process.exit(1);
     });
     break;
+  case "claudecode":
+  case "claude-code":
+  case "claude":
+    cmdClaudeCode().catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+    break;
   case "service":
     cmdService().then(() => {
       process.exit(0);
@@ -6774,6 +6893,7 @@ switch (command) {
     log2(`    ${c2.green("agenticmail stop")}      Stop the server`);
     log2(`    ${c2.green("agenticmail status")}    See what's running`);
     log2(`    ${c2.green("agenticmail openclaw")}  Set up AgenticMail for OpenClaw`);
+    log2(`    ${c2.green("agenticmail claudecode")} Set up AgenticMail for Claude Code`);
     log2(`    ${c2.green("agenticmail service")}   Manage auto-start (install/uninstall/status)`);
     log2(`    ${c2.green("agenticmail update")}    Update to the latest version`);
     log2("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/cli",
-  "version": "0.5.62",
+  "version": "0.6.0",
   "description": "Email and SMS infrastructure for AI agents — the first platform to give agents real email addresses and phone numbers",
   "type": "module",
   "main": "dist/index.js",
@@ -22,16 +22,19 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean --external @agenticmail/claudecode",
     "test": "vitest run --passWithNoTests",
     "preuninstall": "node scripts/uninstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agenticmail/api": "^0.5.62",
+    "@agenticmail/api": "^0.6.0",
     "@agenticmail/core": "^0.5.61",
     "json5": "^2.2.3"
   },
+  "optionalDependencies": {
+    "@agenticmail/claudecode": "^0.1.0"
+  },
   "devDependencies": {
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",