clay-server 2.35.1 → 2.36.0-beta.2

package/README.md

@@ -1,173 +1,221 @@
 <p align="center">
-  <img src="media/logo/icon-full-banded-256-transparent.png" alt="Clay" />
+  <img src="media/logo/icon-full-banded-256-transparent.png" alt="Clay - self-hosted team workspace for Claude Code and Codex" />
 </p>
 
-<h3 align="center">Claude Code for your whole team. No team? Build one with AI.</h3>
+<h2 align="center">Multiplayer Claude Code and Codex.</h2>
+<h4 align="center">
+Drop into a teammate's session live.<br>
+Or pair with AI mates that remember and push back.<br>
+Self-hosted, one toggle between vendors.
+</h4>
 
-[![npm version](https://img.shields.io/npm/v/clay-server)](https://www.npmjs.com/package/clay-server) [![npm downloads](https://img.shields.io/npm/dw/clay-server)](https://www.npmjs.com/package/clay-server) [![GitHub stars](https://img.shields.io/github/stars/chadbyte/clay)](https://github.com/chadbyte/clay) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/chadbyte/clay/blob/main/LICENSE)
+<p align="center">
+  <a href="https://www.npmjs.com/package/clay-server"><img src="https://img.shields.io/npm/v/clay-server" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/clay-server"><img src="https://img.shields.io/npm/dw/clay-server" alt="npm downloads" /></a>
+  <a href="https://github.com/chadbyte/clay"><img src="https://img.shields.io/github/stars/chadbyte/clay" alt="GitHub stars" /></a>
+  <a href="https://github.com/chadbyte/clay/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+The browser tab your whole team lives in. Humans, AI agents, projects, sessions, decisions.
 
-<p align="center"><img src="media/hero.png" alt="Clay workspace" /></p>
+Afraid of locking your personal or team knowledge into one vendor? With Clay, your conventions, sessions, and decisions live on your disk. Switch when you want.
 
-Everything Claude Code does, in your browser and on your phone. Multi-session, multi-user, self-hosted. No cloud relay, no middleman.
+*A team-shared, self-hosted GUI for Claude Code and Codex CLIs.*
 
 ```bash
 npx clay-server
 # Scan the QR code to connect from any device
 ```
 
----
+## What's Clay?
 
-## What you get
+- **A browser-based workspace for Claude Code and Codex.** Open it on any device, alone or with your whole team.
+- **A place where your team collaborates across projects.** Engineers, PMs, designers, and domain experts share one workspace, hop between projects, drop into each other's sessions.
+- **Your virtual team.** Mates with names, memory, and roles — architect, reviewer, designer, whoever you need. They learn your codebase, push back on bad ideas, and don't reset between sessions.
+- **A multi-project dashboard.** Every repo on your machine in one sidebar. Run agents across several in parallel; permission requests and completions surface as notifications.
+- **A self-hosted dev server.** Runs on your machine in plain JSONL and Markdown. No proprietary database, no cloud relay, no lock-in. Walk away whenever — your data walks with you.
+- **A work-automation system.** Ralph Loop iterates a feature overnight; cron schedules agents while you're away. Wake up to results, or a clean failure trace.
 
-### Drop-in replacement for the CLI
+## What it does
 
-Your CLI sessions, your CLAUDE.md rules, your MCP servers. **All of it works in Clay as-is.** Pick up a CLI session in the browser, or continue a browser session in the CLI.
+### Run Claude Code and Codex in one workspace
+
+Open a session, pick a vendor. Switch sessions, pick the other. Clay's adapter layer (YOKE) speaks the Claude Agent SDK and the Codex app-server protocol natively. Cross-vendor instruction loading: Codex reads AGENTS.md, Claude reads CLAUDE.md, Clay merges the rest into the system prompt automatically.
 
 <p align="center">
-  <img src="media/split.gif" alt="split-screen workflow" width="700">
+  <img src="media/split.gif" alt="Toggle between Claude Code and Codex in one click" width="700">
 </p>
 
-### Claude Code on steroids
+### Every project on one dashboard
 
-**Multiple agents, multiple projects, at the same time.** Switch between them in the sidebar. Browse project files live while the agent works, with syntax highlighting for 180+ languages. Mermaid diagrams render as diagrams. Tables render as tables.
+All your projects live in the sidebar. Jump between them in one click, see live status across each, run agents in several at once. No more `cd ~/work/foo && tmux attach && ...`. One Clay daemon hosts every repo on your machine and gives you a single pane of glass over all of them.
 
-**Schedule agents with cron**, or let them run autonomously with **Ralph Loop**. Close your laptop, sessions keep running.
+### Mates: AI teammates with persistent memory
 
-**Push notifications on mobile.** Your phone buzzes when Claude needs approval, finishes a task, or hits an error. Install as a PWA on iOS or Android, review and approve from anywhere.
+Mates are AI personas with their own CLAUDE.md, knowledge files, and memory that compounds across sessions. They learn your stack, your conventions, your decision history. @mention them mid-session, DM them directly, or drop them into a debate. **They don't flatter you. They push back.**
 
 <p align="center">
-  <img src="media/phone.gif" alt="Clay on phone" width="280">
+  <img src="media/mates.gif" alt="An AI teammate (Mate) pushing back on a bad design pitch in Clay" width="640">
 </p>
 
-### Your machine, your server, your data
+### Debate: structured multi-Mate decisions
 
-**Fully local.** Clay runs as a daemon on your machine. Your code and conversations never leave your machine except to reach the AI provider's API.
+Stuck on REST vs GraphQL? Monorepo or split? Surface the question to a debate. Pick panelists, set the format, let your Mates argue both sides with moderated turns. You walk away with a recorded decision, not a vibe check.
 
-**Plain files.** Sessions are JSONL. Settings are JSON. Knowledge is Markdown. Everything lives on your machine in formats you can read, move, and back up. No proprietary database, no cloud lock-in.
+### Parallel worktrees
 
-**Secure by default.** PIN authentication, per-project permissions, and HTTPS are built in.
+Detect existing git worktrees, spin up new ones from the sidebar, and run agents in each one independently. No more "wait, I have uncommitted changes." Each worktree is an isolated session with its own history.
 
-### Bring your whole team
+### Ralph Loop: autonomous coding while you sleep
 
-**One API key runs the whole workspace.** Invite teammates, set permissions per person, per project, per session. Share one key across the org, or let each member use their own Claude Code login.
+Write a `PROMPT.md`, optionally a `JUDGE.md`, hit go. Clay iterates: code, evaluate, retry, until the judge approves or you cap the loop. Run it once, or schedule it on standard Unix cron. Wake up to a finished feature or a clean failure trace.
 
-**OS-level isolation.** On Linux, Clay maps each user to an OS-level account. File permissions and process isolation just work.
+### Web UI, mobile, push notifications
 
-**Shared sessions.** Your PM describes a bug in plain language, your senior joins the same session, and the fix ships together. If someone gets stuck, **jump into their session** to help in real time.
+Installable PWA on iOS and Android. Push notifications for approvals, errors, and completed tasks. Service worker keeps the app responsive offline. When Claude needs approval, your phone buzzes, you tap approve, the agent keeps going.
 
-### Build your AI team
+## Who is Clay for
 
-**Mates.** AI teammates with persistent memory across sessions. They learn your stack, your conventions, and your decision history. @mention them for a quick review, DM them directly, or bring multiple into the same conversation. **They don't flatter you. They push back.**
+### Small teams (3–10)
 
-<!-- TODO: mates.gif -->
+Engineers, PMs, designers, and domain experts in one workspace. Non-devs read the codebase and ask questions without ever opening an editor. Engineers @mention each other or drop into a teammate's session to help in real time. Share one org-wide API key or let each member bring their own, with costs routing to whoever ran the model.
 
-**Debate.** Your Mates argue both sides before you commit. "REST vs GraphQL?" "Monorepo or separate repos?" "This migration plan won't survive production. Here's why."
+### Larger teams (10+)
 
-<!-- TODO: debate.gif -->
+Per-user, per-project, per-session permissions. On Linux, opt in to OS-level isolation: each Clay user maps to a real Linux account, file ACLs enforced via `setfacl`, processes spawn under the right UID/GID. Per-project API keys for billing separation. Plain JSONL sessions give you an audit trail you can grep.
 
----
+### Solopreneurs and indie developers
 
-## Who is Clay for
+You don't have a team yet, so Mates are your team. A persistent architect, a reviewer, a designer — each with their own memory, ready to push back on bad ideas. Run Ralph Loop overnight to ship while you sleep. Toggle Claude and Codex per session to balance cost and capability.
 
-- **Solo dev who needs a second opinion.** Architecture review, dependency decisions, refactor tradeoffs. Build reviewers as Mates instead of asking the void.
-- **Small team sharing one Claude Code setup.** One API key, everyone in the browser, no terminal knowledge required.
-- **Dev lead running agents overnight.** Schedule tasks with cron, get push notifications on your phone, review in the morning.
+### Self-hosting developers
+
+Your code stays on your machine. Sessions are JSONL, knowledge is Markdown, settings are JSON. No proprietary database, no cloud relay, no middleman. CLAUDE.md, AGENTS.md, `.cursorrules` are all loaded automatically across vendors. Walk away whenever, your data walks with you.
 
 ## Getting Started
 
-**Requirements:** Node.js 20+, Claude Code CLI (authenticated).
+**Requirements:** Node.js 20+. Authenticated Claude Code CLI, Codex CLI, or both.
 
 ```bash
 npx clay-server
 ```
 
-On first run, it asks for a port number and whether you're using it solo or with a team.
-Open the browser URL or scan the QR code to connect from your phone instantly.
+On first run, Clay asks for a port and whether you're solo or with a team. Open the URL or scan the QR code from your phone.
 
 For remote access, use a VPN like Tailscale.
 
 <p align="center">
-  <img src="media/start.gif" alt="Clay starting from CLI" width="600">
+  <img src="media/start.gif" alt="Starting Clay daemon from the CLI with npx clay-server" width="600">
 </p>
 
+## CLI Options
+
+```bash
+npx clay-server              # Default (port 2633)
+npx clay-server -p 8080      # Specify port
+npx clay-server --yes        # Skip interactive prompts (use defaults)
+npx clay-server -y --pin 123456
+                              # Non-interactive + PIN (for scripts/CI)
+npx clay-server --add .      # Add current directory to running daemon
+npx clay-server --remove .   # Remove project
+npx clay-server --list       # List registered projects
+npx clay-server --shutdown   # Stop running daemon
+npx clay-server --dangerously-skip-permissions
+                              # Bypass all permission prompts (requires PIN at setup)
+```
+
+Run `npx clay-server --help` for all options.
+
 ## FAQ
 
-**"Is this just a Claude Code wrapper?"**
-Clay uses the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. It doesn't wrap terminal output. It adds multi-session orchestration, persistent AI teammates (Mates), structured debates, scheduled agents, multi-user collaboration, and a full browser UI.
+**"Is this a Claude Code wrapper?"**
+No. Clay drives Claude Code through the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and Codex through the Codex app-server protocol. Both are first-class. Clay adds multi-session orchestration, persistent Mates, structured debates, scheduled agents, multi-user collaboration, built-in MCP servers, and a full browser UI on top.
+
+**"Can I run Claude Code and Codex in the same workspace?"**
+Yes. Pick a vendor when you open a session. Switch per session. Same projects, same Mates, same memory.
+
+**"How are Mates different from Claude Code's sub-agents?"**
+Sub-agents are ephemeral specialists spawned inside a single Claude Code session — a role and a system prompt for one task, then forgotten when the task ends. Mates are persistent teammates with their own knowledge files and memory that survive every session. A sub-agent forgets you the moment it returns; a Mate remembers your codebase, your decisions, and your conventions across months of work. @mention a Mate mid-session, DM it between sessions, or drop several into a debate.
 
 **"Does my code leave my machine?"**
-Clay is fully self-hosted. The server runs on your machine, files stay local. Only API calls go out, same as using the CLI directly.
+Only as model API calls (the same as using the CLI directly). Sessions, Mates, knowledge, and settings all stay on disk.
 
-**"Can I continue a CLI session in the browser?"**
-Yes. Pick up a CLI session in the browser, or continue a browser session in the CLI.
+**"Does my existing CLAUDE.md / AGENTS.md / .cursorrules work?"**
+Yes. Clay loads native instruction files for each vendor and merges the rest into the system prompt automatically.
 
-**"Does my existing CLAUDE.md work?"**
-Yes. If your project has a CLAUDE.md, it works in Clay as-is.
+**"Can I continue a CLI session in the browser?"**
+Yes. CLI sessions show up in the sidebar. Browser sessions can be picked up in the CLI.
 
 **"Does each teammate need their own API key?"**
-No. Teammates can share one org-wide API key. On Linux with OS-level isolation, each member can also use their own Claude Code login. You can assign different API keys per project for billing isolation.
+No. Share one org-wide key, or let each user bring their own. On Linux with OS-level isolation, each member can also use their own Claude Code or Codex login.
+
+**"What does OS-level isolation actually do?"**
+On Linux, opt in and Clay provisions each user as a real Linux account. File ACLs are enforced via `setfacl`, agent processes spawn under the user's UID/GID, and the kernel handles the rest. One teammate can't read another's project files, even by accident. The guarantee comes from the OS, not from a promise in our code.
 
 **"Does it work with MCP servers?"**
-Yes. MCP configurations from the CLI carry over as-is.
+Yes. User-configured MCPs from `~/.clay/mcp.json` plus built-in browser, email, ask-user, and debate servers. All work in both Claude and Codex sessions.
 
 **"Can I use it on my phone?"**
-Yes. Clay works as a PWA on iOS and Android. You get push notifications for approvals, errors, and completed tasks. No app store required.
+Yes. Install as a PWA on iOS or Android. Push notifications for approvals, errors, and task completion.
 
 **"What is d.clay.studio in my browser URL?"**
-It's a DNS-only service that resolves to your local IP for HTTPS certificate validation. No data passes through it. All traffic stays between your browser and your machine. See [clay-dns](clay-dns/) for details.
+A DNS-only service that resolves to your local IP for HTTPS certificate validation. No data passes through it. All traffic stays between your browser and your machine. See [clay-dns](clay-dns/) for details.
 
-## Why I built Clay
+## Our Philosophy
 
-Claude Code is the best coding agent I've found. I wanted to turn it into a team, not just a single-player tool.
+One idea: **user experience sovereignty**.
 
-That started as a browser interface so I could access it from anywhere. Then I added multi-user so my team could use it too. Then I started building the AI teammates themselves.
+Not a grand statement. A simple wish: not to have your thinking, your work, and your data locked in the moment a vendor changes a price or rewrites a ToS.
 
-Most AI agent projects go for full autonomy. Let the AI loose, give it all the permissions, let it run. I wanted the opposite: **AI that works as part of a team.** Visible, controllable, accountable. Your teammates can see what the agent is doing, jump in when it needs help, and set the rules it operates under.
+That shows up in the technical choices we made:
 
-That's Clay now. A workspace where AI teammates have names, persistent memory, and their own perspective. Not "act like an expert" prompting. Actual colleagues who remember last week and sit in your sidebar next to the human ones.
+- **Your machine is the server.** Browser → your daemon → model API. That's the full chain. No vendor cloud, no relay server, no middle tier syncing your sessions through someone else's infrastructure.
+- **One toggle between vendors.** The adapter layer (YOKE) speaks the Claude Agent SDK and the Codex app-server protocol natively. Switching is a setting, not a migration.
+- **Plain text on disk.** Sessions, Mates, knowledge, and settings live as JSONL and Markdown. No proprietary database. You can `cat`, `grep`, version, and back up everything yourself.
+- **Standard formats only.** CLAUDE.md, AGENTS.md, `.cursorrules`, MCP, Unix cron. If you walk away from Clay, your data walks with you in formats every other tool already understands.
 
-## CLI Options
-
-```bash
-npx clay-server              # Default (port 2633)
-npx clay-server -p 8080      # Specify port
-npx clay-server --yes        # Skip interactive prompts (use defaults)
-npx clay-server -y --pin 123456
-                              # Non-interactive + PIN (for scripts/CI)
-npx clay-server --add .      # Add current directory to running daemon
-npx clay-server --remove .   # Remove project
-npx clay-server --list       # List registered projects
-npx clay-server --shutdown   # Stop running daemon
-npx clay-server --dangerously-skip-permissions
-                              # Bypass all permission prompts (requires PIN at setup)
-```
-
-Run `npx clay-server --help` for all options.
+That's the principle. The rest of the README is what it makes possible.
 
 ## Architecture
 
-Clay drives agent execution through the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) and streams it to the browser over WebSocket.
+Clay is a self-hosted daemon. It drives Claude Code (via the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)) and Codex (via the `codex app-server` JSON-RPC protocol) through a vendor-agnostic adapter layer (**YOKE**), and serves a multi-user web workspace over HTTP/WS. Sessions, Mates, and knowledge live as plain JSONL/Markdown on disk.
 
 ```mermaid
 graph LR
-    Browser["Browser<br/>(Phone / Desktop)"]
-    WS["WebSocket"]
-    Server["HTTP Server<br/>lib/server.js"]
-    Project["Project Context<br/>lib/project.js"]
-    SDK["Claude Agent SDK"]
-    Claude["Claude Code<br/>Process"]
-    Push["Push Service"]
-
-    Browser <-->|Real time stream| WS
-    WS <--> Server
-    Server -->|slug routing| Project
-    Project <-->|async iterable| SDK
-    SDK <-->|Prompt / Response| Claude
-    Project -->|Approval request| Push
-    Push -->|Notification| Browser
+    subgraph Clients
+      B1["Browser<br/>User A"]
+      B2["Browser<br/>User B"]
+      Phone["Phone PWA<br/>+ Push"]
+    end
+
+    subgraph Daemon["Clay Daemon (your machine)"]
+      Auth["Auth + RBAC"]
+      Server["HTTP / WS Server"]
+      Project["Project Context"]
+      YOKE["YOKE Adapter Layer"]
+      MCP["Built-in MCP servers<br/>ask-user / browser /<br/>debate / email"]
+      Push["Push (VAPID)"]
+    end
+
+    subgraph Vendors["Agent runtimes"]
+      Claude["Claude Agent SDK"]
+      Codex["codex app-server<br/>(JSON-RPC stdio)"]
+    end
+
+    B1 <-->|WS| Server
+    B2 <-->|WS| Server
+    Phone <-->|WS + push| Server
+    Server --> Auth
+    Server --> Project
+    Project --> YOKE
+    Project --> MCP
+    Project --> Push
+    YOKE --> Claude
+    YOKE --> Codex
+    Push -.-> Phone
 ```
 
