fathom-mcp 0.4.5 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-mcp",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "MCP server for Fathom — vault operations, search, rooms, and cross-workspace communication",
   "type": "module",
   "bin": {

package/scripts/fathom-sessionstart.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Fathom SessionStart hook — version check on session startup.
+# Compares local .fathom/version against npm registry and injects update notice.
+#
+# Output: JSON with hookSpecificOutput.additionalContext (update notice or empty).
+# Graceful failure: if npm unreachable or version file missing, skip silently.
+
+set -o pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+TOAST="$HOOK_DIR/hook-toast.sh"
+
+# Consume stdin (SessionStart sends JSON we don't need)
+cat > /dev/null
+
+# Walk up to find .fathom.json
+find_config() {
+  local dir="$PWD"
+  while [ "$dir" != "/" ]; do
+    if [ -f "$dir/.fathom.json" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+PROJECT_DIR=$(find_config 2>/dev/null) || exit 0
+
+VERSION_FILE="$PROJECT_DIR/.fathom/version"
+
+# If no version file, skip silently — init hasn't been run with this version yet
+if [ ! -f "$VERSION_FILE" ]; then
+    exit 0
+fi
+
+LOCAL_VERSION=$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')
+if [ -z "$LOCAL_VERSION" ]; then
+    exit 0
+fi
+
+# Check npm registry for latest version (2s timeout)
+LATEST_VERSION=$(curl -s --max-time 2 "https://registry.npmjs.org/fathom-mcp/latest" 2>/dev/null \
+    | python3 -c "import json,sys; print(json.load(sys.stdin).get('version',''))" 2>/dev/null || echo "")
+
+# If npm check failed, skip silently
+if [ -z "$LATEST_VERSION" ]; then
+    "$TOAST" fathom "✓ Fathom v${LOCAL_VERSION}" &>/dev/null
+    exit 0
+fi
+
+# Compare versions
+if [ "$LOCAL_VERSION" != "$LATEST_VERSION" ]; then
+    # Update available — inject notice and show toast
+    "$TOAST" fathom "⬆ Fathom v${LATEST_VERSION} available" &>/dev/null
+
+    python3 -c "
+import json
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'SessionStart',
+        'additionalContext': 'Fathom update available: v${LOCAL_VERSION} → v${LATEST_VERSION}. Run: npx fathom-mcp update'
+    }
+}))
+"
+else
+    # Up to date — toast only, no context injection
+    "$TOAST" fathom "✓ Fathom v${LOCAL_VERSION}" &>/dev/null
+fi
+
+exit 0

package/src/cli.js

@@ -7,14 +7,16 @@
  *   npx fathom-mcp          — Start MCP server (stdio, for .mcp.json)
  *   npx fathom-mcp init     — Interactive setup wizard
  *   npx fathom-mcp status   — Check server connection + workspace status
+ *   npx fathom-mcp update   — Update hook scripts + version file
  */
 
 import fs from "fs";
 import path from "path";
 import readline from "readline";
+import { execFileSync } from "child_process";
 import { fileURLToPath } from "url";
 
-import { resolveConfig, writeConfig } from "./config.js";
+import { findConfigFile, resolveConfig, writeConfig } from "./config.js";
 import { createClient } from "./server-client.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -105,6 +107,90 @@ function copyScripts(targetDir) {
   }
 }
 
