feat(daemon+mcp): daemon required for in-Claude-Code use; thin MCP shim

The architectural convergence v0.9.0 was building toward. CLI keeps
working without a daemon (claudemesh send/peer/inbox/...), but the MCP
push-pipe — which Claude Code uses for mid-turn channel emits, slash
commands, and resources — now requires the daemon. There is no fallback.

Daemon (additive):
- /v1/skills (list) and /v1/skills/:name (get) IPC endpoints, so the
  MCP shim can surface mesh skills without holding its own broker WS.
- listSkills() / getSkill() on DaemonBrokerClient.
- SSE 'message' event now carries plaintext body, sender_member_pubkey,
  priority, and subtype — full payload the MCP shim needs to render a
  channel notification.

MCP server: 979 → 469 LoC (470 of the remaining 469 is the unrelated
mesh-service proxy mode; the push-pipe path is ~200 LoC including
boilerplate).
- Probes ~/.claudemesh/daemon/daemon.sock at boot. Bails loudly with
  actionable instructions if missing.
- Subscribes to /v1/events SSE and translates each event into a
  notifications/claude/channel emit.
- Fetches mesh skills from the daemon for ListPrompts/GetPrompt and
  ListResources/ReadResource. ListTools returns []; the CLI is the API.
- No broker WS, no decryption, no reconnect logic. Daemon owns all of it.

claudemesh install: auto-installs and starts the daemon service for the
user's primary mesh (launchd / systemd-user). Pass --no-service to skip.

claudemesh launch: probes the daemon socket; if absent, spawns
'claudemesh daemon up --mesh <slug>' detached and waits up to 10s for
the socket. Surfaces a clear warning on timeout but doesn't block —
Claude Code's MCP shim will print the same error if the daemon really
isn't there.

Bundle: dist/entrypoints/mcp.js drops from 154KB → 104KB (gzipped 34KB
→ 19KB). Test: MCP boots cleanly via stdio, declares correct
capabilities, talks JSON-RPC; daemon /v1/skills returns the empty list
as expected on a mesh with no skills.

