fathom-mcp 0.5.5 → 0.5.7

package/package.json

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

package/scripts/fathom-start.sh

@@ -1,46 +1,53 @@
 #!/usr/bin/env bash
 #
-# fathom-start.sh — Launch an agent in a correctly-named tmux session.
+# fathom-start.sh — Launch an agent session.
 #
-# Reads .fathom.json for workspace name and agent, creates
-# {workspace}_fathom-session, saves pane ID for WebSocket push injection.
+# Reads .fathom.json for workspace name and agent. For interactive agents
+# (claude-code, codex, gemini, opencode), wraps in a tmux session. For
+# headless agents (claude-sdk), spawns a direct process with PID tracking.
 #
-# Usage:
-#   fathom-start.sh              Start agent, save pane ID, attach
-#   fathom-start.sh --detach     Start agent, save pane ID, don't attach
-#   fathom-start.sh --agent X    Override agent (claude-code|codex|gemini|opencode)
+# Claude agents require an explicit mode flag:
+#   fathom-start.sh --claude-code-w-tmux   Interactive Claude Code in tmux
+#   fathom-start.sh --claude-sdk           Headless Claude SDK, no tmux
+#
+# Other usage:
+#   fathom-start.sh              Start agent (non-claude agents auto-detect)
+#   fathom-start.sh --detach     Start agent, don't attach to tmux
+#   fathom-start.sh --agent X    Override agent
 #   fathom-start.sh --kill       Kill existing session
 #   fathom-start.sh --status     Show session status
 
 set -euo pipefail
 
-if ! command -v tmux &>/dev/null; then
-  echo "Error: tmux is not installed. Install it first:" >&2
-  echo "  apt install tmux  |  brew install tmux  |  dnf install tmux" >&2
-  exit 1
-fi
-
 # ── Defaults ──────────────────────────────────────────────────────────────────
 
 ATTACH=true
 AGENT_OVERRIDE=""
 ACTION="start"
+MODE_FLAG=""
+USE_TMUX=true
 
 # ── Parse flags ───────────────────────────────────────────────────────────────
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    --claude-code-w-tmux) MODE_FLAG="claude-code-w-tmux"; shift ;;
+    --claude-sdk)         MODE_FLAG="claude-sdk"; shift ;;
     --detach)   ATTACH=false; shift ;;
     --attach)   ATTACH=true; shift ;;
     --agent)    AGENT_OVERRIDE="$2"; shift 2 ;;
     --kill)     ACTION="kill"; shift ;;
     --status)   ACTION="status"; shift ;;
     -h|--help)
-      echo "Usage: fathom-start.sh [--attach] [--detach] [--agent NAME] [--kill] [--status]"
+      echo "Usage: fathom-start.sh [FLAGS]"
       echo ""
-      echo "  (default)    Start agent in tmux, save pane ID, attach"
-      echo "  --detach     Start but don't attach"
-      echo "  --agent X    Override agent: claude-code, codex, gemini, opencode"
+      echo "Mode flags (required for Claude agents):"
+      echo "  --claude-code-w-tmux   Interactive Claude Code in tmux"
+      echo "  --claude-sdk           Headless Claude SDK, no tmux"
+      echo ""
+      echo "Other flags:"
+      echo "  --detach     Start but don't attach to tmux"
+      echo "  --agent X    Override agent: claude-code, claude-sdk, codex, gemini, opencode"
       echo "  --kill       Kill existing session"
       echo "  --status     Show if session is running"
       exit 0
@@ -104,10 +111,12 @@ fi
 SESSION="${WORKSPACE}_fathom-session"
 PANE_DIR="$HOME/.config/fathom"
 PANE_FILE="$PANE_DIR/${WORKSPACE}-pane-id"
+PID_FILE="$PROJECT_DIR/.fathom/agent.pid"
+LOG_FILE="$PROJECT_DIR/.fathom/agent.log"
 
-# ── Resolve agent command ─────────────────────────────────────────────────────
+# ── Resolve agent type ────────────────────────────────────────────────────────
 