+// --- Headless agent integration ----------------------------------------------
+
+const HEADLESS_CMDS = {
+  "claude-code": (prompt) => ["claude", "-p", prompt],
+  "codex":       (prompt) => ["codex", "exec", prompt],
+  "gemini":      (prompt) => ["gemini", prompt],
+  "opencode":    (prompt) => ["opencode", "run", prompt],
+};
+
+function buildIntegrationPrompt(blob) {
+  return [
+    "The following instructions were generated by fathom-mcp init for this project.",
+    "Add them to the file where you store persistent behavioral instructions",
+    "(e.g. CLAUDE.md for Claude Code). If the file exists, read it first and",
+    "integrate the new section without removing existing content. If a section",
+    "with the same heading already exists, replace it. If no instructions file",
+    "exists yet, create one.",
+    "",
+    "--- INSTRUCTIONS ---",
+    blob,
+    "--- END ---",
+  ].join("\n");
+}
+
+/**
+ * Check if fathom-server is available on PATH.
+ * Returns "installed" or "not-found".
+ */
+function detectFathomServer() {
+  try {
+    execFileSync("which", ["fathom-server"], { stdio: "pipe" });
+    return "installed";
+  } catch {
+    return "not-found";
+  }
+}
+
+function runAgentHeadless(agentKey, prompt) {
+  const cmdBuilder = HEADLESS_CMDS[agentKey];
+  if (!cmdBuilder) return null;
+  const [cmd, ...args] = cmdBuilder(prompt);
+  try {
+    const result = execFileSync(cmd, args, {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "inherit"],
+      timeout: 60000,
+    });
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+// --- CLI flag parsing --------------------------------------------------------
+
+function parseFlags(argv) {
+  const flags = {
+    nonInteractive: false,
+    apiKey: null,
+    server: null,
+    workspace: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "-y" || argv[i] === "--yes") {
+      flags.nonInteractive = true;
+    } else if (argv[i] === "--api-key" && argv[i + 1]) {
+      flags.apiKey = argv[i + 1];
+      i++;
+    } else if (argv[i] === "--server" && argv[i + 1]) {
+      flags.server = argv[i + 1];
+      i++;
+    } else if (argv[i] === "--workspace" && argv[i + 1]) {
+      flags.workspace = argv[i + 1];
+      i++;
+    }
+  }
+  // Check environment variables as fallback
+  if (!flags.apiKey && process.env.FATHOM_API_KEY) {
+    flags.apiKey = process.env.FATHOM_API_KEY;
+  }
+  return flags;
+}
+
 // --- Agent registry ----------------------------------------------------------
 
 const MCP_SERVER_ENTRY = {
@@ -208,9 +294,18 @@ export { AGENTS, writeMcpJson, writeCodexToml, writeGeminiJson, writeOpencodeJso
 
 // --- Init wizard -------------------------------------------------------------
 
-async function runInit() {
+async function runInit(flags = {}) {
+  const {
+    nonInteractive = false,
+    apiKey: flagApiKey = null,
+    server: flagServer = null,
+    workspace: flagWorkspace = null,
+  } = flags;
   const cwd = process.cwd();
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const rl = nonInteractive
+    ? null
+    : readline.createInterface({ input: process.stdin, output: process.stdout });
 
   console.log(`
 ▐▘  ▗ ▌
@@ -221,83 +316,152 @@ async function runInit() {
   hifathom.com  ·  fathom@myrakrusemark.com
 `);
 
+  // Non-interactive: require API key
+  if (nonInteractive && !flagApiKey) {
+    console.error("  Error: --api-key required in non-interactive mode.");
+    process.exit(1);
+  }
+
   // Check for existing config in *this* directory only (don't walk up —
   // a parent's .fathom.json belongs to a different workspace)
   const localConfigPath = path.join(cwd, ".fathom.json");
   if (fs.existsSync(localConfigPath)) {
-    console.log(`  Found existing config at: ${localConfigPath}`);
-    const proceed = await askYesNo(rl, "  Overwrite?", false);
-    if (!proceed) {
-      console.log("  Aborted.");
-      rl.close();
-      process.exit(0);
+    if (nonInteractive) {
+      console.log(`  Overwriting existing config at: ${localConfigPath}`);
+    } else {
+      console.log(`  Found existing config at: ${localConfigPath}`);
+      const proceed = await askYesNo(rl, "  Overwrite?", false);
+      if (!proceed) {
+        console.log("  Aborted.");
+        rl.close();
+        process.exit(0);
+      }
     }
   }
 
   // 1. Workspace name
   const defaultName = path.basename(cwd);
-  const workspace = await ask(rl, "  Workspace name", defaultName);
-
-  // 2. Vault subdirectory
-  const vault = await ask(rl, "  Vault subdirectory", "vault");
+  const workspace = nonInteractive
+    ? (flagWorkspace || defaultName)
+    : await ask(rl, "  Workspace name", defaultName);
 
-  // 3. Description (optional)
-  const description = await ask(rl, "  Workspace description (optional)", "");
+  // 2. Description (optional)
+  const description = nonInteractive ? "" : await ask(rl, "  Workspace description (optional)", "");
 
   // 4. Agent selection — auto-detect and let user choose
   const agentKeys = Object.keys(AGENTS);
   const detected = agentKeys.filter((key) => AGENTS[key].detect(cwd));
 
-  console.log("\n  Detected agents:");
-  for (const key of agentKeys) {
-    const agent = AGENTS[key];
-    const isDetected = detected.includes(key);
-    const mark = isDetected ? "✓" : " ";
-    const markers = { "claude-code": ".claude/", "codex": ".codex/", "gemini": ".gemini/", "opencode": "opencode.json" };
-    const hint = isDetected ? ` (${markers[key] || key} found)` : "";
-    console.log(`    ${mark} ${agent.name}${hint}`);
-  }
+  let selectedAgents;
+  if (nonInteractive) {
+    selectedAgents = detected.length > 0 ? [detected[0]] : ["claude-code"];
+    console.log(`  Agent: ${AGENTS[selectedAgents[0]].name} (auto-detected)`);
+  } else {
+    console.log("\n  Detected agents:");
+    for (const key of agentKeys) {
+      const agent = AGENTS[key];
+      const isDetected = detected.includes(key);
+      const mark = isDetected ? "✓" : " ";
+      const markers = { "claude-code": ".claude/", "codex": ".codex/", "gemini": ".gemini/", "opencode": "opencode.json" };
+      const hint = isDetected ? ` (${markers[key] || key} found)` : "";
+      console.log(`    ${mark} ${agent.name}${hint}`);
+    }
 
-  console.log("\n  Configure for which agents?");
-  agentKeys.forEach((key, i) => {
-    const agent = AGENTS[key];
-    const mark = detected.includes(key) ? " ✓" : "";
-    console.log(`    ${i + 1}. ${agent.name}${mark}`);
-  });
+    console.log("\n  Configure for which agents?");
+    agentKeys.forEach((key, i) => {
+      const agent = AGENTS[key];
+      const mark = detected.includes(key) ? " ✓" : "";
+      console.log(`    ${i + 1}. ${agent.name}${mark}`);
+    });
 
-  const defaultSelection = detected.length > 0
-    ? detected.map((key) => agentKeys.indexOf(key) + 1).join(",")
-    : "1";
-  const selectionStr = await ask(rl, "\n  Enter numbers, comma-separated", defaultSelection);
+    const defaultSelection = detected.length > 0
+      ? detected.map((key) => agentKeys.indexOf(key) + 1).join(",")
+      : "1";
+    const selectionStr = await ask(rl, "\n  Enter numbers, comma-separated", defaultSelection);
 
-  const selectedIndices = selectionStr
-    .split(",")
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => n >= 1 && n <= agentKeys.length);
-  const selectedAgents = [...new Set(selectedIndices.map((i) => agentKeys[i - 1]))];
+    const selectedIndices = selectionStr
+      .split(",")
+      .map((s) => parseInt(s.trim(), 10))
+      .filter((n) => n >= 1 && n <= agentKeys.length);
+    selectedAgents = [...new Set(selectedIndices.map((i) => agentKeys[i - 1]))];
 
-  if (selectedAgents.length === 0) {
-    console.log("  No agents selected. Defaulting to Claude Code.");
-    selectedAgents.push("claude-code");
+    if (selectedAgents.length === 0) {
+      console.log("  No agents selected. Defaulting to Claude Code.");
+      selectedAgents.push("claude-code");
+    }
   }
 
   // 5. Server URL
-  const serverUrl = await ask(rl, "\n  Fathom server URL", "http://localhost:4243");
+  const serverUrl = nonInteractive
+    ? (flagServer || "http://localhost:4243")
+    : await ask(rl, "\n  Fathom server URL", "http://localhost:4243");
 
   // 6. API key
-  const apiKey = await ask(rl, "  API key (from dashboard or server first-run output)", "");
+  const apiKey = flagApiKey || (nonInteractive ? "" : await ask(rl, "  API key (from dashboard or server first-run output)", ""));
+
+  // 7. Server probe — check reachability early
+  const regClient = createClient({ server: serverUrl, apiKey, workspace });
+  const serverReachable = serverUrl ? await regClient.healthCheck() : false;
+  const serverOnPath = detectFathomServer();
+
+  if (!serverReachable) {
+    console.log(`\n  ⚠ Fathom server not reachable at ${serverUrl}\n`);
+    if (serverOnPath === "installed") {
+      console.log("  Start it:  fathom-server");
+    } else {
+      console.log("  Install & start it:");
+      console.log("    pip install fathom-server && fathom-server");
+      console.log("    # or: docker run -p 4243:4243 ghcr.io/myra/fathom-server");
+    }
+    console.log("\n  Without the server, only \"local\" and \"none\" vault modes are available.");
+  }
 
-  // 7. Hooks — only ask if Claude Code is selected
+  // 8. Vault mode selection
+  let vaultMode;
+  if (nonInteractive) {
+    vaultMode = serverReachable ? "hosted" : "local";
+    console.log(`  Vault mode: ${vaultMode} (auto-selected)`);
+  } else {
+    if (serverReachable) {
+      console.log("\n  Vault mode:");
+      console.log("    1. Hosted (default) — vault stored on server, accessible everywhere");
+      console.log("    2. Synced — local vault + server mirror (local is source of truth)");
+      console.log("    3. Local — vault on disk only, not visible to server");
+      console.log("    4. None — no vault, coordination features only");
+      const modeChoice = await ask(rl, "\n  Select mode", "1");
+      const modeMap = { "1": "hosted", "2": "synced", "3": "local", "4": "none" };
+      vaultMode = modeMap[modeChoice] || "hosted";
+    } else {
+      console.log("\n  Vault mode (server not available — hosted/synced require server):");
+      console.log("    1. Local (default) — vault on disk only");
+      console.log("    2. None — no vault, coordination features only");
+      const modeChoice = await ask(rl, "\n  Select mode", "1");
+      vaultMode = modeChoice === "2" ? "none" : "local";
+    }
+  }
+
+  // Only ask about vault subdirectory if mode needs a local dir
+  const needsLocalVault = vaultMode === "synced" || vaultMode === "local";
+  const vault = needsLocalVault
+    ? (nonInteractive ? "vault" : await ask(rl, "  Vault subdirectory", "vault"))
+    : "vault";
+
+  // 9. Hooks — only ask if Claude Code is selected
   const hasClaude = selectedAgents.includes("claude-code");
   let enableRecallHook = false;
   let enablePrecompactHook = false;
   if (hasClaude) {
-    console.log();
-    enableRecallHook = await askYesNo(rl, "  Enable vault recall on every message (UserPromptSubmit)?", true);
-    enablePrecompactHook = await askYesNo(rl, "  Enable PreCompact vault snapshot hook?", true);
+    if (nonInteractive) {
+      enableRecallHook = true;
+      enablePrecompactHook = true;
+    } else {
+      console.log();
+      enableRecallHook = await askYesNo(rl, "  Enable vault recall on every message (UserPromptSubmit)?", true);
+      enablePrecompactHook = await askYesNo(rl, "  Enable PreCompact vault snapshot hook?", true);
+    }
   }
 
-  rl.close();
+  rl?.close();
 
   // --- Write files ---
 
@@ -306,6 +470,7 @@ async function runInit() {
   // .fathom.json
   const configData = {
     workspace,
+    vaultMode,
     vault,
     server: serverUrl,
     apiKey,
@@ -326,13 +491,23 @@ async function runInit() {
     console.log(`  ✓ .fathom/scripts/ (${copiedScripts.length} scripts)`);
   }
 
-  // vault/ directory
-  const vaultDir = path.join(cwd, vault);
-  if (!fs.existsSync(vaultDir)) {
-    fs.mkdirSync(vaultDir, { recursive: true });
-    console.log(`  ✓ ${vault}/ (created)`);
-  } else {
-    console.log(`  · ${vault}/ (already exists)`);
+  // .fathom/version
+  const pkgJsonPath = path.join(__dirname, "..", "package.json");
+  const pkg = readJsonFile(pkgJsonPath);
+  const packageVersion = pkg?.version || "unknown";
+  const fathomDir = path.join(cwd, ".fathom");
+  fs.writeFileSync(path.join(fathomDir, "version"), packageVersion + "\n");
+  console.log(`  ✓ .fathom/version (${packageVersion})`);
+
+  // vault/ directory — only create for synced/local modes
+  if (needsLocalVault) {
+    const vaultDir = path.join(cwd, vault);
+    if (!fs.existsSync(vaultDir)) {
+      fs.mkdirSync(vaultDir, { recursive: true });
+      console.log(`  ✓ ${vault}/ (created)`);
+    } else {
+      console.log(`  · ${vault}/ (already exists)`);
+    }
   }
 
   // fathom-agents.md — boilerplate agent instructions
@@ -357,11 +532,26 @@ async function runInit() {
   }
 
   // Claude Code hooks — only if claude-code is selected
-  if (hasClaude && (enableRecallHook || enablePrecompactHook)) {
+  if (hasClaude) {
     const claudeSettingsPath = path.join(cwd, ".claude", "settings.local.json");
     const claudeSettings = readJsonFile(claudeSettingsPath) || {};
 
     const hooks = {};
+
+    // SessionStart — always registered (version check should always be on)
+    hooks["SessionStart"] = [
+      ...(claudeSettings.hooks?.["SessionStart"] || []),
+    ];
+    const sessionStartCmd = "bash .fathom/scripts/fathom-sessionstart.sh";
+    const hasFathomSessionStart = hooks["SessionStart"].some((entry) =>
+      entry.hooks?.some((h) => h.command === sessionStartCmd)
+    );
+    if (!hasFathomSessionStart) {
+      hooks["SessionStart"].push({
+        hooks: [{ type: "command", command: sessionStartCmd, timeout: 10000 }],
+      });
+    }
+
     if (enableRecallHook) {
       hooks["UserPromptSubmit"] = [
         ...(claudeSettings.hooks?.["UserPromptSubmit"] || []),
@@ -402,41 +592,125 @@ async function runInit() {
   appendToGitignore(cwd, [".fathom.json", ".fathom/scripts/"]);
   console.log("  ✓ .gitignore");
 
-  // Register with server (best-effort)
-  if (serverUrl) {
-    const regClient = createClient({ server: serverUrl, apiKey, workspace });
-    const isUp = await regClient.healthCheck();
-    if (isUp) {
-      const regResult = await regClient.registerWorkspace(workspace, cwd, {
-        vault,
-        description,
-        agents: selectedAgents,
-        type: selectedAgents[0] || "local",
-      });
-      if (regResult.ok) {
-        console.log(`  ✓ Registered workspace "${workspace}" with server`);
-      } else if (regResult.error) {
-        console.log(`  · Server: ${regResult.error}`);
-      }
+  // Register with server
+  if (serverReachable) {
+    const regResult = await regClient.registerWorkspace(workspace, cwd, {
+      vault,
+      description,
+      agents: selectedAgents,
+      type: selectedAgents[0] || "local",
+    });
+    if (regResult.ok) {
+      console.log(`  ✓ Registered workspace "${workspace}" with server`);
+    } else if (regResult.error) {
+      console.log(`  · Server registration: ${regResult.error}`);
     }
   }
 
-  // Per-agent next steps
+  // Context-aware next steps
   console.log(`\n  Done! Fathom MCP is configured for workspace "${workspace}".`);
+  console.log(`  Vault mode: ${vaultMode}`);
   console.log("\n  Next steps:");
-  console.log("    1. Start the server:  cd fathom-server && python app.py");
+
+  if (!serverReachable) {
+    if (serverOnPath === "installed") {
+      console.log("    1. Start the server:  fathom-server");
+    } else {
+      console.log("    1. Install & start the server:  pip install fathom-server && fathom-server");
+    }
+  }
+
+  const stepNum = serverReachable ? 1 : 2;
+  switch (vaultMode) {
+    case "hosted":
+      console.log(`    ${stepNum}. Your vault is stored on the server. Start writing!`);
+      break;
+    case "synced":
+      console.log(`    ${stepNum}. Local vault syncs to server. Files in ./${vault}/ are the source of truth.`);
+      break;
+    case "local":
+      console.log(`    ${stepNum}. Local vault only. Server can't search or peek into it.`);
+      break;
+    case "none":
+      console.log(`    ${stepNum}. No vault configured. Rooms, messaging, and search still work.`);
+      break;
+  }
   for (const agentKey of selectedAgents) {
     const agent = AGENTS[agentKey];
     console.log(`    · ${agent.name}: ${agent.nextSteps}`);
   }
+
+  // Auto-integrate agent instructions
+  const agentMdPath = path.join(cwd, ".fathom", "fathom-agents.md");
+  let instructionsBlob = "";
+  try {
+    instructionsBlob = fs.readFileSync(agentMdPath, "utf-8");
+  } catch { /* file wasn't created — use empty */ }
+
+  const primaryAgent = selectedAgents[0];
+
+  if (instructionsBlob) {
+    const prompt = buildIntegrationPrompt(instructionsBlob);
+    const cmdParts = HEADLESS_CMDS[primaryAgent]?.(prompt);
+
+    if (nonInteractive) {
+      if (cmdParts) {
+        console.log(`\n  Integrating instructions via ${AGENTS[primaryAgent].name}...`);
+        const result = runAgentHeadless(primaryAgent, prompt);
+        if (result !== null) {
+          console.log(result);
+        } else {
+          console.log("  Agent integration failed — paste these instructions manually:\n");
+          printInstructionsFallback(agentMdPath, selectedAgents);
+        }
+      } else {
+        printInstructionsFallback(agentMdPath, selectedAgents);
+      }
+    } else {
+      if (cmdParts) {
+        const [cmd, ...args] = cmdParts;
+        const displayCmd = `${cmd} ${args[0]}${args.length > 1 ? " ..." : ""}`;
+        const rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+        console.log("\n" + "─".repeat(60));
+        const integrate = await askYesNo(
+          rl2,
+          `\n  Auto-integrate instructions into your project?\n  This will run: ${displayCmd}\n\n  Proceed?`,
+          true,
+        );
+        rl2.close();
+
+        if (integrate) {
+          console.log(`\n  Running ${AGENTS[primaryAgent].name}...`);
+          const result = runAgentHeadless(primaryAgent, prompt);
+          if (result !== null) {
+            console.log(result);
+          } else {
+            console.log("  Agent integration failed — paste these instructions manually:\n");
+            printInstructionsFallback(agentMdPath, selectedAgents);
+          }
+        } else {
+          printInstructionsFallback(agentMdPath, selectedAgents);
+        }
+      } else {
+        printInstructionsFallback(agentMdPath, selectedAgents);
+      }
+    }
+  } else {
+    console.log("\n  No agent instructions template found — skipping integration.\n");
+  }
+}
+
+function printInstructionsFallback(agentMdPath, selectedAgents) {
+  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
+  const docTarget = hasNonClaude
+    ? "your CLAUDE.md, AGENTS.md, or equivalent"
+    : "your CLAUDE.md";
+
   console.log(`
-  Agent instructions:
-    Some instructions are needed for your agent to use Fathom + Memento
-    effectively (memory discipline, vault conventions, cross-workspace
-    communication). Saved to: .fathom/fathom-agents.md
+  Agent instructions saved to: ${path.relative(process.cwd(), agentMdPath)}
 
-    Paste it into your CLAUDE.md, AGENTS.md, or equivalent — or point
-    your agent at the file and ask it to integrate the instructions.
+  Paste into ${docTarget}, or point your agent at the file
+  and ask it to integrate the instructions.
 `);
 }
 
@@ -449,6 +723,7 @@ async function runStatus() {
   console.log("\n  Fathom MCP Status\n");
   console.log(`  Config:    ${config._configPath || "(not found — using defaults)"}`);
   console.log(`  Workspace: ${config.workspace}`);
+  console.log(`  Vault mode: ${config.vaultMode}`);
   console.log(`  Vault:     ${config.vault}`);
   console.log(`  Server:    ${config.server}`);
   console.log(`  API Key:   ${config.apiKey ? config.apiKey.slice(0, 7) + "..." + config.apiKey.slice(-4) : "(not set)"}`);
@@ -484,6 +759,72 @@ async function runStatus() {
   console.log();
 }
 
+// --- Update command ----------------------------------------------------------
+
+async function runUpdate() {
+  const found = findConfigFile(process.cwd());
+  if (!found) {
+    console.error("  Error: No .fathom.json found. Run `npx fathom-mcp init` first.");
+    process.exit(1);
+  }
+
+  const projectDir = found.dir;
+  const fathomDir = path.join(projectDir, ".fathom");
+
+  // Read package version from our own package.json
+  const pkgJsonPath = path.join(__dirname, "..", "package.json");
+  const pkg = readJsonFile(pkgJsonPath);
+  const packageVersion = pkg?.version || "unknown";
+
+  // Copy all scripts
+  const scriptsDir = path.join(fathomDir, "scripts");
+  const copiedScripts = copyScripts(scriptsDir);
+
+  // Write version file
+  fs.mkdirSync(fathomDir, { recursive: true });
+  fs.writeFileSync(path.join(fathomDir, "version"), packageVersion + "\n");
+
+  // Ensure SessionStart hook is registered for Claude Code workspaces
+  const agents = found.config.agents || [];
+  const hasClaude = agents.includes("claude-code");
+  let hooksUpdated = false;
+  if (hasClaude) {
+    const claudeSettingsPath = path.join(projectDir, ".claude", "settings.local.json");
+    const claudeSettings = readJsonFile(claudeSettingsPath) || {};
+    const sessionStartCmd = "bash .fathom/scripts/fathom-sessionstart.sh";
+    const existingHooks = claudeSettings.hooks?.["SessionStart"] || [];
+    const hasSessionStart = existingHooks.some((entry) =>
+      entry.hooks?.some((h) => h.command === sessionStartCmd)
+    );
+    if (!hasSessionStart) {
+      claudeSettings.hooks = claudeSettings.hooks || {};
+      claudeSettings.hooks["SessionStart"] = [
+        ...existingHooks,
+        { hooks: [{ type: "command", command: sessionStartCmd, timeout: 10000 }] },
+      ];
+      writeJsonFile(claudeSettingsPath, claudeSettings);
+      hooksUpdated = true;
+    }
+  }
+
+  console.log(`\n  ✓ Fathom hooks updated to v${packageVersion}\n`);
+
+  if (copiedScripts.length > 0) {
+    console.log("  Updated scripts:");
+    for (const script of copiedScripts) {
+      console.log(`    ${script}`);
+    }
+  }
+
+  if (hooksUpdated) {
+    console.log("\n  Registered hooks:");
+    console.log("    SessionStart → fathom-sessionstart.sh (version check)");
+  }
+
+  console.log(`\n  Version written to .fathom/version`);
+  console.log("  Restart your agent session to pick up changes.\n");
+}
+
 // --- Main --------------------------------------------------------------------
 
 // Guard: only run CLI when this module is the entry point (not when imported by tests)
@@ -495,7 +836,8 @@ if (isMain) {
   const command = process.argv[2];
 
   if (command === "init") {
-    runInit().catch((e) => {
+    const flags = parseFlags(process.argv.slice(3));
+    runInit(flags).catch((e) => {
       console.error(`Error: ${e.message}`);
       process.exit(1);
     });
@@ -504,12 +846,25 @@ if (isMain) {
       console.error(`Error: ${e.message}`);
       process.exit(1);
     });
+  } else if (command === "update") {
+    runUpdate().catch((e) => {
+      console.error(`Error: ${e.message}`);
+      process.exit(1);
+    });
   } else if (!command || command === "serve") {
     // Default: start MCP server
     import("./index.js");
   } else {
     console.error(`Unknown command: ${command}`);
-    console.error("Usage: fathom-mcp [init|status|serve]");
+    console.error(`Usage: fathom-mcp [init|status|update|serve]
+
+  fathom-mcp init                                    Interactive setup
+  fathom-mcp init -y --api-key KEY                   Non-interactive setup
+  fathom-mcp init -y --api-key KEY --server URL      Custom server URL
+  fathom-mcp init -y --api-key KEY --workspace NAME  Custom workspace name
+  fathom-mcp status                                  Check connection status
+  fathom-mcp update                                  Update hooks + version
+  fathom-mcp                                         Start MCP server`);
     process.exit(1);
   }
 }

package/src/config.js

@@ -12,9 +12,12 @@ import path from "path";
 
 const CONFIG_FILENAME = ".fathom.json";
 
+const VALID_VAULT_MODES = new Set(["hosted", "synced", "local", "none"]);
+
 const DEFAULTS = {
   workspace: "",
   vault: "vault",
+  vaultMode: "local", // hosted | synced | local | none
   server: "http://localhost:4243",
   apiKey: "",
   description: "",
@@ -65,6 +68,9 @@ export function resolveConfig(startDir = process.cwd()) {
     const { config } = found;
     if (config.workspace) result.workspace = config.workspace;
     if (config.vault) result.vault = config.vault;
+    if (config.vaultMode && VALID_VAULT_MODES.has(config.vaultMode)) {
+      result.vaultMode = config.vaultMode;
+    }
     if (config.server) result.server = config.server;
     if (config.apiKey) result.apiKey = config.apiKey;
     if (config.description) result.description = config.description;
@@ -81,6 +87,9 @@ export function resolveConfig(startDir = process.cwd()) {
   if (process.env.FATHOM_API_KEY) result.apiKey = process.env.FATHOM_API_KEY;
   if (process.env.FATHOM_WORKSPACE) result.workspace = process.env.FATHOM_WORKSPACE;
   if (process.env.FATHOM_VAULT_DIR) result.vault = process.env.FATHOM_VAULT_DIR;
+  if (process.env.FATHOM_VAULT_MODE && VALID_VAULT_MODES.has(process.env.FATHOM_VAULT_MODE)) {
+    result.vaultMode = process.env.FATHOM_VAULT_MODE;
+  }
 
   // Derive workspace name from directory if still empty
   if (!result.workspace) {
@@ -111,6 +120,7 @@ export function writeConfig(dir, config) {
   const filePath = path.join(dir, CONFIG_FILENAME);
   const data = {
     workspace: config.workspace,
+    vaultMode: config.vaultMode || "local",
     vault: config.vault || "vault",
     server: config.server || DEFAULTS.server,
     apiKey: config.apiKey || "",

package/src/index.js

@@ -8,6 +8,9 @@
  *   - server-client.js (HTTP to fathom-server — search, rooms, workspaces)
  */
 
+import fs from "fs";
+import path from "path";
+
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -224,13 +227,14 @@ const tools = [
       "to the latest message. Default: 60 minutes before the latest message. Use start to look " +
       "further back. Example: minutes=15, start=120 returns 15 minutes of conversation starting " +
       "2 hours before the latest message. Response includes window metadata with has_older flag " +
-      "for pseudo-pagination.",
+      "for pseudo-pagination. Automatically marks the room as read for this workspace unless mark_read=false.",
     inputSchema: {
       type: "object",
       properties: {
         room: { type: "string", description: "Room name to read from" },
         minutes: { type: "number", description: "Window duration in minutes. Default: 60." },
         start: { type: "number", description: "Offset in minutes from the latest message. Default: 0 (window ends at latest message). Set to 120 to look back starting 2 hours before the latest message." },
+        mark_read: { type: "boolean", description: "Set to false to peek without marking the room as read. Default: true." },
       },
       required: ["room"],
     },
@@ -238,8 +242,9 @@ const tools = [
   {
     name: "fathom_room_list",
     description:
-      "List all rooms with activity summary — message count, last activity time, last sender, and description. " +
-      "Use to discover active rooms.",
+      "List all rooms with activity summary — message count, last activity time, last sender, " +
+      "description, and per-room unread_count for this workspace. Use to discover active rooms " +
+      "and see which have new messages.",
     inputSchema: {
       type: "object",
       properties: {},
@@ -288,19 +293,39 @@ const tools = [
   },
 ];
 
-// --- Vault path resolution for cross-workspace reads -------------------------
+// --- Vault routing by mode ---------------------------------------------------
 
 /**
- * Resolve vault path for a tool call. If workspace param differs from config
- * workspace, we delegate to the server instead of local I/O.
+ * Resolve vault routing for a tool call based on vault mode and workspace.
+ *
+ * Returns an object describing where to route:
+ *   { local: true, vaultPath, sync? }   — local disk (local/synced mode)
+ *   { local: false, workspace }          — server API (hosted mode / cross-workspace)
+ *   { local: false, disabled: true }     — vault not configured (none mode)
  */
 function resolveVault(args) {
   const ws = args.workspace;
-  if (!ws || ws === config.workspace) {
-    return { vaultPath: config.vault, local: true };
+  const isOwnWorkspace = !ws || ws === config.workspace;
+
+  // Cross-workspace: always route through server
+  if (!isOwnWorkspace) {
+    return { local: false, workspace: ws };
+  }
+
+  // Own workspace: route by vault mode
+  switch (config.vaultMode) {
+    case "hosted":
+      return { local: false, workspace: config.workspace };
+    case "synced":
+      return { local: true, vaultPath: config.vault, sync: true };
+    case "local":
+      return { local: true, vaultPath: config.vault, sync: false };
+    case "none":
+      return { local: false, disabled: true };
+    default:
+      // Fallback for existing installs without vaultMode — behave as local
+      return { local: true, vaultPath: config.vault, sync: false };
   }
-  // Cross-workspace — delegate to server
-  return { vaultPath: null, local: false, workspace: ws };
 }
 
 // --- Server setup & dispatch -------------------------------------------------
@@ -317,87 +342,108 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   let result;
 
   switch (name) {
-    // --- Local file I/O tools ---
+    // --- Vault write ---
     case "fathom_vault_write": {
-      const { vaultPath, local } = resolveVault(args);
-      if (!local) {
-        result = { error: "Cross-workspace writes not supported via MCP. Use the server API." };
-      } else {
-        result = handleVaultWrite(args, vaultPath);
+      const v = resolveVault(args);
+      if (v.disabled) {
+        result = { error: "Vault not configured for this workspace. Use hosted or synced mode, or create a local ./vault/ directory." };
+      } else if (v.local) {
+        result = handleVaultWrite(args, v.vaultPath);
         if (result.ok) {
-          // Fire-and-forget: notify server for access tracking
           client.notifyAccess(args.path, args.workspace).catch(() => {});
+          if (v.sync) client.pushFile(config.workspace, args.path, args.content).catch(() => {});
         }
+      } else {
+        result = await client.writeFile(v.workspace, args.path, args.content);
       }
       break;
     }
+
+    // --- Vault append ---
     case "fathom_vault_append": {
-      const { vaultPath, local } = resolveVault(args);
-      if (!local) {
-        result = { error: "Cross-workspace appends not supported via MCP. Use the server API." };
-      } else {
-        result = handleVaultAppend(args, vaultPath);
+      const v = resolveVault(args);
+      if (v.disabled) {
+        result = { error: "Vault not configured for this workspace. Use hosted or synced mode, or create a local ./vault/ directory." };
+      } else if (v.local) {
+        result = handleVaultAppend(args, v.vaultPath);
         if (result.ok) {
           client.notifyAccess(args.path, args.workspace).catch(() => {});
+          if (v.sync) client.appendFile(config.workspace, args.path, args.content).catch(() => {});
         }
+      } else {
+        result = await client.appendFile(v.workspace, args.path, args.content);
       }
       break;
     }
+
+    // --- Vault read ---
     case "fathom_vault_read": {
-      const { vaultPath, local } = resolveVault(args);
-      if (!local) {
-        // Cross-workspace reads go through server
-        result = { error: "Cross-workspace reads: use fathom_vault_search or the server API." };
-      } else {
-        result = handleVaultRead(args, vaultPath);
+      const v = resolveVault(args);
+      if (v.disabled) {
+        result = { error: "Vault not configured for this workspace. Use hosted or synced mode, or create a local ./vault/ directory." };
+      } else if (v.local) {
+        result = handleVaultRead(args, v.vaultPath);
         if (!result.error) {
           client.notifyAccess(args.path, args.workspace).catch(() => {});
         }
+      } else {
+        result = await client.readFile(v.workspace, args.path);
       }
       break;
     }
+
+    // --- Vault image (local-only for now — base64 over HTTP would be wasteful) ---
     case "fathom_vault_image": {
-      const { vaultPath, local } = resolveVault(args);
-      if (!local) {
-        result = { error: "Cross-workspace image reads not supported via MCP." };
+      const v = resolveVault(args);
+      if (!v.local) {
+        result = { error: "Image reads require local or synced vault mode." };
       } else {
-        result = handleVaultImage(args, vaultPath);
+        result = handleVaultImage(args, v.vaultPath);
       }
       break;
     }
+
+    // --- Vault write asset (local-only) ---
     case "fathom_vault_write_asset": {
-      const { vaultPath, local } = resolveVault(args);
-      if (!local) {
-        result = { error: "Cross-workspace asset writes not supported via MCP." };
+      const v = resolveVault(args);
+      if (!v.local) {
+        result = { error: "Asset writes require local or synced vault mode." };
       } else {
-        result = handleVaultWriteAsset(args, vaultPath);
+        result = handleVaultWriteAsset(args, v.vaultPath);
       }
       break;
     }
 
-    // --- Local listing with server fallback ---
+    // --- Vault list ---
     case "fathom_vault_list": {
-      const { vaultPath, local } = resolveVault(args);
-      if (local) {
+      const v = resolveVault(args);
+      if (v.disabled) {
+        result = { error: "Vault not configured for this workspace." };
+      } else if (v.local) {
         // Try server first for activity-enriched data, fall back to local
         result = await client.vaultList(args.workspace);
         if (result.error) {
-          result = handleVaultList(vaultPath);
+          result = handleVaultList(v.vaultPath);
         }
       } else {
-        result = await client.vaultList(args.workspace);
+        // Hosted or cross-workspace: server has the files
+        result = await client.listFiles(v.workspace);
       }
       break;
     }
+
+    // --- Vault folder ---
     case "fathom_vault_folder": {
-      const { vaultPath, local } = resolveVault(args);
-      if (local) {
+      const v = resolveVault(args);
+      if (v.disabled) {
+        result = { error: "Vault not configured for this workspace." };
+      } else if (v.local) {
         result = await client.vaultFolder(args.folder, args.workspace);
         if (result.error) {
-          result = handleVaultFolder(args, vaultPath);
+          result = handleVaultFolder(args, v.vaultPath);
         }
       } else {
-        result = await client.vaultFolder(args.folder, args.workspace);
+        result = await client.vaultFolder(args.folder, v.workspace);
       }
       break;
     }
@@ -416,10 +462,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       result = await client.roomPost(args.room, args.message, config.workspace);
       break;
     case "fathom_room_read":
-      result = await client.roomRead(args.room, args.minutes, args.start);
+      result = await client.roomRead(
+        args.room, args.minutes, args.start,
+        args.mark_read !== false ? config.workspace : undefined,
+        args.mark_read,
+      );
       break;
     case "fathom_room_list":
-      result = await client.roomList();
+      result = await client.roomList(config.workspace);
       break;
     case "fathom_room_describe":
       result = await client.roomDescribe(args.room, args.description);
@@ -447,6 +497,53 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
+/**
+ * Startup sync for synced mode — scan local vault, compare with server,
+ * and push any files the server is missing.
+ */
+async function startupSync() {
+  if (config.vaultMode !== "synced") return;
+  if (!fs.existsSync(config.vault)) return;
+
+  try {
+    // Build local manifest
+    const manifest = [];
+    const walkDir = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+          walkDir(abs);
+        } else if (entry.isFile()) {
+          const stat = fs.statSync(abs);
+          manifest.push({
+            path: path.relative(config.vault, abs),
+            mtime: stat.mtime.toISOString(),
+            size: stat.size,
+          });
+        }
+      }
+    };
+    walkDir(config.vault);
+
+    if (manifest.length === 0) return;
+
+    // Ask server what it needs
+    const diff = await client.syncManifest(config.workspace, manifest);
+    if (diff.error || !diff.needed) return;
+
+    // Push needed files
+    for (const filePath of diff.needed) {
+      const abs = path.resolve(config.vault, filePath);
+      if (fs.existsSync(abs)) {
+        const content = fs.readFileSync(abs, "utf-8");
+        await client.pushFile(config.workspace, filePath, content);
+      }
+    }
+  } catch {
+    // Sync failure is non-fatal — local vault is source of truth
+  }
+}
+
 async function main() {
   // Auto-register workspace with server (fire-and-forget)
   if (config.server && config.workspace) {
@@ -457,6 +554,9 @@ async function main() {
     }).catch(() => {});
   }
 
+  // Startup sync for synced mode (fire-and-forget)
+  startupSync().catch(() => {});
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/server-client.js

@@ -82,14 +82,22 @@ export function createClient(config) {
     });
   }
 
-  async function roomRead(room, minutes, start) {
+  async function roomRead(room, minutes, start, ws, markRead) {
     return request("GET", `/api/room/${encodeURIComponent(room)}`, {
-      params: { minutes, start },
+      params: { minutes, start, workspace: ws, mark_read: markRead },
     });
   }
 
-  async function roomList() {
-    return request("GET", "/api/room/list");
+  async function roomList(ws) {
+    return request("GET", "/api/room/list", {
+      params: { workspace: ws },
+    });
+  }
+
+  async function roomMarkRead(room, ws) {
+    return request("POST", `/api/room/${encodeURIComponent(room)}/read`, {
+      body: { workspace: ws },
+    });
   }
 
   async function roomDescribe(room, description) {
@@ -145,6 +153,43 @@ export function createClient(config) {
     });
   }
 
+  // --- Hosted vault file CRUD (server-stored files) --------------------------
+
+  async function readFile(ws, filePath) {
+    return request("GET", `/api/vault/${encodeURIComponent(ws)}/files/${filePath}`);
+  }
+
+  async function writeFile(ws, filePath, content) {
+    return request("PUT", `/api/vault/${encodeURIComponent(ws)}/files/${filePath}`, {
+      body: { content },
+    });
+  }
+
+  async function appendFile(ws, filePath, content) {
+    return request("POST", `/api/vault/${encodeURIComponent(ws)}/files/${filePath}/append`, {
+      body: { content },
+    });
+  }
+
+  async function deleteFile(ws, filePath) {
+    return request("DELETE", `/api/vault/${encodeURIComponent(ws)}/files/${filePath}`);
+  }
+
+  async function listFiles(ws) {
+    return request("GET", `/api/vault/${encodeURIComponent(ws)}/files`);
+  }
+
+  /** Push a file to server storage (used by synced mode). Same as writeFile. */
+  async function pushFile(ws, filePath, content) {
+    return writeFile(ws, filePath, content);
+  }
+
+  async function syncManifest(ws, manifest) {
+    return request("POST", `/api/vault/${encodeURIComponent(ws)}/sync/manifest`, {
+      body: manifest,
+    });
+  }
+
   // --- Auth ------------------------------------------------------------------
 
   async function getApiKey() {
@@ -169,6 +214,7 @@ export function createClient(config) {
     roomPost,
     roomRead,
     roomList,
+    roomMarkRead,
     roomDescribe,
     sendToWorkspace,
     listWorkspaces,
@@ -176,6 +222,13 @@ export function createClient(config) {
     notifyAccess,
     vaultList,
     vaultFolder,
+    readFile,
+    writeFile,
+    appendFile,
+    deleteFile,
+    listFiles,
+    pushFile,
+    syncManifest,
     getApiKey,
     healthCheck,
   };