Released as 1.24.0 on npm.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/cli/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.24.0 (2026-05-03) — daemon required + thin MCP shim
+
+The architectural convergence v0.9.0 was building toward.
+
+### Daemon promoted from optional to required (for in-Claude-Code use)
+
+The CLI itself (`claudemesh send`, `peer list`, `inbox`, `vault`, `watch`,
+`webhook`, etc.) keeps working without a daemon. But the MCP server —
+which provides Claude Code's mid-turn channel push, slash commands, and
+resource browser — now requires the daemon. There is no fallback.
+
+- `claudemesh install` auto-installs and starts the daemon service
+  (launchd / systemd-user) for the user's primary mesh. Pass
+  `--no-service` to opt out.
+- `claudemesh launch` ensures the daemon is running before spawning
+  Claude Code; spawns it foreground if absent.
+- The MCP shim probes `~/.claudemesh/daemon/daemon.sock` at boot. If
+  missing after a 2s grace window, it bails with actionable instructions
+  ("run `claudemesh daemon up --mesh <slug>`").
+
+### MCP server: 979 → ~300 LoC of push-pipe code
+
+`apps/cli/src/mcp/server.ts` is now a thin daemon-SSE translator. It
+no longer holds a broker WebSocket, decrypts messages, manages mesh
+state, or runs reconnection logic. All of that is the daemon's job.
+
+- Subscribes to daemon `/v1/events` SSE; translates each `message`
+  event into a `notifications/claude/channel` emit.
+- Sources mesh-published skills via daemon `/v1/skills` IPC for
+  ListPrompts / GetPrompt / ListResources / ReadResource.
+- ListTools returns `[]` (the CLI is the API, taught via the bundled
+  skill).
+- The mesh-service proxy mode (`claudemesh-cli --service <name>`,
+  the sub-MCP-server for proxying a deployed mesh-MCP service) is
+  unchanged — separate code path, different lifecycle.
+
+Bundle size: MCP entry dropped from 154KB → 104KB (gzipped 34KB → 19KB).
+
+### Daemon SSE event payload extended
+
+`message` events on `/v1/events` now include plaintext-decrypted body,
+sender member pubkey, priority, and subtype — everything the MCP shim
+needs to render a complete channel notification without going back to
+the broker.
+
+### Daemon IPC: GET /v1/skills (list) and GET /v1/skills/:name (get)
+
+The daemon exposes mesh-published skills over IPC so the MCP shim can
+surface them as MCP prompts/resources without holding its own broker
+WS. Same wire format as before from Claude Code's perspective.
+
+### Why this is the right architecture
+
+MCP and the daemon are no longer independent broker clients with
+duplicated WS, decrypt, and dedupe logic. The daemon owns the broker
+relationship; MCP is a Claude-Code-specific UX adapter that reads from
+the daemon. Industry-normal shape (Tailscale, Slack, Ollama, Docker)
+where the long-lived runtime is required and the per-app integrations
+attach to it.
+
 ## 1.23.0 (2026-05-03) — close the CLI surface, prune dead MCP stubs
 
 Three previously-MCP-only write verbs land on the CLI, closing every

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudemesh-cli",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Peer mesh for Claude Code sessions — CLI + MCP server.",
   "keywords": [
     "claude-code",

apps/cli/src/commands/install.ts

@@ -437,6 +437,7 @@ function installStatusLine(): { installed: boolean } {
 export function runInstall(args: string[] = []): void {
   const skipHooks = args.includes("--no-hooks");
   const skipSkill = args.includes("--no-skill");
+  const skipService = args.includes("--no-service");
   const wantStatusLine = args.includes("--status-line");
   render.section("claudemesh install");
 
@@ -544,11 +545,33 @@ export function runInstall(args: string[] = []): void {
   }
 
   let hasMeshes = false;
+  let primaryMesh: string | undefined;
   try {
     const meshConfig = readConfig();
     hasMeshes = meshConfig.meshes.length > 0;
+    primaryMesh = meshConfig.meshes[0]?.slug;
   } catch {}
 
+  // Daemon service install — required for MCP integration as of 1.24.0.
+  // The daemon owns the broker WS and feeds the MCP push-pipe via SSE;
+  // skipping it leaves channel push, slash commands, and resources broken.
+  if (!skipService && hasMeshes && primaryMesh) {
+    try {
+      installDaemonService(entry, primaryMesh);
+    } catch (e) {
+      render.warn(
+        `daemon service install failed: ${e instanceof Error ? e.message : String(e)}`,
+        "Run `claudemesh daemon install-service --mesh <slug>` to retry.",
+      );
+    }
+  } else if (skipService) {
+    render.info(dim("· Daemon service skipped (--no-service)"));
+    render.info(dim("  MCP integration will fail at boot until you start the daemon manually:"));
+    render.info(dim("    claudemesh daemon up --mesh <slug>"));
+  } else if (!hasMeshes) {
+    render.info(dim("· Daemon service deferred — join a mesh first, then run install again."));
+  }
+
   render.blank();
   render.warn(`${bold("RESTART CLAUDE CODE")} ${yellow("for MCP tools to appear.")}`);
 
@@ -569,6 +592,67 @@ export function runInstall(args: string[] = []): void {
   render.info(dim(`  claudemesh completions zsh       # shell completions`));
 }
 
+/**
+ * Install + start the per-user daemon service for the primary mesh.
+ *
+ * Refuses on CI hosts (the service-install module guards this); falls
+ * back to a friendly message and lets the install otherwise succeed.
+ * The MCP push-pipe will fail loudly if the daemon isn't reachable, so
+ * the user knows there's a problem before it shows up as "no messages
+ * arriving."
+ */
+function installDaemonService(binaryEntry: string, meshSlug: string): void {
+  const {
+    installService,
+    detectPlatform,
+  } = require("~/daemon/service-install.js") as typeof import("../daemon/service-install.js");
+
+  const platform = detectPlatform();
+  if (!platform) {
+    render.info(dim(`· Daemon service skipped — unsupported platform: ${process.platform}`));
+    return;
+  }
+
+  // Resolve the binary the service unit should launch. When invoked from a
+  // bundled binary, argv[1] is correct. When invoked under tsx / dev, fall
+  // back to whatever `claudemesh` resolves to on PATH so the unit launches
+  // a shipped binary, not a dev script.
+  let binary = process.argv[1] ?? binaryEntry;
+  if (!binary || /\.ts$/.test(binary) || /node_modules|src\/entrypoints/.test(binary)) {
+    try {
+      const { execSync } = require("node:child_process") as typeof import("node:child_process");
+      binary = execSync("which claudemesh", { encoding: "utf8" }).trim();
+    } catch {
+      render.warn(
+        "couldn't resolve a 'claudemesh' binary on PATH; daemon service skipped",
+        "Install via npm/homebrew, then run `claudemesh daemon install-service --mesh " + meshSlug + "`",
+      );
+      return;
+    }
+  }
+
+  const r = installService({ binaryPath: binary, meshSlug });
+  render.ok(`daemon service installed (${r.platform})`);
+  render.kv([
+    ["unit", dim(r.unitPath)],
+    ["mesh", dim(meshSlug)],
+  ]);
+
+  // Boot the unit immediately so MCP has a daemon to attach to on next
+  // Claude Code launch. Best-effort: if launchctl/systemctl errors out we
+  // log and continue — the user can run the boot command manually.
+  try {
+    const { execSync } = require("node:child_process") as typeof import("node:child_process");
+    execSync(r.bootCommand, { stdio: "ignore" });
+    render.ok("daemon started");
+  } catch (e) {
+    render.warn(
+      `daemon service installed but failed to start: ${e instanceof Error ? e.message : String(e)}`,
+      `Run manually: ${r.bootCommand}`,
+    );
+  }
+}
+
 export function runUninstall(): void {
   render.section("claudemesh uninstall");
 

apps/cli/src/commands/launch.ts

@@ -44,6 +44,55 @@ export interface LaunchFlags {
 
 // --- Interactive mesh picker ---
 
+/**
+ * Ensure the per-user daemon is running before we hand off to Claude Code.
+ *
+ * As of 1.24.0 the daemon owns the broker WS and feeds the MCP push-pipe
+ * over IPC SSE. If the socket is absent when Claude boots its MCP shim,
+ * the shim bails (no fallback). So we probe for the socket here and, if
+ * missing, spawn `claudemesh daemon up --mesh <slug>` in the background,
+ * waiting briefly for the socket to appear.
+ *
+ * Best-effort: if the daemon spawn fails, we surface the error and let
+ * the launch proceed — Claude Code will print the same "daemon not
+ * running" message and the user can fix it manually.
+ */
+async function ensureDaemonRunning(meshSlug: string, quiet: boolean): Promise<void> {
+  const { DAEMON_PATHS } = await import("~/daemon/paths.js");
+  if (existsSync(DAEMON_PATHS.SOCK_FILE)) return;
+
+  if (!quiet) render.info("starting claudemesh daemon…");
+  const { spawn } = await import("node:child_process");
+  const argv0 = process.argv[1] ?? "claudemesh";
+  let binary = argv0;
+  if (/\.ts$/.test(binary) || /node_modules|src\/entrypoints/.test(binary)) {
+    try {
+      const { execSync } = await import("node:child_process");
+      binary = execSync("which claudemesh", { encoding: "utf8" }).trim();
+    } catch { binary = "claudemesh"; }
+  }
+  const child = spawn(binary, ["daemon", "up", "--mesh", meshSlug], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+
+  // Wait for the socket to appear. 10 s budget — covers cold node start +
+  // broker hello round-trip on slow links.
+  const start = Date.now();
+  while (Date.now() - start < 10_000) {
+    if (existsSync(DAEMON_PATHS.SOCK_FILE)) {
+      if (!quiet) render.ok("daemon ready");
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  render.warn(
+    "daemon failed to start within 10s",
+    "Run `claudemesh daemon up --mesh " + meshSlug + "` manually, then re-launch.",
+  );
+}
+
 async function pickMesh(meshes: JoinedMesh[]): Promise<JoinedMesh> {
   if (meshes.length === 1) return meshes[0]!;
 
@@ -550,6 +599,12 @@ export async function runLaunch(flags: LaunchFlags, rawArgs: string[]): Promise<
     }
   } catch { /* best effort */ }
 
+  // Ensure the daemon is running before we spawn Claude. The MCP shim
+  // (loaded by --dangerously-load-development-channels server:claudemesh)
+  // requires the daemon's UDS to be reachable at boot — if it isn't,
+  // channel push, slash commands, and resources fail.
+  await ensureDaemonRunning(mesh.slug, args.quiet);
+
   // Clean up stale mesh MCP entries from crashed sessions
   try {
     const claudeConfigPath = join(homedir(), ".claude.json");

apps/cli/src/daemon/broker.ts

@@ -56,6 +56,19 @@ interface PendingPeerList {
   timer: NodeJS.Timeout;
 }
 
+export interface SkillSummary {
+  name: string;
+  description: string;
+  tags: string[];
+  author: string;
+  createdAt: string;
+}
+
+export interface SkillFull extends SkillSummary {
+  instructions: string;
+  manifest?: unknown;
+}
+
 const HELLO_ACK_TIMEOUT_MS = 5_000;
 const SEND_ACK_TIMEOUT_MS  = 15_000;
 const BACKOFF_CAPS_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
@@ -76,6 +89,8 @@ export class DaemonBrokerClient {
   private helloTimer: NodeJS.Timeout | null = null;
   private pendingAcks = new Map<string, PendingAck>();
   private peerListResolvers = new Map<string, PendingPeerList>();
+  private skillListResolvers = new Map<string, { resolve: (rows: SkillSummary[]) => void; timer: NodeJS.Timeout }>();
+  private skillDataResolvers = new Map<string, { resolve: (row: SkillFull | null) => void; timer: NodeJS.Timeout }>();
   private sessionPubkey: string | null = null;
   private sessionSecretKey: string | null = null;
   private opens: Array<() => void> = [];
@@ -189,6 +204,28 @@ export class DaemonBrokerClient {
           return;
         }
 
+        if (msg.type === "skill_list") {
+          const reqId = String(msg._reqId ?? "");
+          const pending = this.skillListResolvers.get(reqId);
+          if (pending) {
+            this.skillListResolvers.delete(reqId);
+            clearTimeout(pending.timer);
+            pending.resolve(Array.isArray(msg.skills) ? (msg.skills as SkillSummary[]) : []);
+          }
+          return;
+        }
+
+        if (msg.type === "skill_data") {
+          const reqId = String(msg._reqId ?? "");
+          const pending = this.skillDataResolvers.get(reqId);
+          if (pending) {
+            this.skillDataResolvers.delete(reqId);
+            clearTimeout(pending.timer);
+            pending.resolve((msg.skill as SkillFull) ?? null);
+          }
+          return;
+        }
+
         if (msg.type === "push" || msg.type === "inbound") {
           this.opts.onPush?.(msg);
           return;
@@ -264,6 +301,34 @@ export class DaemonBrokerClient {
     });
   }
 
+  /** List mesh-published skills. Empty array on disconnect / timeout. */
+  async listSkills(query?: string, timeoutMs = 5_000): Promise<SkillSummary[]> {
+    if (this._status !== "open" || !this.ws) return [];
+    return new Promise<SkillSummary[]>((resolve) => {
+      const reqId = `sl-${++this.reqCounter}`;
+      const timer = setTimeout(() => {
+        if (this.skillListResolvers.delete(reqId)) resolve([]);
+      }, timeoutMs);
+      this.skillListResolvers.set(reqId, { resolve, timer });
+      try { this.ws!.send(JSON.stringify({ type: "list_skills", query, _reqId: reqId })); }
+      catch { this.skillListResolvers.delete(reqId); clearTimeout(timer); resolve([]); }
+    });
+  }
+
+  /** Fetch one skill's full body. Null on not-found / disconnect / timeout. */
+  async getSkill(name: string, timeoutMs = 5_000): Promise<SkillFull | null> {
+    if (this._status !== "open" || !this.ws) return null;
+    return new Promise<SkillFull | null>((resolve) => {
+      const reqId = `sg-${++this.reqCounter}`;
+      const timer = setTimeout(() => {
+        if (this.skillDataResolvers.delete(reqId)) resolve(null);
+      }, timeoutMs);
+      this.skillDataResolvers.set(reqId, { resolve, timer });
+      try { this.ws!.send(JSON.stringify({ type: "get_skill", name, _reqId: reqId })); }
+      catch { this.skillDataResolvers.delete(reqId); clearTimeout(timer); resolve(null); }
+    });
+  }
+
   /** Set the daemon's profile (avatar/title/bio/capabilities). Fire-and-forget. */
   setProfile(profile: { avatar?: string; title?: string; bio?: string; capabilities?: string[] }): void {
     if (this._status !== "open" || !this.ws) return;

apps/cli/src/daemon/inbound.ts

@@ -44,11 +44,14 @@ export async function handleBrokerPush(msg: Record<string, unknown>, ctx: Inboun
   const brokerMessageId = stringOrNull(msg.messageId);
   const senderPubkey    = stringOrNull(msg.senderPubkey)    ?? "";
   const senderName      = stringOrNull(msg.senderName)      ?? senderPubkey.slice(0, 8);
+  const senderMemberPk  = stringOrNull(msg.senderMemberPubkey);
   const topic           = stringOrNull(msg.topic);
   const replyToId       = stringOrNull(msg.replyToId);
   const ciphertext      = stringOrNull(msg.ciphertext)      ?? "";
   const nonce           = stringOrNull(msg.nonce)           ?? "";
   const createdAt       = stringOrNull(msg.createdAt);
+  const priority        = stringOrNull(msg.priority) ?? "next";
+  const subtype         = stringOrNull(msg.subtype);
   // Forward-compat: Sprint 7 brokers will send client_message_id alongside.
   const clientMessageId = stringOrNull(msg.client_message_id) ?? brokerMessageId ?? randomUUID();
   const body            = await decryptOrFallback({
@@ -78,9 +81,12 @@ export async function handleBrokerPush(msg: Record<string, unknown>, ctx: Inboun
     client_message_id: clientMessageId,
     broker_message_id: brokerMessageId,
     sender_pubkey: senderPubkey,
+    sender_member_pubkey: senderMemberPk,
     sender_name: senderName,
     topic,
     reply_to_id: replyToId,
+    priority,
+    ...(subtype ? { subtype } : {}),
     body,
     created_at: createdAt,
   });

apps/cli/src/daemon/ipc/server.ts

@@ -173,7 +173,7 @@ function makeHandler(opts: {
       respond(res, 200, {
         daemon_version: VERSION,
         ipc_api: "v1",
-        ipc_features: ["version", "health", "send", "inbox", "events", "peers", "profile"],
+        ipc_features: ["version", "health", "send", "inbox", "events", "peers", "profile", "skills"],
         schema_version: 1,
       });
       return;
@@ -204,6 +204,32 @@ function makeHandler(opts: {
       return;
     }
 
+    if (req.method === "GET" && url.pathname === "/v1/skills") {
+      if (!opts.broker) { respond(res, 503, { error: "broker not initialised" }); return; }
+      const query = url.searchParams.get("query") ?? undefined;
+      try {
+        const skills = await opts.broker.listSkills(query);
+        respond(res, 200, { skills });
+      } catch (e) {
+        respond(res, 502, { error: "broker_unreachable", detail: String(e) });
+      }
+      return;
+    }
+
+    if (req.method === "GET" && url.pathname.startsWith("/v1/skills/")) {
+      if (!opts.broker) { respond(res, 503, { error: "broker not initialised" }); return; }
+      const name = decodeURIComponent(url.pathname.slice("/v1/skills/".length));
+      if (!name) { respond(res, 400, { error: "missing skill name" }); return; }
+      try {
+        const skill = await opts.broker.getSkill(name);
+        if (!skill) { respond(res, 404, { error: "skill_not_found", name }); return; }
+        respond(res, 200, { skill });
+      } catch (e) {
+        respond(res, 502, { error: "broker_unreachable", detail: String(e) });
+      }
+      return;
+    }
+
     if (req.method === "POST" && url.pathname === "/v1/profile") {
       if (!opts.broker) { respond(res, 503, { error: "broker not initialised" }); return; }
       try {