-resolve_agent_cmd() {
+resolve_agent() {
   local agent="${AGENT_OVERRIDE:-}"
   if [[ -z "$agent" ]]; then
     agent=$(read_json_array_first "$CONFIG_FILE" "agents")
@@ -115,10 +124,53 @@ resolve_agent_cmd() {
   if [[ -z "$agent" ]]; then
     agent="claude-code"
   fi
+  echo "$agent"
+}
+
+AGENT=$(resolve_agent)
+
+# ── Determine execution mode (tmux vs headless) ──────────────────────────────
+# Must happen in the main shell, not inside $(...) subshell.
+
+case "$AGENT" in
+  claude-code)
+    if [[ "$MODE_FLAG" == "claude-sdk" ]]; then
+      USE_TMUX=false
+    elif [[ -z "$MODE_FLAG" ]]; then
+      echo "Error: Claude Code requires an explicit mode flag:" >&2
+      echo "  fathom-start.sh --claude-code-w-tmux    Interactive Claude in tmux" >&2
+      echo "  fathom-start.sh --claude-sdk             Headless Claude SDK" >&2
+      echo "" >&2
+      echo "For local agents managed by fathom-server, use the dashboard restart button instead." >&2
+      exit 1
+    fi
+    ;;
+  claude-sdk)
+    if [[ "$MODE_FLAG" == "claude-code-w-tmux" ]]; then
+      USE_TMUX=true
+    else
+      USE_TMUX=false
+    fi
+    ;;
+esac
 
-  case "$agent" in
+# ── Resolve agent command ─────────────────────────────────────────────────────
+
+resolve_agent_cmd() {
+  case "$AGENT" in
     claude-code)
-      echo "claude --model opus --permission-mode bypassPermissions"
+      if [[ "$USE_TMUX" == false ]]; then
+        echo "claude -p --permission-mode bypassPermissions --no-user-prompt --output-format stream-json"
+      else
+        echo "claude --model opus --permission-mode bypassPermissions"
+      fi
+      ;;
+    claude-sdk)
+      if [[ "$USE_TMUX" == true ]]; then
+        echo "claude --model opus --permission-mode bypassPermissions"
+      else
+        echo "claude -p --permission-mode bypassPermissions --no-user-prompt --output-format stream-json"
+      fi
       ;;
     codex)
       echo "codex"
@@ -130,7 +182,7 @@ resolve_agent_cmd() {
       echo "opencode"
       ;;
     *)
-      echo "Warning: Unknown agent '$agent', falling back to claude" >&2
+      echo "Warning: Unknown agent '$AGENT', falling back to claude" >&2
       echo "claude"
       ;;
   esac
@@ -148,38 +200,127 @@ save_pane_id() {
   fi
 }
 
-# ── Session check ─────────────────────────────────────────────────────────────
+# ── Session/process check ────────────────────────────────────────────────────
 
 session_exists() {
   tmux has-session -t "$SESSION" 2>/dev/null
 }
 
