tryharness 0.4.1 → 0.4.3

package/README.md

@@ -1,6 +1,6 @@
 # tryharness
 
-Connect the coding agents installed on this machine to [Harness](https://tryharness.ai):
+Put the coding agents installed on this machine in your [Harness](https://tryharness.ai) relay:
 
 ```sh
 npx tryharness
@@ -10,10 +10,15 @@ Supports the Node.js 18, 20, 22, and 24 release lines.
 
 That one command pairs the machine, detects Claude Code, Codex, pi, and opencode,
 configures every installed agent, installs the Harness daemon as a user-level login
-service, validates readiness, and starts indexing existing coding sessions locally in
-SQLite. Setup returns as soon as the daemon is ready; indexing continues in the
+service (launchd on macOS, a systemd user service on Linux, a Task Scheduler logon task
+on Windows; all without elevation), validates readiness, and starts indexing existing
+coding sessions locally in SQLite. Setup returns as soon as the daemon is ready; indexing continues in the
 background and does not require an open Harness tab.
 
+JSONL histories are streamed from beginning to end and only normalized conversation
+records are retained. Source-file size does not truncate recall; long read results are
+paged when Harness displays them.
+
 The command is idempotent. Run it again after installing another agent or to repair its
 configuration.
 
@@ -23,8 +28,10 @@ configuration.
 npx tryharness status
 npx tryharness doctor
 npx tryharness sync --agent codex
+npx tryharness task <run-id> --follow
 npx tryharness logs --follow
-npx tryharness handoff codex --file ./implementation-brief.md
+npx tryharness board
+npx tryharness board post --for claude-code --objective "Port the parser" --file ./brief.md
 npx tryharness disconnect
 ```
 
@@ -32,10 +39,54 @@ npx tryharness disconnect
 daemon, the bridge, the database, and agent discovery. `sync` requests a background
 rescan; it is diagnostic, not part of normal setup.
 
+Delegated coding tasks start only after the user presses Start on Harness's proposal
+card, which posts the task on the machine's board under the run id. They then run non-interactively with each agent's full-authority/auto-approve mode
+inside the exact absolute working directory shown on that card; Harness never falls
+back to the user's home directory. The card immediately shows a
+`npx tryharness task <run-id> --follow` command for watching the machine-local raw output
+in a terminal. Both the card and the follow command print the agent's native session
+command as soon as the agent reports its session id, including while the run is active,
+so the user can enter and steer the agent directly rather than interacting through a
+Harness wrapper.
+
+## Task board
+
+The daemon keeps a task board in its local SQLite database. Any connected agent can post
+work for another agent on the machine through the `post_task` tool, and every agent sees
+the board through `list_tasks`, `get_task`, `claim_task` and `report_task`, which the
+stdio MCP exposes. The board is pull-only: a task waits until
+its target agent reads the board and claims it, and nothing starts by itself. A claimer
+reports done, failed or needs_input; the poster answers a question with `report_task`
+and status `answered`, which returns the task to the claimer with the answer in its
+brief. The daemon is also the board's worker. A task posted for a coding agent installed on the
+machine with `--run --workspace <dir>` (or an agent's `run_workspace` request, once the user
+authorizes it with `tryharness board run <id>`) is claimed by the daemon in that agent's name,
+run non-interactively through the same runner as a delegated run, and reported back on the
+task with the result and the agent's session id; `tryharness task <id> --follow` works on it.
+One run per agent at a time; a daemon restart marks a running task unknown. An interactive
+claim carries a lease (default 60 minutes); a lapsed lease shows the claim as stale and only
+the poster or the user releases it. `tryharness board agents` shows when each agent last read
+the board. Every change goes up the bridge as identity and status only.
+
+Interactive sessions are told about waiting work when they open. Setup adds a Claude Code
+SessionStart hook that prints the board's tasks for it into the session's context, the Pi
+extension shows the same on session start (and puts it in context where pi allows), and the
+OpenCode plugin adds it to the first message of a session. Codex has no hook surface, so it
+reads the board when asked. The nudge is silent when nothing waits or no daemon is running.
+
+Every task has one holder, the only agent allowed to write it next, and a version that
+every write bumps; a write lands only for the holder at the expected version, and anything
+else comes back as a conflict carrying the task as it is now, so agents cannot overwrite
+each other. Briefs and results stay on the machine; the bridge reports identity and status
+only. Any MCP client on the machine joins the board by launching `lib/mcp-stdio.mjs --agent <name>`.
+Grok Bot keeps its MCP servers in its own account settings, so setup prints
+`npx tryharness mcp grok-bot`, a one-server snippet to paste into Grok Bot's MCP settings; it
+then appears on the board as `grok-bot`.
+
 The daemon dials out to Harness over one authenticated WebSocket. Its local control
 socket is permissioned to the current user. When OpenCode is installed, the daemon also
 starts OpenCode's own helper on a random loopback-only port with a random per-process
 password so it can index OpenCode history; no fixed or unauthenticated port is used.
 Connection tokens stay in `~/.harness/config.json` with owner-only permissions. Coding
-history and handoffs stay in the local SQLite database unless an explicit operation
+history and the board stay in the local SQLite database unless an explicit operation
 sends content through Harness.

package/assets/opencode-plugin.js

@@ -8,6 +8,34 @@ const socketPath = process.platform === "win32"
   ? "\\\\.\\pipe\\tryharness-daemon"
   : path.join(os.homedir(), ".harness", "daemon.sock");
 
+function ask(message) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let socket;
+    try { socket = net.createConnection(socketPath); } catch { resolve(null); return; }
+    socket.setEncoding("utf8");
+    socket.setTimeout(1_500);
+    socket.on("connect", () => socket.write(JSON.stringify(message) + "\n"));
+    socket.on("data", (chunk) => { buffer += chunk; if (buffer.includes("\n")) { socket.destroy(); try { resolve(JSON.parse(buffer.split("\n")[0])); } catch { resolve(null); } } });
+    socket.on("timeout", () => { socket.destroy(); resolve(null); });
+    socket.on("error", () => resolve(null));
+  });
+}
+
+// What opencode is told once per session, on its first message: work waiting on the board.
+async function boardNudge() {
+  const response = await ask({ command: "board.list", agent: "opencode" });
+  const tasks = response?.ok ? response.tasks : [];
+  const waiting = tasks.filter((task) => task.status === "open" && (!task.target_agent || task.target_agent === "opencode"));
+  const held = tasks.filter((task) => task.claimed_by === "opencode" && (task.status === "claimed" || task.status === "needs_input"));
+  if (!waiting.length && !held.length) return "";
+  const line = (task) => `- ${task.id}: ${task.objective}${task.origin_agent ? ` (from ${task.origin_agent})` : ""}`;
+  return ["Harness task board:", ...(waiting.length ? [`${waiting.length} task${waiting.length === 1 ? "" : "s"} waiting for you:`, ...waiting.slice(0, 5).map(line)] : []),
+    ...(held.length ? [`${held.length} you already claimed:`, ...held.slice(0, 5).map(line)] : []),
+    "Read one with get_task, claim it with claim_task before working, and report_task when done or stuck."].join("\n");
+}
+const nudged = new Set();
+
 function notify(message) {
   try {
     const socket = net.createConnection(socketPath);
@@ -19,6 +47,14 @@ function notify(message) {
 }
 
 export const TryHarnessPlugin = async ({ directory }) => ({
+  // The first message of each session carries the board nudge as an extra text part.
+  "chat.message": async (input, output) => {
+    const sessionId = input?.sessionID || input?.sessionId;
+    if (!sessionId || nudged.has(sessionId) || !Array.isArray(output?.parts)) return;
+    nudged.add(sessionId);
+    const nudge = await boardNudge();
+    if (nudge) output.parts.push({ type: "text", text: nudge });
+  },
   event: async ({ event }) => {
     if (event?.type !== "session.idle") return;
     const sessionId = event?.properties?.sessionID || event?.properties?.sessionId;

package/assets/pi-extension.ts

@@ -5,7 +5,38 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+import net from "node:net";
+
 const CONFIG_PATH = path.join(os.homedir(), ".harness", "config.json");
+const SOCKET_PATH = process.platform === "win32" ? "\\\\.\\pipe\\tryharness-daemon" : path.join(os.homedir(), ".harness", "daemon.sock");
+
+// One request to the local daemon; nothing waiting, or no daemon, is an empty answer.
+function daemon(message) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let socket;
+    try { socket = net.createConnection(SOCKET_PATH); } catch { resolve(null); return; }
+    socket.setEncoding("utf8");
+    socket.setTimeout(1_500);
+    socket.on("connect", () => socket.write(JSON.stringify(message) + "\n"));
+    socket.on("data", (chunk) => { buffer += chunk; if (buffer.includes("\n")) { socket.destroy(); try { resolve(JSON.parse(buffer.split("\n")[0])); } catch { resolve(null); } } });
+    socket.on("timeout", () => { socket.destroy(); resolve(null); });
+    socket.on("error", () => resolve(null));
+  });
+}
+
+// What pi is told when a session opens: work waiting for it on the machine's task board.
+async function boardNudge() {
+  const response = await daemon({ command: "board.list", agent: "pi" });
+  const tasks = response?.ok ? response.tasks : [];
+  const waiting = tasks.filter((task) => task.status === "open" && (!task.target_agent || task.target_agent === "pi"));
+  const held = tasks.filter((task) => task.claimed_by === "pi" && (task.status === "claimed" || task.status === "needs_input"));
+  if (!waiting.length && !held.length) return "";
+  const line = (task) => `- ${task.id}: ${task.objective}${task.origin_agent ? ` (from ${task.origin_agent})` : ""}`;
+  return ["Harness task board:", ...(waiting.length ? [`${waiting.length} task${waiting.length === 1 ? "" : "s"} waiting for you:`, ...waiting.slice(0, 5).map(line)] : []),
+    ...(held.length ? [`${held.length} you already claimed:`, ...held.slice(0, 5).map(line)] : []),
+    "Read one with get_task, claim it with claim_task before working, and report_task when done or stuck."].join("\n");
+}
 let nextId = 1;
 let typeApi = null;
 
@@ -88,5 +119,12 @@ export default function tryHarness(pi) {
     return connecting;
   };
   pi.on("session_start", (_event, ctx) => void connect(ctx).catch((error) => ctx?.ui?.notify?.("Harness unavailable: " + error?.message, "warning")));
+  pi.on("session_start", async (_event, ctx) => {
+    const nudge = await boardNudge();
+    if (!nudge) return;
+    // Into the model's context when pi offers it; always visible to the person.
+    if (typeof pi.sendMessage === "function") { try { pi.sendMessage({ customType: "harness-board", content: nudge, display: true }); } catch {} }
+    ctx?.ui?.notify?.(nudge.split("\n").slice(0, 2).join(" "), "info");
+  });
   pi.registerCommand("harness-reconnect", { description: "Reconnect Harness", handler: async (_args, ctx) => connect(ctx) });
 }

package/cli.mjs

@@ -3,16 +3,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { configureAgents, AGENTS, removeAgentConfigurations } from "./lib/adapters.mjs";
+import { configureAgents, AGENTS, MCP_CLIENTS, detectMcpClients, mcpClientSnippet, removeAgentConfigurations } from "./lib/adapters.mjs";
 import { detectAgents } from "./lib/commands.mjs";
 import { daemonRequest } from "./lib/control-client.mjs";
 import { ensureDir, readJson, writeJsonAtomic } from "./lib/files.mjs";
 import { paths } from "./lib/paths.mjs";
-import { installRuntime } from "./lib/runtime-install.mjs";
+import { currentRuntime, installRuntime } from "./lib/runtime-install.mjs";
 import { installService, serviceInfo, uninstallService } from "./lib/service.mjs";
 
 const SOURCE_ROOT = path.dirname(fileURLToPath(import.meta.url));
-const PACKAGE = readJson(path.join(SOURCE_ROOT, "package.json"), { version: "0.4.1" });
+const PACKAGE = readJson(path.join(SOURCE_ROOT, "package.json"), { version: "0.4.3" });
 const VERSION = PACKAGE.version;
 const NODE_MAJOR = Number(process.versions.node.split(".")[0]);
 if (!Number.isFinite(NODE_MAJOR) || NODE_MAJOR < 18) {
@@ -31,6 +31,18 @@ function arg(flag, fallback = null) {
   return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
 }
 function has(flag) { return argv.includes(flag); }
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+function shellQuote(value) { return `'${String(value).replace(/'/g, `'\\''`)}'`; }
+function resumeCommand(agent, sessionId, cwd) {
+  const command = agent === "claude-code"
+    ? `claude --dangerously-skip-permissions --resume ${shellQuote(sessionId)}`
+    : agent === "codex"
+      ? `codex resume --dangerously-bypass-approvals-and-sandbox ${shellQuote(sessionId)}`
+      : agent === "pi"
+        ? `pi --approve --session ${shellQuote(sessionId)}`
+        : `opencode --auto --session ${shellQuote(sessionId)}`;
+  return cwd ? `cd ${shellQuote(cwd)} && ${command}` : command;
+}
 function origin() {
   const saved = readJson(paths.config, {});
   return String(arg("--origin", saved.origin || "https://tryharness.ai")).replace(/\/$/, "");
@@ -138,6 +150,9 @@ async function connect() {
   config = { ...readJson(paths.config, config), version: VERSION, runtimeRoot, agentStates: stateMap };
   writeJsonAtomic(paths.config, config);
   printAgentStates(states);
+  for (const client of detectMcpClients()) {
+    if (client.path) console.log(`  ! ${client.client}: found; it joins the task board once you paste its MCP snippet (npx tryharness mcp ${client.client})`);
+  }
 
   const service = installService({ runtimeRoot });
   const ready = await waitForDaemon();
@@ -199,18 +214,109 @@ async function sync() {
   console.log(`Local history scan started for ${agent}. It runs in the daemon; this terminal does not need to stay open.`);
 }
 
-async function handoff() {
-  const agent = argv[0];
-  if (!AGENTS.includes(agent)) throw new Error("usage: tryharness handoff <claude-code|codex|pi|opencode> --file <brief.md>");
-  const file = arg("--file");
-  let body = "";
-  if (file) body = fs.readFileSync(path.resolve(file), "utf8");
-  else if (!process.stdin.isTTY) for await (const chunk of process.stdin) body += chunk;
-  else body = arg("--body", "");
-  if (!body.trim()) throw new Error("handoff needs --file, --body, or piped input");
-  const response = await daemonRequest({ command: "handoffs.create", agent, sessionId: arg("--session"), title: arg("--title", path.basename(file || "Harness handoff")), body, source: file ? path.resolve(file) : "tryharness CLI" });
-  if (!response.ok) throw new Error(response.error || "handoff failed");
-  console.log(`Handoff ${response.id} is ready for ${agent}. Harness's get_handoff tool can read it.`);
+async function mcpSnippet() {
+  const client = argv[0];
+  if (!MCP_CLIENTS.includes(client)) throw new Error(`usage: tryharness mcp <${MCP_CLIENTS.join("|")}>`);
+  const config = readJson(paths.config, {});
+  const runtimeRoot = config.runtimeRoot || currentRuntime();
+  if (!runtimeRoot) throw new Error("no Harness runtime is installed yet; run npx tryharness first");
+  const found = detectMcpClients().find((entry) => entry.client === client);
+  console.log(`${client}: ${found?.path ? `found at ${found.path}` : "not found on this machine; the snippet still works once it is installed"}`);
+  console.log(`In ${client === "grok-bot" ? "Grok Bot, open Settings, MCP, add a server" : client} and paste this:\n`);
+  console.log(JSON.stringify(mcpClientSnippet({ runtimeRoot, client }), null, 2));
+  console.log(`\nIt then sees the board through list_tasks, get_task, post_task, claim_task and report_task as "${client}".`);
+}
+
+async function board() {
+  const sub = argv.find((value) => !value.startsWith("--")) || "list";
+  const agent = arg("--as", "user");
+  if (sub === "post") {
+    const target = arg("--for");
+    if (target && !AGENTS.includes(target) && target !== "harness" && target !== "grok-bot") throw new Error("usage: tryharness board post --for <agent> --objective <text> [--file <brief.md>] [--run --workspace <dir>]");
+    const objective = arg("--objective", "");
+    const file = arg("--file");
+    let brief = "";
+    if (file) brief = fs.readFileSync(path.resolve(file), "utf8");
+    else if (!process.stdin.isTTY) for await (const chunk of process.stdin) brief += chunk;
+    if (!objective.trim()) throw new Error("board post needs --objective");
+    const runWorkspace = has("--run") ? path.resolve(arg("--workspace", process.cwd())) : null;
+    if (runWorkspace && !AGENTS.includes(target)) throw new Error("--run needs --for with a coding agent installed on this machine");
+    const response = await daemonRequest({ command: "board.post", agent, objective, brief, targetAgent: target || null, runWorkspace });
+    if (!response.ok) throw new Error(response.error || "post failed");
+    if (runWorkspace) console.log(`Task ${response.task.id} is on the board and ${target} will run it in ${runWorkspace}. Follow it: npx tryharness task ${response.task.id} --follow`);
+    else console.log(`Task ${response.task.id} is on the board${target ? ` for ${target}` : ""}. Any agent's list_tasks tool shows it.`);
+    return;
+  }
+  if (sub === "run" || sub === "release") {
+    const id = String(argv[argv.indexOf(sub) + 1] || "");
+    const response = await daemonRequest({ command: sub === "run" ? "board.run" : "board.release", agent, id });
+    if (!response.ok) throw new Error(response.error || `${sub} failed`);
+    console.log(sub === "run" ? `Run authorized; ${response.task.target_agent} starts it now. Follow it: npx tryharness task ${id} --follow` : `Task ${id} is open again.`);
+    return;
+  }
+  if (sub === "agents") {
+    const response = await daemonRequest({ command: "board.agents", agent });
+    if (!response.ok) throw new Error(response.error || "board unavailable");
+    if (!response.agents.length) { console.log("No agent has read the board yet."); return; }
+    for (const row of response.agents) console.log(`${row.agent.padEnd(14)} last seen ${row.last_seen_at}${response.running.some((run) => run.agent === row.agent) ? " · running a task" : ""}`);
+    return;
+  }
+  if (sub === "show") {
+    const response = await daemonRequest({ command: "board.get", agent, id: String(argv[argv.indexOf("show") + 1] || "") });
+    if (!response.ok) throw new Error(response.error || "task not found");
+    const { task: t } = response;
+    console.log(`${t.id} · ${t.status}${t.stale ? " (stale claim)" : ""} · from ${t.origin_agent}${t.target_agent ? ` for ${t.target_agent}` : ""}${t.claimed_by ? ` · claimed by ${t.claimed_by}` : ""} · held by ${t.holder || "nobody"} · version ${t.version}\n${t.objective}\n`);
+    if (t.run_workspace) console.log(`run: ${t.run_authorized_at ? `authorized by ${t.run_authorized_by}` : "requested, waiting for: npx tryharness board run " + t.id} · ${t.run_workspace}${t.session_id ? `\nagent session: ${t.session_id}\nopen live session: ${resumeCommand(t.target_agent, t.session_id, t.run_workspace)}` : ""}\n`);
+    if (t.brief) console.log(t.brief + "\n");
+    if (t.result) console.log(`${t.status === "needs_input" ? "question" : "result"}: ${t.result}`);
+    return;
+  }
+  if (sub !== "list") throw new Error("usage: tryharness board [list --all | show <id> | post --for <agent> --objective <text> [--file <brief.md>] [--run --workspace <dir>] | run <id> | release <id> | agents]");
+  const response = await daemonRequest({ command: "board.list", agent, all: has("--all") });
+  if (!response.ok) throw new Error(response.error || "board unavailable");
+  if (!response.tasks.length) { console.log("The board is empty."); return; }
+  for (const t of response.tasks) console.log(`${t.id}  ${(t.stale ? "stale" : t.status).padEnd(11)} ${t.origin_agent} → ${t.target_agent || "anyone"}${t.claimed_by ? ` (${t.claimed_by})` : ""}${t.run_workspace && !t.run_authorized_at ? " [wants to run]" : ""}  ${t.objective}`);
+}
+
+async function task() {
+  const runId = String(argv[0] || "").trim();
+  if (!/^[a-zA-Z0-9._-]{1,128}$/.test(runId)) throw new Error("usage: tryharness task <run-id> [--follow]");
+  const follow = has("--follow") || has("-f");
+  let offset = Math.max(0, Math.floor(Number(arg("--offset", "0")) || 0));
+  let announced = false;
+  let sessionShown = null;
+  let misses = 0;
+  for (;;) {
+    const response = await daemonRequest({ command: "tasks.get", runId, offset });
+    if (!response.ok) {
+      if (follow && misses < 10) { misses += 1; await sleep(500); continue; }
+      throw new Error(response.error || `task ${runId} was not found on this machine`);
+    }
+    misses = 0;
+    const current = response.task;
+    if (!announced) {
+      console.log(`Harness task ${runId} · ${current.agent} · ${current.status}`);
+      if (current.cwd) console.log(`directory: ${current.cwd}`);
+      if (follow) console.log("following machine-local agent output (Ctrl-C stops following, not the task)\n");
+      announced = true;
+    }
+    if (current.log) process.stdout.write(current.log);
+    offset = current.nextOffset;
+    if (current.sessionId && current.sessionId !== sessionShown) {
+      sessionShown = current.sessionId;
+      console.log(`\nagent session: ${current.sessionId}`);
+      console.log(`open live session: ${resumeCommand(current.agent, current.sessionId, current.cwd)}`);
+    }
+    const terminal = current.status === "done" || current.status === "failed" || current.status === "interrupted";
+    if (!follow || (terminal && offset >= current.logLength)) {
+      console.log(`\nstatus: ${current.status}`);
+      if (current.message) console.log(current.message);
+      if (current.status === "interrupted") console.log("The daemon restarted during this run; its outcome is unknown. Check the repository.");
+      if (current.status !== "done") process.exitCode = 1;
+      return;
+    }
+    await sleep(500);
+  }
 }
 
 function logs() {
@@ -230,7 +336,7 @@ async function disconnect() {
 }
 
 function help() {
-  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness handoff <agent> --file <path>\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
+  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness task <id> --follow\n                             follow a delegated agent run in this terminal\n  tryharness board [--all]   list open work on the machine's task board\n  tryharness board post --for <agent> --objective <text> [--file <brief.md>]\n  tryharness board show <id>\n  tryharness board post --for codex --objective <text> --run --workspace <dir>\n                             the daemon runs it and reports back on the task\n  tryharness board run <id>  authorize a run an agent asked for\n  tryharness board release <id>\n  tryharness board agents    when each agent last read the board\n  tryharness mcp grok-bot    print the MCP snippet that puts Grok Bot on the board\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
 }
 
 try {
@@ -238,7 +344,9 @@ try {
   else if (command === "status" || command === "bridge") await status();
   else if (command === "doctor") await doctor();
   else if (command === "sync" || command === "backfill" || command === "drain") await sync();
-  else if (command === "handoff") await handoff();
+  else if (command === "task") await task();
+  else if (command === "board") await board();
+  else if (command === "mcp") await mcpSnippet();
   else if (command === "logs") logs();
   else if (command === "disconnect") await disconnect();
   else if (command === "daemon") { const { startDaemon } = await import("./lib/daemon.mjs"); await startDaemon(); }

package/lib/adapters.mjs

@@ -7,6 +7,23 @@ import { paths } from "./paths.mjs";
 
 export const AGENTS = ["claude-code", "codex", "pi", "opencode"];
 
+// MCP clients that are not coding agents: no history to index and nothing to run, but they
+// join the machine's task board by launching the same stdio MCP under their own name.
+export const MCP_CLIENTS = ["grok-bot"];
+const MCP_CLIENT_APPS = {
+  "grok-bot": { darwin: ["/Applications/Grok Bot.app", path.join(os.homedir(), "Applications", "Grok Bot.app")] },
+};
+
+export function detectMcpClients({ platform = process.platform, exists = fs.existsSync } = {}) {
+  return MCP_CLIENTS.map((client) => ({ client, path: (MCP_CLIENT_APPS[client][platform] || []).find((candidate) => exists(candidate)) || null }));
+}
+
+// Grok Bot keeps its MCP server list in its account and writes it only from its own settings
+// (a one-server JSON paste); there is no file on disk to write. The snippet is the setup.
+export function mcpClientSnippet({ runtimeRoot, client, nodePath = process.execPath }) {
+  return { mcpServers: { harness: { command: nodePath, args: [path.join(runtimeRoot, "lib", "mcp-stdio.mjs"), "--agent", client] } } };
+}
+
 function installAsset(source, target) {
   ensureDir(path.dirname(target));
   fs.copyFileSync(source, target);
@@ -24,6 +41,32 @@ export function integrationAssets(homeDir = os.homedir()) {
   };
 }
 
+// Claude Code learns about waiting board work through a SessionStart hook whose stdout joins
+// its context. The hook is one entry in the user's settings, added once and removed on
+// disconnect; every other setting and hook is left as it was.
+export function claudeSettingsPath(homeDir = os.homedir()) {
+  return path.join(homeDir, ".claude", "settings.json");
+}
+const isHarnessHook = (entry) => JSON.stringify(entry).includes("/lib/nudge.mjs");
+
+export function installClaudeSessionHook({ runtimeRoot, homeDir = os.homedir(), nodePath = process.execPath }) {
+  const file = claudeSettingsPath(homeDir);
+  const settings = readJson(file, {});
+  const hooks = settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const starts = (Array.isArray(hooks.SessionStart) ? hooks.SessionStart : []).filter((entry) => !isHarnessHook(entry));
+  starts.push({ hooks: [{ type: "command", command: `${JSON.stringify(nodePath)} ${JSON.stringify(path.join(runtimeRoot, "lib", "nudge.mjs"))} --agent claude-code`, timeout: 10 }] });
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks: { ...hooks, SessionStart: starts } }, null, 2) + "\n");
+}
+
+export function removeClaudeSessionHook(homeDir = os.homedir()) {
+  const file = claudeSettingsPath(homeDir);
+  const settings = readJson(file, null);
+  if (!settings?.hooks || !Array.isArray(settings.hooks.SessionStart)) return;
+  const starts = settings.hooks.SessionStart.filter((entry) => !isHarnessHook(entry));
+  fs.writeFileSync(file, JSON.stringify({ ...settings, hooks: { ...settings.hooks, SessionStart: starts } }, null, 2) + "\n");
+}
+
 export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.homedir(), detected = detectAgents(), execute = run, connection = readJson(paths.config, {}) }) {
   const byAgent = new Map(detected.map((entry) => [entry.agent, entry]));
   const mcpPath = path.join(runtimeRoot, "lib", "mcp-stdio.mjs");
@@ -42,7 +85,9 @@ export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.h
     if (agent === "claude-code") {
       execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
       const added = execute(found.path, ["mcp", "add", "--scope", "user", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
-      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP configured" : diagnostic(added) });
+      let hooked = true;
+      try { installClaudeSessionHook({ runtimeRoot, homeDir }); } catch { hooked = false; }
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? (hooked ? "MCP and session-start nudge configured" : "MCP configured; the session-start hook could not be written") : diagnostic(added) });
     } else if (agent === "codex") {
       execute(found.path, ["mcp", "remove", "harness"]);
       const added = execute(found.path, ["mcp", "add", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
@@ -69,7 +114,7 @@ export function agentHealth(states) {
 export function removeAgentConfigurations({ homeDir = os.homedir(), detected = detectAgents(), execute = run } = {}) {
   for (const found of detected) {
     if (!found.path) continue;
-    if (found.agent === "claude-code") execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
+    if (found.agent === "claude-code") { execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]); removeClaudeSessionHook(homeDir); }
     else if (found.agent === "codex" || found.agent === "opencode") execute(found.path, ["mcp", "remove", "harness"]);
   }
   const assets = integrationAssets(homeDir);