fathom-mcp 0.5.8 → 0.5.9

package/package.json

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

package/scripts/fathom-start.sh

@@ -287,6 +287,8 @@ do_start() {
 
     cd "$PROJECT_DIR"
     unset CLAUDECODE 2>/dev/null || true
+    # Ensure common binary locations are on PATH for backgrounded processes
+    export PATH="$HOME/.local/bin:$HOME/.claude/local/bin:$PATH"
     mkdir -p .fathom
 
     local pipe_file="$PROJECT_DIR/.fathom/agent.pipe"

package/src/agents.js

@@ -0,0 +1,394 @@
+/**
+ * Central agent registry — ~/.config/fathom/agents.json
+ *
+ * Single source of truth for all agent definitions. The CLI uses this
+ * for list/start/stop/restart/add/remove/config commands.
+ */
+
+import fs from "fs";
+import path from "path";
+import { execSync, execFileSync, spawn } from "child_process";
+
+const CONFIG_DIR = path.join(process.env.HOME || "/tmp", ".config", "fathom");
+const AGENTS_FILE = path.join(CONFIG_DIR, "agents.json");
+
+const EMPTY_CONFIG = { version: 1, agents: {} };
+
+// ── Config I/O ──────────────────────────────────────────────────────────────
+
+export function loadAgentsConfig() {
+  try {
+    const raw = fs.readFileSync(AGENTS_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.agents || typeof parsed.agents !== "object") {
+      return { ...EMPTY_CONFIG };
+    }
+    return parsed;
+  } catch {
+    return { ...EMPTY_CONFIG };
+  }
+}
+
+export function saveAgentsConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(AGENTS_FILE, JSON.stringify(config, null, 2) + "\n");
+}
+
+// ── CRUD ────────────────────────────────────────────────────────────────────
+
+export function getAgent(name) {
+  const config = loadAgentsConfig();
+  return config.agents[name] || null;
+}
+
+export function listAgents() {
+  const config = loadAgentsConfig();
+  return config.agents;
+}
+
+export function addAgent(name, entry) {
+  const config = loadAgentsConfig();
+  config.agents[name] = entry;
+  saveAgentsConfig(config);
+}
+
+export function removeAgent(name) {
+  const config = loadAgentsConfig();
+  if (!config.agents[name]) return false;
+  delete config.agents[name];
+  saveAgentsConfig(config);
+  return true;
+}
+
+// ── Status ──────────────────────────────────────────────────────────────────
+
+export function isAgentRunning(name, entry) {
+  if (entry.ssh) return "ssh";
+
+  const mode = entry.executionMode || "tmux";
+
+  if (mode === "tmux") {
+    const session = `${name}_fathom-session`;
+    try {
+      execSync(`tmux has-session -t ${JSON.stringify(session)} 2>/dev/null`, {
+        stdio: "pipe",
+      });
+      return "running";
+    } catch {
+      return "stopped";
+    }
+  }
+
+  // headless — check PID file
+  const pidFile = path.join(entry.projectDir, ".fathom", "agent.pid");
+  try {
+    const pid = fs.readFileSync(pidFile, "utf-8").trim();
+    if (pid) {
+      process.kill(parseInt(pid, 10), 0); // signal 0 = existence check
+      return "running";
+    }
+  } catch {
+    // PID file missing or process gone
+  }
+  return "stopped";
+}
+
+// ── Start / Stop ────────────────────────────────────────────────────────────
+
+/**
+ * Default command per agent type + execution mode.
+ */
+export function defaultCommand(agentType, executionMode) {
+  const cmds = {
+    "claude-code": {
+      tmux: "claude --model opus --permission-mode bypassPermissions",
+      headless:
+        "claude -p --permission-mode bypassPermissions --output-format stream-json",
+    },
+    "claude-sdk": {
+      tmux: "claude --model opus --permission-mode bypassPermissions",
+      headless:
+        "claude -p --permission-mode bypassPermissions --output-format stream-json",
+    },
+    codex: { tmux: "codex", headless: "codex" },
+    gemini: { tmux: "gemini", headless: "gemini" },
+    opencode: { tmux: "opencode", headless: "opencode" },
+  };
+  const forType = cmds[agentType] || cmds["claude-code"];
+  return forType[executionMode] || forType.tmux;
+}
+
+export function startAgent(name, entry) {
+  const mode = entry.executionMode || "tmux";
+  const command = entry.command || defaultCommand(entry.agentType || "claude-code", mode);
+  const session = `${name}_fathom-session`;
+
+  // Build env
+  const env = {
+    ...process.env,
+    PATH: `${process.env.HOME}/.local/bin:${process.env.HOME}/.claude/local/bin:${process.env.PATH}`,
+    ...(entry.env || {}),
+  };
+  // Remove CLAUDECODE to avoid nested session detection
+  delete env.CLAUDECODE;
+
+  if (entry.ssh) {
+    return startAgentSSH(name, entry, command, env);
+  }
+
+  if (mode === "headless") {
+    return startAgentHeadless(name, entry, command, env);
+  }
+
+  return startAgentTmux(name, entry, command, session, env);
+}
+
+function startAgentTmux(name, entry, command, session, env) {
+  // Check if already running
+  try {
+    execSync(`tmux has-session -t ${JSON.stringify(session)} 2>/dev/null`, {
+      stdio: "pipe",
+    });
+    // Save pane ID in case it wasn't saved
+    savePaneId(name, session);
+    return { ok: true, message: `Session already running: ${session}`, alreadyRunning: true };
+  } catch {
+    // Not running — continue
+  }
+
+  try {
+    execSync(
+      `tmux new-session -d -s ${JSON.stringify(session)} -c ${JSON.stringify(entry.projectDir)} ${command}`,
+      { stdio: "pipe", env },
+    );
+  } catch (e) {
+    return { ok: false, message: `Failed to start tmux session: ${e.message}` };
+  }
+
+  // Brief wait for session to stabilize, then save pane ID
+  try {
+    execSync("sleep 1", { stdio: "pipe" });
+  } catch {
+    // ignore
+  }
+  savePaneId(name, session);
+
+  return { ok: true, message: `Started: ${session}` };
+}
+
+function savePaneId(name, session) {
+  try {
+    const paneId = execSync(
+      `tmux list-panes -t ${JSON.stringify(session)} -F '#{pane_id}' 2>/dev/null | head -1`,
+      { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] },
+    ).trim();
+    if (paneId) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+      fs.writeFileSync(path.join(CONFIG_DIR, `${name}-pane-id`), paneId + "\n");
+    }
+  } catch {
+    // Non-critical
+  }
+}
+
+function startAgentHeadless(name, entry, command, env) {
+  const fathomDir = path.join(entry.projectDir, ".fathom");
+  const pidFile = path.join(fathomDir, "agent.pid");
+  const keeperPidFile = path.join(fathomDir, "agent-keeper.pid");
+  const pipeFile = path.join(fathomDir, "agent.pipe");
+  const logFile = path.join(fathomDir, "agent.log");
+
+  // Check if already running
+  try {
+    const pid = fs.readFileSync(pidFile, "utf-8").trim();
+    if (pid) {
+      process.kill(parseInt(pid, 10), 0);
+      return { ok: true, message: `Headless agent already running (PID ${pid})`, alreadyRunning: true };
+    }
+  } catch {
+    // Not running
+  }
+
+  fs.mkdirSync(fathomDir, { recursive: true });
+
+  // Clean up stale pipe
+  try {
+    fs.unlinkSync(pipeFile);
+  } catch {
+    // ignore
+  }
+
+  // Create FIFO, start keeper, start agent
+  try {
+    execSync(`mkfifo ${JSON.stringify(pipeFile)}`, { stdio: "pipe" });
+
+    // Keeper: holds the pipe open so agent doesn't get EOF
+    const keeper = spawn("sleep", ["infinity"], {
+      stdio: ["ignore", fs.openSync(pipeFile, "w"), "ignore"],
+      detached: true,
+      env,
+    });
+    keeper.unref();
+    fs.writeFileSync(keeperPidFile, String(keeper.pid) + "\n");
+
+    // Agent: reads from pipe, logs to file
+    const logFd = fs.openSync(logFile, "a");
+    const pipeFd = fs.openSync(pipeFile, "r");
+    const agent = spawn("bash", ["-c", command], {
+      cwd: entry.projectDir,
+      stdio: [pipeFd, logFd, logFd],
+      detached: true,
+      env,
+    });
+    agent.unref();
+    fs.closeSync(pipeFd);
+    fs.closeSync(logFd);
+
+    fs.writeFileSync(pidFile, String(agent.pid) + "\n");
+
+    return { ok: true, message: `Started headless (PID ${agent.pid}). Log: ${logFile}` };
+  } catch (e) {
+    return { ok: false, message: `Failed to start headless agent: ${e.message}` };
+  }
+}
+
+function startAgentSSH(name, entry, command, env) {
+  const { host, user, key } = entry.ssh;
+  const sshArgs = [];
+  if (key) sshArgs.push("-i", key);
+  const target = user ? `${user}@${host}` : host;
+  const remoteCmd = `cd ${JSON.stringify(entry.projectDir)} && ${command}`;
+
+  try {
+    execFileSync("ssh", [...sshArgs, target, remoteCmd], {
+      stdio: "inherit",
+      env,
+    });
+    return { ok: true, message: `SSH agent started on ${target}` };
+  } catch (e) {
+    return { ok: false, message: `SSH start failed: ${e.message}` };
+  }
+}
+
+export function stopAgent(name, entry) {
+  const session = `${name}_fathom-session`;
+  const messages = [];
+  let stopped = false;
+
+  if (entry.ssh) {
+    return { ok: false, message: "Cannot stop SSH agents remotely — connect to the host directly." };
+  }
+
+  // Kill tmux session
+  try {
+    execSync(`tmux has-session -t ${JSON.stringify(session)} 2>/dev/null`, { stdio: "pipe" });
+    execSync(`tmux kill-session -t ${JSON.stringify(session)}`, { stdio: "pipe" });
+    // Remove pane ID file
+    try {
+      fs.unlinkSync(path.join(CONFIG_DIR, `${name}-pane-id`));
+    } catch {
+      // ignore
+    }
+    messages.push(`Killed tmux session: ${session}`);
+    stopped = true;
+  } catch {
+    // No tmux session
+  }
+
+  // Kill headless process
+  const fathomDir = path.join(entry.projectDir, ".fathom");
+  const pidFile = path.join(fathomDir, "agent.pid");
+  const keeperPidFile = path.join(fathomDir, "agent-keeper.pid");
+  const pipeFile = path.join(fathomDir, "agent.pipe");
+
+  try {
+    const pid = fs.readFileSync(pidFile, "utf-8").trim();
+    if (pid) {
+      process.kill(parseInt(pid, 10));
+      messages.push(`Killed headless process: PID ${pid}`);
+      stopped = true;
+    }
+  } catch {
+    // Not running or file missing
+  }
+  try { fs.unlinkSync(pidFile); } catch { /* */ }
+
+  // Keeper cleanup
+  try {
+    const keeperPid = fs.readFileSync(keeperPidFile, "utf-8").trim();
+    if (keeperPid) process.kill(parseInt(keeperPid, 10));
+  } catch {
+    // ignore
+  }
+  try { fs.unlinkSync(keeperPidFile); } catch { /* */ }
+  try { fs.unlinkSync(pipeFile); } catch { /* */ }
+
+  if (!stopped) {
+    return { ok: false, message: `No running session found for: ${name}` };
+  }
+
+  return { ok: true, message: messages.join("\n") };
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Build a default agent entry from a .fathom.json config in a directory.
+ */
+export function buildEntryFromConfig(projectDir, fathomConfig) {
+  const agentType = fathomConfig.agents?.[0] || "claude-code";
+  const isHeadless = agentType === "claude-sdk";
+  const executionMode = isHeadless ? "headless" : "tmux";
+  return {
+    projectDir,
+    agentType,
+    executionMode,
+    command: defaultCommand(agentType, executionMode),
+    server: fathomConfig.server || "http://localhost:4243",
+    apiKey: fathomConfig.apiKey || "",
+    vault: fathomConfig.vault || "vault",
+    vaultMode: fathomConfig.vaultMode || "local",
+    description: fathomConfig.description || "",
+    hooks: fathomConfig.hooks || {},
+    ssh: null,
+    env: {},
+  };
+}
+
+/**
+ * Look up an agent entry by workspace name from the central registry.
+ * Returns null if no match found.
+ */
+export function findAgentByWorkspace(workspace) {
+  const config = loadAgentsConfig();
+  // Direct name match first
+  if (config.agents[workspace]) {
+    return { name: workspace, entry: config.agents[workspace] };
+  }
+  return null;
+}
+
+/**
+ * Look up an agent entry by projectDir from the central registry.
+ * Walks up from startDir matching against registered projectDirs.
+ * Returns { name, entry } or null.
+ */
+export function findAgentByDir(startDir) {
+  const config = loadAgentsConfig();
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (true) {
+    for (const [name, entry] of Object.entries(config.agents)) {
+      if (entry.projectDir === dir) {
+        return { name, entry };
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir || dir === root) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export { AGENTS_FILE, CONFIG_DIR };

package/src/cli.js

@@ -4,10 +4,17 @@
  * fathom-mcp CLI
  *
  * Usage:
- *   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
+ *   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
+ *   npx fathom-mcp list         — List all agents + running status
+ *   npx fathom-mcp start [name] — Start agent by name or legacy cwd-walk
+ *   npx fathom-mcp stop <name>  — Stop an agent
+ *   npx fathom-mcp restart <name> — Restart an agent
+ *   npx fathom-mcp add [name]   — Add agent to registry (reads .fathom.json defaults)
+ *   npx fathom-mcp remove <name>— Remove agent from registry
+ *   npx fathom-mcp config <name>— Print agent config JSON
  */
 
 import fs from "fs";
@@ -18,6 +25,17 @@ import { fileURLToPath } from "url";
 
 import { findConfigFile, resolveConfig, writeConfig } from "./config.js";
 import { createClient } from "./server-client.js";
+import {
+  listAgents,
+  getAgent,
+  addAgent as registryAddAgent,
+  removeAgent as registryRemoveAgent,
+  isAgentRunning,
+  startAgent,
+  stopAgent,
+  defaultCommand,
+  buildEntryFromConfig,
+} from "./agents.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SCRIPTS_DIR = path.join(__dirname, "..", "scripts");
@@ -372,10 +390,7 @@ async function runInit(flags = {}) {
     ? (flagWorkspace || defaultName)
     : await ask(rl, "  Workspace name", defaultName);
 
-  // 2. Description (optional)
-  const description = nonInteractive ? "" : await ask(rl, "  Workspace description (optional)", "");
-
-  // 4. Agent selection — auto-detect and let user choose
+  // 2. Agent selection — auto-detect and let user choose
   const agentKeys = Object.keys(AGENTS);
   const detected = agentKeys.filter((key) => AGENTS[key].detect(cwd));
 
@@ -518,7 +533,6 @@ async function runInit(flags = {}) {
     vault,
     server: serverUrl,
     apiKey,
-    description,
     agents: selectedAgents,
     hooks: {
       "vault-recall": { enabled: enableRecallHook },
@@ -528,21 +542,13 @@ async function runInit(flags = {}) {
   const configPath = writeConfig(cwd, configData);
   console.log(`  ✓ ${path.relative(cwd, configPath)}`);
 
-  // .fathom/scripts/
-  const scriptsDir = path.join(cwd, ".fathom", "scripts");
-  const copiedScripts = copyScripts(scriptsDir);
+  // ~/.config/fathom/scripts/ (central, shared across all workspaces)
+  const centralScriptsDir = path.join(process.env.HOME, ".config", "fathom", "scripts");
+  const copiedScripts = copyScripts(centralScriptsDir);
   if (copiedScripts.length > 0) {
-    console.log(`  ✓ .fathom/scripts/ (${copiedScripts.length} scripts)`);
+    console.log(`  ✓ ~/.config/fathom/scripts/ (${copiedScripts.length} scripts)`);
   }
 
-  // .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);
@@ -554,18 +560,18 @@ async function runInit(flags = {}) {
     }
   }
 
-  // fathom-agents.md — boilerplate agent instructions
+  // fathom-agents.md — boilerplate agent instructions (central)
   const agentMdSrc = path.join(__dirname, "..", "fathom-agents.md");
-  const agentMdDest = path.join(cwd, ".fathom", "fathom-agents.md");
+  const agentMdDest = path.join(process.env.HOME, ".config", "fathom", "fathom-agents.md");
   try {
     let template = fs.readFileSync(agentMdSrc, "utf-8");
     template = template
       .replace(/\{\{WORKSPACE_NAME\}\}/g, workspace)
       .replace(/\{\{VAULT_DIR\}\}/g, vault)
-      .replace(/\{\{DESCRIPTION\}\}/g, description || `${workspace} workspace`);
+      .replace(/\{\{DESCRIPTION\}\}/g, `${workspace} workspace`);
     fs.mkdirSync(path.dirname(agentMdDest), { recursive: true });
     fs.writeFileSync(agentMdDest, template);
-    console.log("  ✓ .fathom/fathom-agents.md");
+    console.log("  ✓ ~/.config/fathom/fathom-agents.md");
   } catch { /* template not found — skip silently */ }
 
   // Per-agent config files
@@ -575,10 +581,10 @@ async function runInit(flags = {}) {
     console.log(`  ✓ ${result}`);
   }
 
-  // Hook scripts (shared across agents)
-  const sessionStartCmd = "bash .fathom/scripts/fathom-sessionstart.sh";
-  const recallCmd = "bash .fathom/scripts/fathom-recall.sh";
-  const precompactCmd = "bash .fathom/scripts/fathom-precompact.sh";
+  // Hook scripts (central location, shared across agents)
+  const sessionStartCmd = "bash ~/.config/fathom/scripts/fathom-sessionstart.sh";
+  const recallCmd = "bash ~/.config/fathom/scripts/fathom-recall.sh";
+  const precompactCmd = "bash ~/.config/fathom/scripts/fathom-precompact.sh";
 
   // Claude Code hooks
   if (hasClaude) {
@@ -607,14 +613,13 @@ async function runInit(flags = {}) {
   }
 
   // .gitignore
-  appendToGitignore(cwd, [".fathom.json", ".fathom/scripts/"]);
+  appendToGitignore(cwd, [".fathom.json"]);
   console.log("  ✓ .gitignore");
 
   // Register with server
   if (serverReachable) {
     const regResult = await regClient.registerWorkspace(workspace, cwd, {
       vault,
-      description,
       agents: selectedAgents,
       type: selectedAgents[0] || "local",
     });
@@ -659,7 +664,7 @@ async function runInit(flags = {}) {
   }
 
   // Auto-integrate agent instructions
-  const agentMdPath = path.join(cwd, ".fathom", "fathom-agents.md");
+  const agentMdPath = agentMdDest;
   let instructionsBlob = "";
   try {
     instructionsBlob = fs.readFileSync(agentMdPath, "utf-8");
@@ -788,25 +793,20 @@ async function runUpdate() {
   }
 
   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");
+  // Copy all scripts to central location
+  const scriptsDir = path.join(process.env.HOME, ".config", "fathom", "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 agents that support hooks
   // Detect by config agents field or directory presence (older configs may lack agents)
   const agents = found.config.agents || [];
-  const sessionStartCmd = "bash .fathom/scripts/fathom-sessionstart.sh";
+  const sessionStartCmd = "bash ~/.config/fathom/scripts/fathom-sessionstart.sh";
   const registeredHooks = [];
 
   // Claude Code / Claude SDK
@@ -836,7 +836,7 @@ async function runUpdate() {
   console.log(`\n  ✓ Fathom hooks updated to v${packageVersion}\n`);
 
   if (copiedScripts.length > 0) {
-    console.log("  Updated scripts:");
+    console.log("  Updated scripts in ~/.config/fathom/scripts/:");
     for (const script of copiedScripts) {
       console.log(`    ${script}`);
     }
@@ -849,39 +849,218 @@ async function runUpdate() {
     }
   }
 
-  console.log(`\n  Version written to .fathom/version`);
-  console.log("  Restart your agent session to pick up changes.\n");
+  console.log("\n  Restart your agent session to pick up changes.\n");
 }
 
 // --- Start command -----------------------------------------------------------
 
 function runStart(argv) {
-  // Find the installed fathom-start.sh script
+  // Check if first non-flag arg matches a registry entry
+  const firstArg = argv.find((a) => !a.startsWith("-"));
+  if (firstArg) {
+    const entry = getAgent(firstArg);
+    if (entry) {
+      const result = startAgent(firstArg, entry);
+      console.log(`  ${result.message}`);
+      process.exit(result.ok ? 0 : 1);
+      return;
+    }
+  }
+
+  // Legacy fallback: delegate to fathom-start.sh
   const found = findConfigFile(process.cwd());
   const projectDir = found?.dir || process.cwd();
 
-  // Check .fathom/scripts/ first (installed by init/update), then package scripts/
-  const localScript = path.join(projectDir, ".fathom", "scripts", "fathom-start.sh");
+  const centralScript = path.join(process.env.HOME, ".config", "fathom", "scripts", "fathom-start.sh");
   const packageScript = path.join(SCRIPTS_DIR, "fathom-start.sh");
-  const script = fs.existsSync(localScript) ? localScript : packageScript;
+  const script = fs.existsSync(centralScript) ? centralScript : packageScript;
 
   if (!fs.existsSync(script)) {
     console.error("  Error: fathom-start.sh not found. Run `npx fathom-mcp update` first.");
     process.exit(1);
   }
 
-  // Pass remaining args through to the shell script
   try {
     execFileSync("bash", [script, ...argv], {
       cwd: projectDir,
       stdio: "inherit",
     });
   } catch (e) {
-    // Script already printed its own errors; just propagate exit code
     process.exit(e.status || 1);
   }
 }
 
+// --- List command -------------------------------------------------------------
+
+function runList() {
+  const agents = listAgents();
+  const names = Object.keys(agents);
+
+  if (names.length === 0) {
+    console.log("\n  No agents registered. Run `fathom-mcp add` to register one.\n");
+    return;
+  }
+
+  // Header
+  const cols = { name: 16, type: 13, mode: 11, status: 10 };
+  console.log(
+    "\n  " +
+      "NAME".padEnd(cols.name) +
+      "TYPE".padEnd(cols.type) +
+      "MODE".padEnd(cols.mode) +
+      "STATUS".padEnd(cols.status) +
+      "DIR",
+  );
+
+  for (const name of names) {
+    const entry = agents[name];
+    const type = entry.agentType || "claude-code";
+    const mode = entry.executionMode || "tmux";
+    const status = entry.ssh ? "[ssh]" : isAgentRunning(name, entry);
+    const dir = entry.projectDir.replace(process.env.HOME, "~");
+
+    console.log(
+      "  " +
+        name.padEnd(cols.name) +
+        type.padEnd(cols.type) +
+        mode.padEnd(cols.mode) +
+        status.padEnd(cols.status) +
+        dir,
+    );
+  }
+  console.log();
+}
+
+// --- Stop command ------------------------------------------------------------
+
+function runStop(name) {
+  if (!name) {
+    console.error("  Usage: fathom-mcp stop <name>");
+    process.exit(1);
+  }
+  const entry = getAgent(name);
+  if (!entry) {
+    console.error(`  Error: No agent "${name}" in registry. Run \`fathom-mcp list\` to see agents.`);
+    process.exit(1);
+  }
+  const result = stopAgent(name, entry);
+  console.log(`  ${result.message}`);
+  process.exit(result.ok ? 0 : 1);
+}
+
+// --- Restart command ---------------------------------------------------------
+
+function runRestart(name) {
+  if (!name) {
+    console.error("  Usage: fathom-mcp restart <name>");
+    process.exit(1);
+  }
+  const entry = getAgent(name);
+  if (!entry) {
+    console.error(`  Error: No agent "${name}" in registry. Run \`fathom-mcp list\` to see agents.`);
+    process.exit(1);
+  }
+
+  const stopResult = stopAgent(name, entry);
+  if (stopResult.ok) {
+    console.log(`  ${stopResult.message}`);
+  }
+
+  // Brief pause between stop and start
+  try { execFileSync("sleep", ["1"], { stdio: "pipe" }); } catch { /* */ }
+
+  const startResult = startAgent(name, entry);
+  console.log(`  ${startResult.message}`);
+  process.exit(startResult.ok ? 0 : 1);
+}
+
+// --- Add command -------------------------------------------------------------
+
+async function runAdd(argv) {
+  const flags = parseFlags(argv);
+  const nameArg = argv.find((a) => !a.startsWith("-"));
+  const cwd = process.cwd();
+
+  // Try to read .fathom.json from cwd for defaults
+  const found = findConfigFile(cwd);
+  const fathomConfig = found?.config || {};
+  const projectDir = found?.dir || cwd;
+
+  const defaults = buildEntryFromConfig(projectDir, fathomConfig);
+  const defaultName = fathomConfig.workspace || path.basename(projectDir);
+
+  if (flags.nonInteractive) {
+    const name = nameArg || defaultName;
+    registryAddAgent(name, defaults);
+    console.log(`  ✓ Added agent "${name}" to registry.`);
+    return;
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  const name = await ask(rl, "  Agent name", nameArg || defaultName);
+  const agentProjectDir = await ask(rl, "  Project directory", defaults.projectDir);
+  const agentType = await ask(rl, "  Agent type (claude-code|claude-sdk|codex|gemini|opencode)", defaults.agentType);
+  const executionMode = await ask(rl, "  Execution mode (tmux|headless)", defaults.executionMode);
+  const command = await ask(rl, "  Command", defaultCommand(agentType, executionMode));
+  const server = await ask(rl, "  Server URL", defaults.server);
+  const apiKey = await ask(rl, "  API key", defaults.apiKey);
+  const vault = await ask(rl, "  Vault subdirectory", defaults.vault || "vault");
+  const vaultMode = await ask(rl, "  Vault mode (hosted|synced|local|none)", defaults.vaultMode);
+  const description = await ask(rl, "  Description", defaults.description);
+
+  rl.close();
+
+  const entry = {
+    projectDir: path.resolve(agentProjectDir),
+    agentType,
+    executionMode,
+    command,
+    server,
+    apiKey,
+    vault,
+    vaultMode,
+    description,
+    hooks: defaults.hooks || {},
+    ssh: null,
+    env: {},
+  };
+
+  registryAddAgent(name, entry);
+  console.log(`\n  ✓ Added agent "${name}" to registry.`);
+}
+
+// --- Remove command ----------------------------------------------------------
+
+function runRemove(name) {
+  if (!name) {
+    console.error("  Usage: fathom-mcp remove <name>");
+    process.exit(1);
+  }
+  const removed = registryRemoveAgent(name);
+  if (removed) {
+    console.log(`  ✓ Removed agent "${name}" from registry.`);
+  } else {
+    console.error(`  Error: No agent "${name}" in registry.`);
+    process.exit(1);
+  }
+}
+
+// --- Config command ----------------------------------------------------------
+
+function runConfigCmd(name) {
+  if (!name) {
+    console.error("  Usage: fathom-mcp config <name>");
+    process.exit(1);
+  }
+  const entry = getAgent(name);
+  if (!entry) {
+    console.error(`  Error: No agent "${name}" in registry.`);
+    process.exit(1);
+  }
+  console.log(JSON.stringify({ [name]: entry }, null, 2));
+}
+
 // --- Main --------------------------------------------------------------------
 
 // Guard: only run CLI when this module is the entry point (not when imported by tests)
@@ -892,41 +1071,50 @@ const isMain = process.argv[1] && (
 if (isMain) {
   const command = process.argv[2];
 
+  const asyncHandler = (fn) => fn().catch((e) => {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  });
+
   if (command === "init") {
-    const flags = parseFlags(process.argv.slice(3));
-    runInit(flags).catch((e) => {
-      console.error(`Error: ${e.message}`);
-      process.exit(1);
-    });
+    asyncHandler(() => runInit(parseFlags(process.argv.slice(3))));
   } else if (command === "status") {
-    runStatus().catch((e) => {
-      console.error(`Error: ${e.message}`);
-      process.exit(1);
-    });
+    asyncHandler(runStatus);
   } else if (command === "update") {
-    runUpdate().catch((e) => {
-      console.error(`Error: ${e.message}`);
-      process.exit(1);
-    });
+    asyncHandler(runUpdate);
   } else if (command === "start") {
     runStart(process.argv.slice(3));
+  } else if (command === "list" || command === "ls") {
+    runList();
+  } else if (command === "stop") {
+    runStop(process.argv[3]);
+  } else if (command === "restart") {
+    runRestart(process.argv[3]);
+  } else if (command === "add") {
+    asyncHandler(() => runAdd(process.argv.slice(3)));
+  } else if (command === "remove" || command === "rm") {
+    runRemove(process.argv[3]);
+  } else if (command === "config") {
+    runConfigCmd(process.argv[3]);
   } 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|update|start|serve]
+    console.error(`Usage: fathom-mcp [command]
 
-  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                                         Start MCP server (stdio)
+  fathom-mcp serve                                   Same as above
+  fathom-mcp init [-y --api-key KEY]                 Interactive/non-interactive setup
   fathom-mcp status                                  Check connection status
   fathom-mcp update                                  Update hooks + version
-  fathom-mcp start                                   Start agent in tmux session
-  fathom-mcp start --detach                          Start without attaching
-  fathom-mcp start --kill                            Kill agent session
-  fathom-mcp                                         Start MCP server`);
+
+  fathom-mcp list                                    List all agents + status
+  fathom-mcp start [name]                            Start agent (by name or legacy cwd)
+  fathom-mcp stop <name>                             Stop agent
+  fathom-mcp restart <name>                          Stop + start agent
+  fathom-mcp add [name]                              Add agent to registry
+  fathom-mcp remove <name>                           Remove from registry
+  fathom-mcp config <name>                           Print agent config JSON`);
     process.exit(1);
   }
 }

package/src/config.js

@@ -4,11 +4,13 @@
  * Precedence (highest wins):
  *   1. Environment variables (FATHOM_SERVER_URL, FATHOM_API_KEY, FATHOM_WORKSPACE, FATHOM_VAULT_DIR)
  *   2. .fathom.json (walked up from cwd to filesystem root)
- *   3. Built-in defaults
+ *   3. Central registry (~/.config/fathom/agents.json, matched by projectDir)
+ *   4. Built-in defaults
  */
 
 import fs from "fs";
 import path from "path";
+import { findAgentByDir } from "./agents.js";
 
 const CONFIG_FILENAME = ".fathom.json";
 
@@ -55,31 +57,54 @@ export function findConfigFile(startDir = process.cwd()) {
 }
 
 /**
- * Resolve final config by merging: defaults → .fathom.json → env vars.
+ * Apply fields from a source config object onto a result object.
+ */
+function applyConfig(result, config) {
+  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.agents && Array.isArray(config.agents)) {
+    result.agents = config.agents;
+  }
+  if (config.hooks) {
+    result.hooks = { ...result.hooks, ...config.hooks };
+  }
+}
+
+/**
+ * Resolve final config by merging: defaults → registry → .fathom.json → env vars.
  */
 export function resolveConfig(startDir = process.cwd()) {
   const result = { ...DEFAULTS, hooks: { ...DEFAULTS.hooks } };
   let projectDir = startDir;
 
-  // Layer 2: .fathom.json
+  // Layer 3: Central registry (matched by projectDir walk-up)
+  let registryMatch = null;
+  try {
+    registryMatch = findAgentByDir(startDir);
+  } catch {
+    // Registry not available — skip
+  }
+  if (registryMatch) {
+    const { name, entry } = registryMatch;
+    projectDir = entry.projectDir;
+    result.workspace = name;
+    applyConfig(result, entry);
+    if (entry.agentType) {
+      result.agents = [entry.agentType];
+    }
+    result._registryName = name;
+  }
+
+  // Layer 2: .fathom.json (overrides registry)
   const found = findConfigFile(startDir);
   if (found) {
     projectDir = found.dir;
-    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;
-    if (config.agents && Array.isArray(config.agents)) {
-      result.agents = config.agents;
-    }
-    if (config.hooks) {
-      result.hooks = { ...result.hooks, ...config.hooks };
-    }
+    applyConfig(result, found.config);
   }
 
   // Layer 1: Environment variables (highest priority)
@@ -124,7 +149,6 @@ export function writeConfig(dir, config) {
     vault: config.vault || "vault",
     server: config.server || DEFAULTS.server,
     apiKey: config.apiKey || "",
-    description: config.description || "",
     agents: config.agents || [],
     hooks: config.hooks || DEFAULTS.hooks,
   };

package/src/index.js

@@ -947,7 +947,6 @@ async function main() {
   if (config.server && config.workspace) {
     client.registerWorkspace(config.workspace, config._projectDir, {
       vault: config._rawVault,
-      description: config.description,
       agents: config.agents,
       type: config.vaultMode,
     }).catch(() => {});