-For detailed sequence diagrams, daemon architecture, and design decisions, see [docs/architecture.md](docs/architecture.md).
+For sequence diagrams, OS-level isolation, daemon IPC, and key design decisions, see [docs/guides/architecture.md](docs/guides/architecture.md).
 
 ## Community Projects
 
@@ -195,7 +243,7 @@ If you're using Clay, let us know how in Discussions:
 
 ## Disclaimer
 
-Not affiliated with Anthropic. Claude is a trademark of Anthropic. Provided "as is" without warranty. Users are responsible for complying with their AI provider's terms of service.
+Not affiliated with Anthropic or OpenAI. Claude is a trademark of Anthropic. Codex is a trademark of OpenAI. Provided "as is" without warranty. Users are responsible for complying with their AI provider's terms of service.
 
 ## License
 

package/lib/project-image.js

@@ -34,7 +34,7 @@ function attachImage(ctx) {
       return hydrated;
     }
     if (!entry.imageRefs) return entry;
-    if (entry.type !== "user_message" && entry.type !== "mention_user") return entry;
+    if (entry.type !== "user_message" && entry.type !== "mention_user" && entry.type !== "user_mention") return entry;
     var images = [];
     for (var ri = 0; ri < entry.imageRefs.length; ri++) {
       var ref = entry.imageRefs[ri];

package/lib/project-mate-interaction.js

@@ -31,6 +31,29 @@ function attachMateInteraction(ctx) {
   var MENTION_CONTEXT_BUDGET = 32 * 1024; // 32KB total budget for prior turns fed into mention context
   var MENTION_CONTEXT_MAX_TURNS = 200; // hard safety cap so we never walk the entire session
 
+  // Plain @mention targets: vendor-only mentions with no persona, no memory,
+  // no digest write-back. Lets users in a Claude session ask raw Codex (and
+  // vice versa) for a second opinion without spinning up a real Mate.
+  var PLAIN_MENTIONS = {
+    "plain:claude": {
+      vendor: "claude",
+      name: "Claude Code",
+      avatarColor: "#cc785c",
+      avatarStyle: "bottts",
+      avatarSeed: "plain-claude",
+    },
+    "plain:codex": {
+      vendor: "codex",
+      name: "Codex",
+      avatarColor: "#10a37f",
+      avatarStyle: "bottts",
+      avatarSeed: "plain-codex",
+    },
+  };
+  function isPlainMentionId(id) {
+    return typeof id === "string" && Object.prototype.hasOwnProperty.call(PLAIN_MENTIONS, id);
+  }
+
   // Walk session history backwards collecting full turns (no per-turn truncation)
   // until either maxTurns is reached or byteBudget is exhausted. Each turn keeps
   // its full text; we drop older turns first when the budget runs out.
@@ -489,10 +512,27 @@ function attachMateInteraction(ctx) {
 
     var userId = ws._clayUser ? ws._clayUser.id : null;
     var mateCtx = matesModule.buildMateCtx(userId);
-    var mate = matesModule.getMate(mateCtx, msg.mateId);
-    if (!mate) {
-      sendTo(ws, { type: "mention_error", mateId: msg.mateId, error: "Mate not found" });
-      return;
+    var isPlain = isPlainMentionId(msg.mateId);
+    var mate;
+    if (isPlain) {
+      var pCfg = PLAIN_MENTIONS[msg.mateId];
+      mate = {
+        id: msg.mateId,
+        vendor: pCfg.vendor,
+        name: pCfg.name,
+        profile: {
+          displayName: pCfg.name,
+          avatarColor: pCfg.avatarColor,
+          avatarStyle: pCfg.avatarStyle,
+          avatarSeed: pCfg.avatarSeed,
+        },
+      };
+    } else {
+      mate = matesModule.getMate(mateCtx, msg.mateId);
+      if (!mate) {
+        sendTo(ws, { type: "mention_error", mateId: msg.mateId, error: "Mate not found" });
+        return;
+      }
     }
 
     var mateName = (mate.profile && mate.profile.displayName) || mate.name || "Mate";
@@ -601,15 +641,17 @@ function attachMateInteraction(ctx) {
         sendToSession(session.localId, { type: "mention_done", mateId: msg.mateId });
         send({ type: "mention_processing", mateId: msg.mateId, active: false });
 
-        if (isMate) {
+        if (isMate && !isPlain) {
           notifyMentionResponse(session, msg.mateId, mateName, fullText);
         }
 
-        // Check if the mate wrote a debate brief during this turn
-        ctx.checkForDmDebateBrief(session, msg.mateId, mateCtx);
+        if (!isPlain) {
+          // Check if the mate wrote a debate brief during this turn
+          ctx.checkForDmDebateBrief(session, msg.mateId, mateCtx);
 
-        // Generate session digest for mate's long-term memory
-        digestMentionSession(session, msg.mateId, mateCtx, fullText, msg.text);
+          // Generate session digest for mate's long-term memory
+          digestMentionSession(session, msg.mateId, mateCtx, fullText, msg.text);
+        }
       },
       onError: function (errMsg) {
         session._mentionInProgress = false;
@@ -644,18 +686,29 @@ function attachMateInteraction(ctx) {
         delete session._mentionSessions[msg.mateId];
       }
 
-      // Load Mate CLAUDE.md
-      var mateDir = matesModule.getMateDir(mateCtx, msg.mateId);
       var claudeMd = "";
-      try {
-        claudeMd = fs.readFileSync(path.join(mateDir, "CLAUDE.md"), "utf8");
-      } catch (e) {
-        // CLAUDE.md may not exist for new mates
-      }
+      var recentDigests = "";
+      if (isPlain) {
+        // Plain @mention: route to the vendor with just enough framing so the
+        // model understands it is a sidebar response, not the primary agent.
+        claudeMd =
+          "A user is working with another coding assistant and has @mentioned you for a second opinion on the current exchange.\n" +
+          "The recent conversation between the user and that other assistant is included as context below.\n" +
+          "Read it, then answer the user's question directly. Be concise and give your honest take.\n" +
+          "You are not driving the session, so do not run tools or take actions unless the user explicitly asks; commenting and advising is the default.";
+      } else {
+        // Load Mate CLAUDE.md
+        var mateDir = matesModule.getMateDir(mateCtx, msg.mateId);
+        try {
+          claudeMd = fs.readFileSync(path.join(mateDir, "CLAUDE.md"), "utf8");
+        } catch (e) {
+          // CLAUDE.md may not exist for new mates
+        }
 
-      // Load session digests (unified: uses memory-summary.md if available)
-      // Pass user's message as query for BM25 search of relevant past sessions
-      var recentDigests = loadMateDigests(mateCtx, msg.mateId, mentionFullInput);
+        // Load session digests (unified: uses memory-summary.md if available)
+        // Pass user's message as query for BM25 search of relevant past sessions
+        recentDigests = loadMateDigests(mateCtx, msg.mateId, mentionFullInput);
+      }
 
       // Build initial mention context
       var mentionContext = buildMentionContext(userName, recentTurns) + recentDigests;

package/lib/project-notifications.js

@@ -85,6 +85,23 @@ var formatters = {
       meta: { avatarMateId: data.avatarMateId || null },
     };
   },
+
+  user_mention: function (data) {
+    return {
+      type: "user_mention",
+      title: "@" + (data.fromName || "Someone"),
+      body: data.preview || "Mentioned you",
+      meta: {
+        fromUserId: data.fromUserId || null,
+        fromName: data.fromName || "",
+        fromAvatarStyle: data.fromAvatarStyle || null,
+        fromAvatarSeed: data.fromAvatarSeed || null,
+        fromAvatarColor: data.fromAvatarColor || null,
+        fromAvatarCustom: data.fromAvatarCustom || "",
+        persistent: true,
+      },
+    };
+  },
 };
 
 // ========================================================
@@ -93,6 +110,7 @@ var formatters = {
 
 function attachNotifications(ctx) {
   var broadcastAll = ctx.broadcastAll;
+  var sendToUser = ctx.sendToUser || null; // (userId, msg) -> void; iterates all project clients
   var pushModule = ctx.pushModule;
 
   var notifications = loadNotifications();
@@ -142,16 +160,24 @@ function attachNotifications(ctx) {
       sessionId: data.sessionId || null,
       mateId: data.mateId || null,
       ownerId: data.ownerId || null,
+      targetUserId: data.targetUserId || null,
       createdAt: Date.now(),
       meta: formatted.meta || {},
     };
     notifications.unshift(notif);
     saveNotifications();
-    broadcastAll({
+    var payload = {
       type: "notification_created",
       notification: notif,
       unreadCount: getUnreadCount(),
-    });
+    };
+    // If targeted at a specific user, deliver only to that user's connections.
+    // Otherwise broadcast to everyone (existing behavior).
+    if (notif.targetUserId && typeof sendToUser === "function") {
+      sendToUser(notif.targetUserId, payload);
+    } else {
+      broadcastAll(payload);
+    }
     return notif;
   }