@botbuddy/cli 1.0.0

package/bin/botbuddy.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../src/commands.mjs";
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@botbuddy/cli",
+  "version": "1.0.0",
+  "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
+  "type": "module",
+  "bin": {
+    "botbuddy": "./bin/botbuddy.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": ["mcp", "agents", "swarm", "cli", "coordination"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,61 @@
+import { getConfig, SERVER_URL } from "./config.mjs";
+import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
+
+function authHeader() {
+  const cfg = getConfig();
+  if (cfg.access_token) {
+    if (cfg.token_expires_at && Date.now() >= cfg.token_expires_at) {
+      die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
+    }
+    if (cfg.token_expires_at && cfg.token_expires_at - Date.now() < 5 * 60 * 1000) {
+      console.error(`${yellow("⚠")} Token expires in <5 minutes. Run ${cyan("botbuddy login")} soon.`);
+    }
+    return { Authorization: `Bearer ${cfg.access_token}` };
+  }
+  if (cfg.api_key) return { "x-agent-api-key": cfg.api_key };
+  die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
+}
+
+export async function callTool(toolName, args = {}) {
+  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const body = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name: toolName, arguments: args },
+  };
+
+  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const data = await res.json();
+
+  if (data.error?.message) die(`Server error: ${data.error.message}`);
+
+  const text = data.result?.content?.map((c) => c.text).join("\n");
+  if (text) {
+    console.log(prettyJson(text));
+  } else {
+    console.log(JSON.stringify(data, null, 2));
+  }
+  return data;
+}
+
+export async function listResources() {
+  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const body = { jsonrpc: "2.0", id: 1, method: "resources/list", params: {} };
+  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const data = await res.json();
+  console.log(JSON.stringify(data.result?.resources ?? data.result ?? data, null, 2));
+}
+
+export async function readResource(uri) {
+  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const body = { jsonrpc: "2.0", id: 1, method: "resources/read", params: { uri } };
+  const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
+  const data = await res.json();
+  const text = data.result?.contents?.[0]?.text;
+  if (text) {
+    console.log(prettyJson(text));
+  } else {
+    console.log(JSON.stringify(data.result ?? data, null, 2));
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,72 @@
+import { createHash, randomBytes } from "crypto";
+import { SERVER_URL, saveConfig, getConfig } from "./config.mjs";
+import { green, dim, die } from "./utils.mjs";
+
+export async function doLogin() {
+  console.log("\x1b[1mBotBuddy OAuth Login\x1b[0m\n");
+
+  // Step 1: Dynamic client registration
+  console.log(dim("→ Registering client..."));
+  const regRes = await fetch(`${SERVER_URL}/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "botbuddy-cli-node",
+      redirect_uris: ["http://localhost:19836/callback"],
+      grant_types: ["authorization_code"],
+      token_endpoint_auth_method: "none",
+    }),
+  });
+  const regData = await regRes.json();
+  const clientId = regData.client_id;
+  if (!clientId) die(`Client registration failed: ${JSON.stringify(regData)}`);
+  console.log(`  ${green("✓")} Client registered: ${dim(clientId)}`);
+
+  // Step 2: Generate PKCE
+  const codeVerifier = randomBytes(32).toString("base64url").slice(0, 43);
+  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+
+  // Step 3: Authorization
+  const state = randomBytes(16).toString("hex");
+  const authUrl = `${SERVER_URL}/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent("http://localhost:19836/callback")}&response_type=code&scope=read+write+lock&state=${state}&code_challenge=${codeChallenge}&code_challenge_method=S256`;
+
+  console.log(dim("→ Requesting authorization..."));
+  const authRes = await fetch(authUrl, { redirect: "manual" });
+  const location = authRes.headers.get("location");
+  if (!location) die("Authorization failed — no redirect received");
+
+  const codeMatch = location.match(/code=([^&]+)/);
+  if (!codeMatch) die("No authorization code in redirect");
+  const authCode = codeMatch[1];
+  console.log(`  ${green("✓")} Authorization code received`);
+
+  // Step 4: Exchange code for token
+  console.log(dim("→ Exchanging code for token..."));
+  const tokenRes = await fetch(`${SERVER_URL}/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: authCode,
+      client_id: clientId,
+      code_verifier: codeVerifier,
+      redirect_uri: "http://localhost:19836/callback",
+    }),
+  });
+  const tokenData = await tokenRes.json();
+  if (!tokenData.access_token) die(`Token exchange failed: ${JSON.stringify(tokenData)}`);
+  console.log(`  ${green("✓")} Access token received`);
+
+  const expiresAt = tokenData.expires_in
+    ? Date.now() + tokenData.expires_in * 1000
+    : Date.now() + 24 * 60 * 60 * 1000; // default 24h if server omits expires_in
+
+  saveConfig({
+    ...getConfig(),
+    access_token: tokenData.access_token,
+    client_id: clientId,
+    token_expires_at: expiresAt,
+  });
+
+  console.log(`\n${green("✓")} Logged in successfully! Token saved to ${dim("~/.botbuddy/config.json")}`);
+}