+headless_is_running() {
+  if [[ -f "$PID_FILE" ]]; then
+    local pid
+    pid=$(cat "$PID_FILE" 2>/dev/null)
+    if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+      return 0
+    fi
+  fi
+  return 1
+}
+
 # ── Actions ───────────────────────────────────────────────────────────────────
 
 do_status() {
   echo "Workspace: $WORKSPACE"
   echo "Session:   $SESSION"
   if session_exists; then
-    echo "Status:    running"
+    echo "Status:    running (tmux)"
     if [[ -f "$PANE_FILE" ]]; then
       echo "Pane ID:   $(cat "$PANE_FILE")"
     fi
+  elif headless_is_running; then
+    echo "Status:    running (headless)"
+    echo "PID:       $(cat "$PID_FILE")"
+    echo "Log:       $LOG_FILE"
+    if [[ -p "$PROJECT_DIR/.fathom/agent.pipe" ]]; then
+      echo "Pipe:      $PROJECT_DIR/.fathom/agent.pipe"
+    fi
   else
     echo "Status:    not running"
   fi
 }
 
 do_kill() {
+  local killed=false
   if session_exists; then
     tmux kill-session -t "$SESSION"
     rm -f "$PANE_FILE"
-    echo "Killed session: $SESSION"
-  else
-    echo "Session not running: $SESSION"
+    echo "Killed tmux session: $SESSION"
+    killed=true
+  fi
+  if headless_is_running; then
+    local pid
+    pid=$(cat "$PID_FILE")
+    kill "$pid" 2>/dev/null || true
+    rm -f "$PID_FILE"
+    echo "Killed headless process: PID $pid"
+    killed=true
+  fi
+  # Clean up keeper process and FIFO
+  local keeper_pid_file="$PROJECT_DIR/.fathom/agent-keeper.pid"
+  if [[ -f "$keeper_pid_file" ]]; then
+    local keeper_pid
+    keeper_pid=$(cat "$keeper_pid_file")
+    kill "$keeper_pid" 2>/dev/null || true
+    rm -f "$keeper_pid_file"
+  fi
+  rm -f "$PROJECT_DIR/.fathom/agent.pipe"
+  if [[ "$killed" == false ]]; then
+    echo "No running session found for: $WORKSPACE"
   fi
 }
 
 do_start() {
+  local agent_cmd
+  agent_cmd=$(resolve_agent_cmd)
+
+  if [[ "$USE_TMUX" == false ]]; then
+    # ── Headless mode — FIFO-based stdin ──
+    if headless_is_running; then
+      echo "Headless agent already running (PID $(cat "$PID_FILE"))"
+      echo "Log: $LOG_FILE"
+      return 0
+    fi
+
+    echo "Starting headless: $agent_cmd"
+    echo "Dir: $PROJECT_DIR"
+    echo "Logs: $LOG_FILE"
+
+    cd "$PROJECT_DIR"
+    unset CLAUDECODE 2>/dev/null || true
+    mkdir -p .fathom
+
+    local pipe_file="$PROJECT_DIR/.fathom/agent.pipe"
+
+    # Clean up stale pipe
+    rm -f "$pipe_file"
+    mkfifo "$pipe_file"
+
+    # Keep a writer FD open so the pipe never sends EOF to the reader.
+    # Without this, the agent reads EOF and exits when no writer is connected.
+    sleep infinity > "$pipe_file" &
+    local keeper_pid=$!
+
+    # Start agent reading from the FIFO, logging stdout/stderr
+    $agent_cmd < "$pipe_file" >> "$LOG_FILE" 2>&1 &
+    local pid=$!
+
+    echo "$pid" > "$PID_FILE"
+    echo "$keeper_pid" > "$PROJECT_DIR/.fathom/agent-keeper.pid"
+
+    echo "PID: $pid"
+    echo "Pipe: $pipe_file"
+    echo "Started. View logs: tail -f $LOG_FILE"
+    echo "Inject: echo 'your message' > $pipe_file"
+    return 0
+  fi
+
+  # ── Interactive mode — tmux session ──
+  if ! command -v tmux &>/dev/null; then
+    echo "Error: tmux is not installed. Install it first:" >&2
+    echo "  apt install tmux  |  brew install tmux  |  dnf install tmux" >&2
+    exit 1
+  fi
+
   if session_exists; then
     echo "Session already running: $SESSION"
     save_pane_id
@@ -189,9 +330,6 @@ do_start() {
     return 0
   fi
 
-  local agent_cmd
-  agent_cmd=$(resolve_agent_cmd)
-
   echo "Starting: $SESSION"
   echo "Agent:    $agent_cmd"
   echo "Dir:      $PROJECT_DIR"

package/src/cli.js

@@ -130,6 +130,7 @@ function copyScripts(targetDir) {
 
 const HEADLESS_CMDS = {
   "claude-code": (prompt) => ["claude", "-p", "--dangerously-skip-permissions", prompt],
+  "claude-sdk":  (prompt) => ["claude", "-p", "--dangerously-skip-permissions", prompt],
   "codex":       (prompt) => ["codex", "exec", prompt],
   "gemini":      (prompt) => ["gemini", prompt],
   "opencode":    (prompt) => ["opencode", "run", prompt],
@@ -306,6 +307,13 @@ const AGENTS = {
     hasHooks: false,
     nextSteps: "Run `opencode` in this directory — fathom tools load automatically.",
   },
+  "claude-sdk": {
+    name: "Claude SDK (headless)",
+    detect: (cwd) => fs.existsSync(path.join(cwd, ".claude")),
+    configWriter: writeMcpJson,
+    hasHooks: true,
+    nextSteps: "Headless Claude Code — no TUI, structured I/O. Start with: npx fathom-mcp start",
+  },
 };
 
 // Exported for testing
@@ -381,7 +389,7 @@ async function runInit(flags = {}) {
       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 markers = { "claude-code": ".claude/", "codex": ".codex/", "gemini": ".gemini/", "opencode": "opencode.json", "claude-sdk": ".claude/" };
       const hint = isDetected ? ` (${markers[key] || key} found)` : "";
       console.log(`    ${mark} ${agent.name}${hint}`);
     }
@@ -480,8 +488,8 @@ async function runInit(flags = {}) {
     ? (nonInteractive ? "vault" : await ask(rl, "  Vault subdirectory", "vault"))
     : "vault";
 
-  // 9. Hooks — ask if any hook-supporting agent is selected (Claude Code, Gemini CLI)
-  const hasClaude = selectedAgents.includes("claude-code");
+  // 9. Hooks — ask if any hook-supporting agent is selected (Claude Code, Claude SDK, Gemini CLI)
+  const hasClaude = selectedAgents.includes("claude-code") || selectedAgents.includes("claude-sdk");
   const hasGemini = selectedAgents.includes("gemini");
   const hasHookAgent = hasClaude || hasGemini;
   let enableRecallHook = false;
@@ -712,7 +720,7 @@ async function runInit(flags = {}) {
 }
 
 function printInstructionsFallback(agentMdPath, selectedAgents) {
-  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code");
+  const hasNonClaude = selectedAgents.some((k) => k !== "claude-code" && k !== "claude-sdk");
   const docTarget = hasNonClaude
     ? "your CLAUDE.md, AGENTS.md, or equivalent"
     : "your CLAUDE.md";
@@ -801,8 +809,8 @@ async function runUpdate() {
   const sessionStartCmd = "bash .fathom/scripts/fathom-sessionstart.sh";
   const registeredHooks = [];
 
-  // Claude Code
-  const hasClaude = agents.includes("claude-code")
+  // Claude Code / Claude SDK
+  const hasClaude = agents.includes("claude-code") || agents.includes("claude-sdk")
     || fs.existsSync(path.join(projectDir, ".claude"));
   if (hasClaude) {
     const settingsPath = path.join(projectDir, ".claude", "settings.local.json");

package/src/ws-connection.js

@@ -89,7 +89,7 @@ export function createWSConnection(config) {
 
         case "inject":
         case "ping_fire":
-          injectToTmux(msg.text || "");
+          injectMessage(msg.text || "");
           break;
 
         case "image":
@@ -148,7 +148,42 @@ export function createWSConnection(config) {
     reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_MS);
   }
 
-  // ── tmux injection ──────────────────────────────────────────────────────────
+  // ── Message injection ───────────────────────────────────────────────────────
+
+  function injectMessage(text) {
+    if (!text) return;
+
+    if (agent === "claude-sdk") {
+      // Headless SDK agents use a FIFO pipe for stdin injection.
+      // Server-managed (local): server handles via persistent_session._inject_headless()
+      // Standalone (remote): write to .fathom/agent.pipe FIFO
+      injectToFifo(text);
+    } else {
+      injectToTmux(text);
+    }
+  }
+
+  function injectToFifo(text) {
+    if (!text) return;
+
+    const projectDir = config._projectDir || process.cwd();
+    const pipePath = path.join(projectDir, ".fathom", "agent.pipe");
+
+    try {
+      const stat = fs.statSync(pipePath);
+      if (stat.isFIFO()) {
+        // Write to FIFO — opens, writes, closes in one shot.
+        // The newline terminates the message for claude -p.
+        fs.appendFileSync(pipePath, text + "\n");
+        return;
+      }
+    } catch {
+      // FIFO not found — fall back to tmux
+    }
+
+    // Fallback: try tmux injection (e.g., started with --claude-code-w-tmux override)
+    injectToTmux(text);
+  }
 
   function injectToTmux(text) {
     if (!text) return;