package/src/codex-bridge.mjs

@@ -0,0 +1,463 @@
+/**
+ * BotBuddy Codex Bridge
+ *
+ * Runs locally alongside `codex app-server --listen ws://127.0.0.1:<port>`.
+ * Connects the local Codex app-server to BotBuddy for remote orchestration.
+ *
+ * Security:
+ *   - Bridge ↔ BotBuddy: HTTPS + HMAC session signing (prevents session hijacking)
+ *   - Bridge ↔ Codex app-server: localhost-only WS with nonce handshake
+ *
+ * Usage:
+ *   botbuddy codex bridge [--port 4500] [--repo /path/to/repo] [--model gpt-5.4]
+ */
+
+import { createHash, randomBytes } from "crypto";
+import { getConfig, SERVER_URL } from "./config.mjs";
+import { green, red, cyan, dim, bold, yellow, die } from "./utils.mjs";
+
+const RELAY_URL = SERVER_URL.replace("/mcp-server", "/codex-relay");
+const POLL_INTERVAL_MS = 2000;
+const PING_INTERVAL_MS = 15000;
+
+// ─── HMAC signing ───────────────────────────────────────────────
+let sessionSecret = null;
+
+// Lazy async HMAC that matches the server's Web Crypto implementation
+
+// Lazy async HMAC that matches the server's Web Crypto implementation
+async function signRequest(sessionId) {
+  if (!sessionSecret) return {};
+  const timestamp = String(Date.now());
+  const { createHmac } = await import("crypto");
+  const hmac = createHmac("sha256", sessionSecret).update(`${sessionId}:${timestamp}`).digest("hex");
+  return {
+    "x-bb-hmac": hmac,
+    "x-bb-timestamp": timestamp,
+  };
+}
+
+export async function runBridge(args) {
+  const cfg = getConfig();
+  if (!cfg.api_key && !cfg.access_token) {
+    die(`Not authenticated. Run: ${cyan("botbuddy login")} or ${cyan("botbuddy register <name>")}`);
+  }
+
+  // Parse args
+  let wsPort = 4500;
+  let repoPath = process.cwd();
+  let model = "gpt-5.4";
+  let autoStart = false;
+
+  for (let i = 0; i < args.length; i++) {
+    if ((args[i] === "--port" || args[i] === "-p") && args[i + 1]) wsPort = parseInt(args[++i], 10);
+    else if ((args[i] === "--repo" || args[i] === "-r") && args[i + 1]) repoPath = args[++i];
+    else if ((args[i] === "--model" || args[i] === "-m") && args[i + 1]) model = args[++i];
+    else if (args[i] === "--auto-start") autoStart = true;
+  }
+
+  const wsUrl = `ws://127.0.0.1:${wsPort}`;
+  const hostname = (await import("os")).then(m => m.hostname());
+  const host = await hostname;
+
+  console.log(`${bold("BotBuddy Codex Bridge")}\n`);
+  console.log(`  ${dim("WebSocket:")} ${cyan(wsUrl)}`);
+  console.log(`  ${dim("Repo:")}      ${cyan(repoPath)}`);
+  console.log(`  ${dim("Model:")}     ${cyan(model)}`);
+  console.log(`  ${dim("Host:")}      ${dim(host)}`);
+  console.log(`  ${dim("Security:")}  ${green("HMAC-SHA256")} session signing + ${green("loopback-only")} WS\n`);
+
+  // ── Step 1: Register bridge session with BotBuddy ──
+  console.log(dim("→ Connecting to BotBuddy..."));
+  const session = await relayPost("/bridge/connect", {
+    bridge_name: cfg.agent_name || `bridge-${host}`,
+    machine_host: host,
+    repo_path: repoPath,
+    config: { ws_port: wsPort, model, auto_start: autoStart },
+  });
+
+  if (!session?.session?.id) die("Failed to register bridge session");
+  const sessionId = session.session.id;
+
+  // Store session secret for HMAC signing
+  if (session.session_secret) {
+    sessionSecret = session.session_secret;
+    console.log(`  ${green("✓")} HMAC session secret received`);
+  } else {
+    console.log(`  ${yellow("⚠")} No session secret — HMAC signing disabled`);
+  }
+  console.log(`  ${green("✓")} Bridge session: ${dim(sessionId)}\n`);
+
+  // ── Step 2: Connect to local Codex app-server ──
+  let ws = null;
+  let wsConnected = false;
+  let msgId = 100;
+  let initialized = false;
+  const pendingRequests = new Map(); // id → { resolve, reject }
+  const threads = new Map(); // codex_thread_id → bb_thread_id
+
+  // Generate a nonce for localhost verification
+  const bridgeNonce = randomBytes(16).toString("hex");
+
+  function connectWs() {
+    console.log(dim(`→ Connecting to Codex app-server at ${wsUrl}...`));
+    try {
+      ws = new WebSocket(wsUrl);
+    } catch (err) {
+      console.log(`  ${red("✗")} WebSocket connection failed: ${err.message}`);
+      console.log(`  ${dim("Make sure codex app-server is running:")}`);
+      console.log(`  ${cyan(`codex app-server --listen ${wsUrl}`)}\n`);
+      setTimeout(connectWs, 5000);
+      return;
+    }
+
+    ws.onopen = async () => {
+      wsConnected = true;
+      console.log(`  ${green("✓")} Connected to Codex app-server`);
+
+      // Verify we're actually on localhost (defense-in-depth)
+      try {
+        const wsUrlObj = new URL(wsUrl.replace("ws://", "http://"));
+        const resolvedHost = wsUrlObj.hostname;
+        if (resolvedHost !== "127.0.0.1" && resolvedHost !== "localhost" && resolvedHost !== "::1") {
+          console.log(`  ${red("✗")} SECURITY: Refusing non-loopback connection to ${resolvedHost}`);
+          ws.close();
+          return;
+        }
+      } catch {}
+
+      // Initialize handshake with bridge identity nonce
+      const initResult = await sendWs("initialize", {
+        clientInfo: {
+          name: "botbuddy_bridge",
+          title: "BotBuddy Codex Bridge",
+          version: "1.0.0",
+          bridgeNonce,
+        },
+        capabilities: { experimentalApi: true },
+      });
+      console.log(`  ${green("✓")} Initialized: platform=${initResult?.platformFamily || "unknown"}`);
+
+      // Send initialized notification
+      ws.send(JSON.stringify({ method: "initialized", params: {} }));
+      initialized = true;
+      console.log(`  ${green("✓")} Handshake complete — ready for commands\n`);
+    };
+
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(event.data);
+        handleAppServerMessage(msg);
+      } catch (err) {
+        console.error("Failed to parse app-server message:", err);
+      }
+    };
+
+    ws.onclose = () => {
+      wsConnected = false;
+      initialized = false;
+      console.log(`\n  ${red("✗")} Codex app-server disconnected. Reconnecting in 5s...`);
+      setTimeout(connectWs, 5000);
+    };
+
+    ws.onerror = (err) => {
+      console.error(`  ${red("✗")} WebSocket error`);
+    };
+  }
+
+  function sendWs(method, params = {}) {
+    return new Promise((resolve, reject) => {
+      const id = msgId++;
+      pendingRequests.set(id, { resolve, reject });
+      const msg = { method, id, params };
+      ws.send(JSON.stringify(msg));
+      // Timeout after 30s
+      setTimeout(() => {
+        if (pendingRequests.has(id)) {
+          pendingRequests.delete(id);
+          reject(new Error(`Timeout waiting for response to ${method}`));
+        }
+      }, 30000);
+    });
+  }
+
+  async function handleAppServerMessage(msg) {
+    // Response to a request we made
+    if (msg.id !== undefined && pendingRequests.has(msg.id)) {
+      const { resolve, reject } = pendingRequests.get(msg.id);
+      pendingRequests.delete(msg.id);
+      if (msg.error) reject(new Error(msg.error.message));
+      else resolve(msg.result);
+      return;
+    }
+
+    // Notification from app-server
+    if (msg.method) {
+      const eventType = msg.method;
+      const payload = msg.params || {};
+
+      // Handle thread lifecycle
+      if (eventType === "thread/started") {
+        const threadId = payload.thread?.id;
+        if (threadId) {
+          console.log(`  ${cyan("◆")} Thread started: ${threadId}`);
+          const result = await relayPost("/bridge/thread-update", {
+            session_id: sessionId,
+            codex_thread_id: threadId,
+            status: "active",
+            model,
+          });
+          if (result?.thread_id) threads.set(threadId, result.thread_id);
+        }
+      }
+
+      if (eventType === "turn/started") {
+        console.log(`  ${cyan("▸")} Turn started: ${payload.turn?.id || "?"}`);
+      }
+
+      if (eventType === "turn/completed") {
+        const status = payload.turn?.status || "completed";
+        console.log(`  ${status === "completed" ? green("✓") : red("✗")} Turn ${payload.turn?.id}: ${status}`);
+
+        // Extract and forward token usage if present
+        const usage = payload.turn?.usage || payload.usage;
+        if (usage) {
+          const threadId = payload.thread?.id || payload.threadId;
+          if (threadId) {
+            const updatePayload = { session_id: sessionId, codex_thread_id: threadId };
+            if (usage.input_tokens !== undefined) updatePayload.input_tokens = usage.input_tokens;
+            if (usage.output_tokens !== undefined) updatePayload.output_tokens = usage.output_tokens;
+            if (usage.total_tokens !== undefined) {
+              updatePayload.input_tokens = updatePayload.input_tokens || 0;
+              updatePayload.output_tokens = updatePayload.output_tokens || (usage.total_tokens - (updatePayload.input_tokens || 0));
+            }
+            if (usage.cost_cents !== undefined) updatePayload.total_cost_cents = usage.cost_cents;
+            await relayPost("/bridge/thread-update", updatePayload).catch(() => {});
+            console.log(`  ${dim(`tokens: ${usage.input_tokens || 0}↑ ${usage.output_tokens || 0}↓`)}`);
+          }
+        }
+      }
+
+      if (eventType === "item/agentMessage/delta") {
+        const text = payload.delta?.text || "";
+        if (text) process.stdout.write(dim(text));
+      }
+
+      if (eventType === "item/started") {
+        const itemType = payload.item?.type;
+        if (itemType === "commandRun") {
+          console.log(`\n  ${cyan("$")} ${payload.item?.command || ""}`);
+        }
+      }
+
+      // Capture rate limits from codex app-server
+      if (eventType === "codex.rate_limits") {
+        console.log(`  ${dim("⟳ Rate limits updated")}`);
+        await relayPost("/bridge/rate-limits", {
+          session_id: sessionId,
+          rate_limits: payload,
+        }).catch(() => {});
+      }
+
+      if (eventType === "thread/status/changed") {
+        const threadId = payload.threadId;
+        const status = payload.status?.type;
+        if (threadId && status) {
+          await relayPost("/bridge/thread-update", {
+            session_id: sessionId,
+            codex_thread_id: threadId,
+            status,
+          });
+        }
+      }
+
+      // Forward event to BotBuddy
+      const bbThreadId = payload.thread?.id ? threads.get(payload.thread.id) :
+                         payload.threadId ? threads.get(payload.threadId) : null;
+      if (bbThreadId) {
+        await relayPost("/bridge/event", {
+          session_id: sessionId,
+          thread_id: bbThreadId,
+          event_type: eventType,
+          turn_id: payload.turn?.id || payload.turnId,
+          item_id: payload.item?.id,
+          payload,
+        }).catch(() => {}); // non-critical
+      }
+    }
+  }
+
+  // ── Step 3: Poll for commands from BotBuddy ──
+  async function pollCommands() {
+    try {
+      const result = await relayGet("/bridge/command-poll");
+      const commands = result?.commands || [];
+      for (const cmd of commands) {
+        await executeCommand(cmd);
+      }
+    } catch (err) {
+      // Silently retry
+    }
+  }
+
+  async function executeCommand(cmd) {
+    console.log(`\n  ${cyan("⟐")} Command: ${cmd.command} ${JSON.stringify(cmd.params)}`);
+
+    try {
+      if (!wsConnected || !initialized) {
+        await relayPost("/bridge/command-result", {
+          command_id: cmd.id,
+          status: "failed",
+          result: { error: "Codex app-server not connected" },
+        });
+        return;
+      }
+
+      let result;
+
+      switch (cmd.command) {
+        case "thread/start": {
+          result = await sendWs("thread/start", {
+            model: cmd.params.model || model,
+            cwd: cmd.params.cwd || repoPath,
+            approvalPolicy: cmd.params.approval_policy || "never",
+            sandbox: cmd.params.sandbox || "workspaceWrite",
+          });
+          // Track thread
+          if (result?.thread?.id) {
+            const bbResult = await relayPost("/bridge/thread-update", {
+              session_id: sessionId,
+              codex_thread_id: result.thread.id,
+              title: cmd.params.title,
+              model: cmd.params.model || model,
+              status: "idle",
+              cwd: cmd.params.cwd || repoPath,
+            });
+            if (bbResult?.thread_id) threads.set(result.thread.id, bbResult.thread_id);
+          }
+          break;
+        }
+
+        case "turn/start": {
+          const codexThreadId = await resolveCodexThreadId(cmd.thread_id);
+          if (!codexThreadId) {
+            result = { error: "Thread not found" };
+            break;
+          }
+          result = await sendWs("turn/start", {
+            threadId: codexThreadId,
+            input: [{ type: "text", text: cmd.params.prompt || cmd.params.text || "" }],
+            ...(cmd.params.model && { model: cmd.params.model }),
+          });
+          break;
+        }
+
+        case "turn/interrupt": {
+          const codexTid = await resolveCodexThreadId(cmd.thread_id);
+          if (!codexTid) { result = { error: "Thread not found" }; break; }
+          result = await sendWs("turn/interrupt", {
+            threadId: codexTid,
+            turnId: cmd.params.turn_id,
+          });
+          break;
+        }
+
+        case "thread/list": {
+          result = await sendWs("thread/list", {
+            limit: cmd.params.limit || 25,
+          });
+          break;
+        }
+
+        default:
+          // Pass through any other app-server method
+          result = await sendWs(cmd.command, cmd.params);
+      }
+
+      await relayPost("/bridge/command-result", {
+        command_id: cmd.id,
+        status: "completed",
+        result,
+      });
+      console.log(`  ${green("✓")} Command completed`);
+    } catch (err) {
+      console.error(`  ${red("✗")} Command failed: ${err.message}`);
+      await relayPost("/bridge/command-result", {
+        command_id: cmd.id,
+        status: "failed",
+        result: { error: err.message },
+      });
+    }
+  }
+
+  async function resolveCodexThreadId(bbThreadId) {
+    // Look up in local map first
+    for (const [codexId, bbId] of threads.entries()) {
+      if (bbId === bbThreadId) return codexId;
+    }
+    // Fallback: query DB via relay
+    return null;
+  }
+
+  // ── Step 4: Ping + command poll loops ──
+  const pingInterval = setInterval(async () => {
+    try {
+      await relayPost("/bridge/ping", { session_id: sessionId });
+    } catch {}
+  }, PING_INTERVAL_MS);
+
+  const pollInterval = setInterval(pollCommands, POLL_INTERVAL_MS);
+
+  // ── Step 5: Graceful shutdown ──
+  const shutdown = async () => {
+    console.log(`\n${dim("→ Shutting down bridge...")}`);
+    clearInterval(pingInterval);
+    clearInterval(pollInterval);
+    try {
+      await relayPost("/bridge/disconnect", { session_id: sessionId });
+    } catch {}
+    if (ws) ws.close();
+    console.log(`${green("✓")} Bridge disconnected.`);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // ── Start ──
+  connectWs();
+  console.log(dim("Polling for commands from BotBuddy...\n"));
+}
+
+// ─── HTTP helpers ───
+
+function authHeaders() {
+  const cfg = getConfig();
+  const headers = { "Content-Type": "application/json" };
+  if (cfg.api_key) headers["x-agent-api-key"] = cfg.api_key;
+  else if (cfg.access_token) headers["Authorization"] = `Bearer ${cfg.access_token}`;
+  return headers;
+}
+
+async function relayPost(path, body) {
+  const headers = authHeaders();
+  // Add HMAC signing if we have a session secret and session_id
+  if (sessionSecret && body?.session_id) {
+    const hmacHeaders = await signRequest(body.session_id);
+    Object.assign(headers, hmacHeaders);
+  }
+  const res = await fetch(`${RELAY_URL}${path}`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  return res.json();
+}
+
+async function relayGet(path) {
+  const res = await fetch(`${RELAY_URL}${path}`, {
+    method: "GET",
+    headers: authHeaders(),
+  });
+  return res.json();
+}

package/src/commands.mjs

@@ -0,0 +1,225 @@
+import { callTool, readResource } from "./api.mjs";
+import { doLogin } from "./auth.mjs";
+import { runBridge } from "./codex-bridge.mjs";
+import { loadConfig, getConfig, clearConfig, saveConfig, getConfigPath } from "./config.mjs";
+import { green, red, cyan, dim, bold, die } from "./utils.mjs";
+
+const VERSION = "1.0.0";
+
+export function run(argv) {
+  loadConfig();
+  const [command, ...args] = argv;
+
+  switch (command) {
+    case "login": return doLogin();
+    case "logout": return cmdLogout();
+    case "status": return cmdStatus();
+    case "register": return cmdRegister(args);
+    case "heartbeat": return cmdHeartbeat(args);
+    case "lock": return cmdLock(args);
+    case "locks": return cmdLocks(args);
+    case "unlock": return cmdUnlock(args);
+    case "resources": return callTool("list_resources");
+    case "agents": return callTool("list_agents");
+    case "tasks": return readResource("botbuddy://tasks");
+    case "task": return cmdTask(args);
+    case "hours": return cmdHours(args);
+    case "browse": return cmdBrowse(args);
+    case "codex": return cmdCodex(args);
+    case "version": case "--version": case "-v":
+      console.log(`botbuddy v${VERSION}`); return;
+    case "help": case "--help": case "-h": case undefined:
+      return cmdHelp();
+    default:
+      die(`Unknown command: ${command}. Run ${cyan("botbuddy help")} for usage.`);
+  }
+}
+
+function cmdHelp() {
+  console.log(`${bold("botbuddy")} ${dim(`v${VERSION}`)} — Swarm coordination CLI
+
+${bold("USAGE")}
+  botbuddy <command> [options]
+
+${bold("AUTH")}
+  login                    Authenticate via OAuth (PKCE)
+  logout                   Remove saved credentials
+  status                   Show current auth status
+
+${bold("AGENTS")}
+  register <name> [type]   Register a new agent (type: codex|claude|gpt|custom)
+  agents                   List all agents
+  heartbeat [task]         Send a heartbeat
+
+${bold("RESOURCES")}
+  lock <name> <type>       Acquire a single lock (type: port|mcp_server|file|...)
+  locks [options]          Batch-acquire resources (auto-assigns free ones)
+    -p, --port [type]      Request a port (frontend|backend, default: frontend)
+    -m, --mcp              Request an MCP server slot
+    -t, --ticket <id>      Ticket ID (shared across all locks)
+    --pr <id>              PR ID (shared across all locks)
+  unlock <name>            Release a lock
+  resources                List all resources and locks
+
+${bold("TASKS")}
+  task create <title> [-d description] [-p priority]
+  task claim <id>          Claim a pending task
+  task done <id>           Mark a task as done
+  tasks                    List all tasks
+
+${bold("SWARM")}
+  hours                    Get current working hours
+  hours derive             Derive working hours from activity
+  hours set <json>         Set working hours manually
+
+${bold("BROWSE")}
+  browse agents|tasks|resources|activity|settings
+
+${bold("CODEX")}
+  codex bridge [options]   Start Codex app-server bridge
+    -p, --port <port>      WebSocket port (default: 4500)
+    -r, --repo <path>      Repository path (default: cwd)
+    -m, --model <model>    Default model (default: gpt-5.4)
+    --auto-start           Auto-start app-server
+
+${bold("OTHER")}
+  help                     Show this help
+  version                  Show version`);
+}
+
+function cmdStatus() {
+  const cfg = getConfig();
+  if (cfg.access_token) {
+    console.log(`${green("✓")} Authenticated via OAuth`);
+    if (cfg.agent_name) console.log(`  Agent: ${cyan(cfg.agent_name)}`);
+    if (cfg.client_id) console.log(`  Client: ${dim(cfg.client_id)}`);
+    if (cfg.token_expires_at) {
+      const remaining = cfg.token_expires_at - Date.now();
+      if (remaining <= 0) {
+        console.log(`  Token: ${red("EXPIRED")} — run ${cyan("botbuddy login")}`);
+      } else {
+        const mins = Math.round(remaining / 60000);
+        const label = mins > 60 ? `${Math.round(mins / 60)}h ${mins % 60}m` : `${mins}m`;
+        console.log(`  Token expires in: ${dim(label)}`);
+      }
+    }
+    console.log(`  Config: ${dim(getConfigPath())}`);
+  } else if (cfg.api_key) {
+    console.log(`${green("✓")} Authenticated via API key`);
+    if (cfg.agent_name) console.log(`  Agent: ${cyan(cfg.agent_name)}`);
+  } else {
+    console.log(`${red("✗")} Not authenticated`);
+    console.log(`  Run: ${cyan("botbuddy login")}`);
+  }
+}
+
+function cmdLogout() {
+  clearConfig();
+  console.log(`${green("✓")} Logged out. Credentials removed.`);
+}
+
+async function cmdRegister(args) {
+  const name = args[0];
+  if (!name) die("Usage: botbuddy register <name> [type]");
+  const type = args[1] || "custom";
+  const data = await callTool("register_agent", { name, type });
+  const text = data?.result?.content?.[0]?.text;
+  if (text) {
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed.api_key) {
+        saveConfig({ ...getConfig(), api_key: parsed.api_key, agent_id: parsed.agent_id, agent_name: name });
+      }
+    } catch {}
+  }
+}
+
+function cmdHeartbeat(args) {
+  return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
+}
+
+function cmdLock(args) {
+  if (args.length < 2) die("Usage: botbuddy lock <resource_name> <type>");
+  return callTool("acquire_lock", { resource_name: args[0], resource_type: args[1] });
+}
+
+function cmdLocks(args) {
+  const resources = [];
+  let ticketId, prId;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "-p" || args[i] === "--port") {
+      const portType = (args[i + 1] && !args[i + 1].startsWith("-")) ? args[++i] : "frontend";
+      resources.push({ resource_type: "port", port_type: portType });
+    } else if (args[i] === "-m" || args[i] === "--mcp") {
+      resources.push({ resource_type: "mcp_server" });
+    } else if (args[i] === "-t" || args[i] === "--ticket") {
+      ticketId = args[++i];
+    } else if (args[i] === "--pr") {
+      prId = args[++i];
+    }
+  }
+  if (!resources.length) {
+    die("Usage: botbuddy locks -p [frontend|backend] -m [-t ticket] [--pr id]");
+  }
+  const payload = { resources };
+  if (ticketId) payload.ticket_id = ticketId;
+  if (prId) payload.pr_id = prId;
+  return callTool("acquire_resources", payload);
+}
+
+function cmdUnlock(args) {
+  if (!args[0]) die("Usage: botbuddy unlock <resource_name>");
+  return callTool("release_lock", { resource_name: args[0] });
+}
+
+function cmdTask(args) {
+  const sub = args[0];
+  if (!sub) die("Usage: botbuddy task <create|claim|done> ...");
+  switch (sub) {
+    case "create": {
+      const title = args[1];
+      if (!title) die("Usage: botbuddy task create <title> [-d desc] [-p priority]");
+      let desc = "", priority = 0;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === "-d" && args[i + 1]) { desc = args[++i]; }
+        else if (args[i] === "-p" && args[i + 1]) { priority = parseInt(args[++i], 10); }
+      }
+      return callTool("create_task", { title, description: desc, priority });
+    }
+    case "claim":
+      if (!args[1]) die("Usage: botbuddy task claim <task_id>");
+      return callTool("claim_task", { task_id: args[1] });
+    case "done":
+      if (!args[1]) die("Usage: botbuddy task done <task_id>");
+      return callTool("complete_task", { task_id: args[1] });
+    default:
+      die(`Unknown task subcommand: ${sub}`);
+  }
+}
+
+function cmdHours(args) {
+  switch (args[0]) {
+    case "derive": return callTool("derive_working_hours");
+    case "set":
+      if (!args[1]) die("Usage: botbuddy hours set '<json_schedule>'");
+      return callTool("set_working_hours", { schedule: JSON.parse(args[1]) });
+    default:
+      return callTool("get_working_hours");
+  }
+}
+
+function cmdBrowse(args) {
+  if (!args[0]) die("Usage: botbuddy browse <agents|tasks|resources|activity|settings>");
+  return readResource(`botbuddy://${args[0]}`);
+}
+
+function cmdCodex(args) {
+  const sub = args[0];
+  if (!sub) die("Usage: botbuddy codex <bridge> [options]");
+  switch (sub) {
+    case "bridge":
+      return runBridge(args.slice(1));
+    default:
+      die(`Unknown codex subcommand: ${sub}. Try: botbuddy codex bridge`);
+  }
+}

package/src/config.mjs

@@ -0,0 +1,40 @@
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const CONFIG_DIR = join(homedir(), ".botbuddy");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export const SERVER_URL = "https://tpnivjpoayjmexclfpav.supabase.co/functions/v1/mcp-server";
+
+let config = {};
+
+export function loadConfig() {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      config = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+  } catch {
+    config = {};
+  }
+  return config;
+}
+
+export function saveConfig(data) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+  chmodSync(CONFIG_FILE, 0o600);
+  config = data;
+}
+
+export function getConfig() {
+  return config;
+}
+
+export function clearConfig() {
+  try { unlinkSync(CONFIG_FILE); } catch {}
+}
+
+export function getConfigPath() {
+  return CONFIG_FILE;
+}

package/src/utils.mjs

@@ -0,0 +1,19 @@
+export const red = (s) => `\x1b[31m${s}\x1b[0m`;
+export const green = (s) => `\x1b[32m${s}\x1b[0m`;
+export const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+export const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+export const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+export const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+export function die(msg) {
+  console.error(`${red("✗")} ${msg}`);
+  process.exit(1);
+}
+
+export function prettyJson(text) {
+  try {
+    return JSON.stringify(JSON.parse(text), null, 2);
+  } catch {
+    return text;
+  }
+}