@cohortapp/agent-sdk 2.3.0

package/scripts/setup/init-telegram.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/**
+ * init-telegram.mjs — Idempotent init for the Telegram channel (grammY).
+ *
+ * Mirrors init-whatsapp-baileys.mjs + init-slack-socket-mode.mjs:
+ *   1. Walks the operator through creating a bot with @BotFather.
+ *   2. Prompts for the bot token → appends TELEGRAM_BOT_TOKEN to .env
+ *      (never overwrites an existing value; skips the prompt off-TTY).
+ *   3. Validates the token via the Telegram getMe API (no grammy needed).
+ *   4. Activates config/telegram.yaml from the scaffold example.
+ *   5. Checks for the optional `grammy` package and prints an install hint.
+ *
+ * Opt-in: grammY is a dynamic dependency, so the daemon only loads Telegram
+ * when config/telegram.yaml exists. Safe to re-run.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-telegram]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-telegram]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-telegram]    ${m}\n`);
+const fail = (m) => process.stderr.write(`[init-telegram]  ✗ ${m}\n`);
+
+function printWalkthrough() {
+  process.stdout.write(`
+================================================================================
+Telegram Setup — create a bot with @BotFather
+================================================================================
+
+Telegram gives the agent realtime DMs/groups via long-polling (no public
+webhook, runs inside the daemon). You need a bot token from BotFather.
+
+Step 1 — Create the bot
+   Open Telegram, message @BotFather, send: /newbot
+   Choose a display name and a username ending in "bot".
+   BotFather replies with an HTTP API token like: 123456789:ABCdef...
+
+Step 2 — (optional) Let the bot read all group messages
+   @BotFather → /setprivacy → pick your bot → Disable.
+   (Otherwise the bot only sees @mentions, replies, and commands in groups.)
+
+Step 3 — Paste the token below, or add it manually to ${join(AGENT_DIR, ".env")}:
+     TELEGRAM_BOT_TOKEN=123456789:ABCdef...
+
+================================================================================
+`);
+}
+
+function readEnv(envPath) {
+  if (!existsSync(envPath)) return {};
+  const map = {};
+  for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+    const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (m) map[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return map;
+}
+
+function appendEnvLine(envPath, key, value) {
+  if (!existsSync(envPath)) { writeFileSync(envPath, `${key}=${value}\n`); return; }
+  const body = readFileSync(envPath, "utf-8");
+  const suffix = body.endsWith("\n") ? "" : "\n";
+  appendFileSync(envPath, `${suffix}${key}=${value}\n`);
+}
+
+async function promptForToken() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question("Paste your TELEGRAM_BOT_TOKEN (digits:ABC…), or press ENTER to skip: ");
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+/** Validate a token via the Telegram getMe API. Returns { ok, username?, error? }. */
+async function validateToken(token) {
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/getMe`);
+    const body = await res.json();
+    if (body.ok && body.result?.username) return { ok: true, username: body.result.username };
+    return { ok: false, error: body.description || "getMe returned not-ok" };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+async function ensureTokenInEnv() {
+  const envPath = join(AGENT_DIR, ".env");
+  const env = readEnv(envPath);
+  const existing = env.TELEGRAM_BOT_TOKEN || "";
+  if (/^\d+:[\w-]+$/.test(existing)) {
+    ok("TELEGRAM_BOT_TOKEN already set in .env");
+    return existing;
+  }
+  if (!process.stdin.isTTY) {
+    warn("TELEGRAM_BOT_TOKEN missing and stdin is non-interactive — skipping prompt.");
+    info(`Add it manually to ${envPath}:  TELEGRAM_BOT_TOKEN=123456789:ABC…`);
+    return "";
+  }
+  const token = await promptForToken();
+  if (!token) {
+    warn("No token provided — skipping. Add it manually before starting the daemon.");
+    return "";
+  }
+  if (!/^\d+:[\w-]+$/.test(token)) {
+    fail(`Token doesn't look like a Telegram bot token (digits:ABC…) — got '${token.slice(0, 8)}…'. Skipping.`);
+    return "";
+  }
+  appendEnvLine(envPath, "TELEGRAM_BOT_TOKEN", token);
+  ok(`TELEGRAM_BOT_TOKEN appended to ${envPath}`);
+  return token;
+}
+
+function activateGateFile() {
+  const exampleSrc = join(MAESTRO_ROOT, "scaffold/config/telegram.yaml.example");
+  const cfgDir = join(AGENT_DIR, "config");
+  mkdirSync(cfgDir, { recursive: true });
+  const activePath = join(cfgDir, "telegram.yaml");
+  if (existsSync(activePath)) { ok("config/telegram.yaml already present"); return; }
+  if (!existsSync(exampleSrc)) { warn(`scaffold/config/telegram.yaml.example missing in ${MAESTRO_ROOT}`); return; }
+  copyFileSync(exampleSrc, activePath);
+  ok("activated config/telegram.yaml from scaffold");
+}
+
+function checkGrammy() {
+  const pkg = join(AGENT_DIR, "node_modules/grammy/package.json");
+  if (existsSync(pkg)) { ok("grammy npm package present in agent"); }
+  else {
+    warn("grammy npm package NOT present in agent");
+    info(`  Install with: cd ${AGENT_DIR} && npm i grammy`);
+  }
+}
+
+async function main() {
+  printWalkthrough();
+  const token = await ensureTokenInEnv();
+
+  if (token) {
+    const v = await validateToken(token);
+    if (v.ok) ok(`token valid — bot is @${v.username}`);
+    else warn(`token validation failed: ${v.error}`);
+  }
+
+  activateGateFile();
+  checkGrammy();
+
+  info("DM pairing is default-deny: unknown senders must `pair <code>` first.");
+  info("Seed allowlisted ids in config/allowlist.yaml under `telegram:` or pair at runtime.");
+  ok("init-telegram complete");
+  info("Verify with: maestro doctor   (and DM the bot once the daemon is running)");
+}
+
+main().catch((err) => {
+  fail(`unexpected error: ${err.message}`);
+  process.stderr.write(`${err.stack}\n`);
+  process.exit(1);
+});

package/scripts/setup/init-voice-realtime.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * init-voice-realtime.mjs — Idempotent init step for the voice-realtime feature.
+ *
+ * Sets up the OpenAI Realtime voice channel for an agent. Safe to run
+ * repeatedly — every step checks state and only acts on what's missing.
+ *
+ * What this installs (v2, post-1.12.20):
+ *   1. Copy scaffold/config/voice.yaml.example → config/voice.yaml.disabled
+ *      (operator activates by renaming to .yaml once configured).
+ *   2. Patch .env.example with voice-related placeholders (OpenAI key, Twilio,
+ *      cloud-relay URL + tokens).
+ *   3. Install ~/Library/LaunchAgents/ai.maestro.<firstname>-voice-webhook.plist
+ *      from scripts/local-triggers/templates/ (uses the agent's own copy of
+ *      voice-webhook-server.mjs — no MAESTRO_ROOT runtime dep).
+ *   4. Install ai.maestro.<firstname>-voice-relay-poller.plist for the
+ *      Railway-fronted SIP poll loop.
+ *   5. Verify a recent enough `openai` npm package is available.
+ *   6. Create logs/voice/{sessions,outbound-audio} + state/voice/.
+ *   7. Print next-step checklist (Twilio SIP trunk, OpenAI dashboard config).
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+
+import { installPlist, bootInLaunchd } from "./lib/install-plist.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+// MAESTRO_ROOT here is only used to find the scaffold/ directory which lives
+// inside the npm package install location. At runtime the agent uses its own
+// colocated copies under AGENT_DIR/lib + scripts. Setting MAESTRO_ROOT explicitly
+// only matters during `npx @cohortapp/agent-sdk init/upgrade` invocation.
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const args = new Set(process.argv.slice(2));
+const skipPlists = args.has("--skip-plists");
+const skipBoot = args.has("--skip-boot");
+
+const ok = (m) => process.stdout.write(`[init-voice-realtime]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-voice-realtime]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-voice-realtime]  · ${m}\n`);
+
+// Resolve agent's first name from config/agent.json — needed for plist labels.
+function loadFirstname() {
+  const agentJsonPath = join(AGENT_DIR, "config/agent.json");
+  if (existsSync(agentJsonPath)) {
+    try {
+      const j = JSON.parse(readFileSync(agentJsonPath, "utf-8"));
+      const n = j.firstName || j.fullName?.split(/\s+/)[0] || "";
+      return n.toLowerCase().replace(/[^a-z0-9]/g, "");
+    } catch { /* fall through */ }
+  }
+  return "agent";
+}
+const firstname = loadFirstname();
+
+// ── 1. Place the disabled config file ──────────────────────────────────────
+// The scaffold lives inside the npm package install dir, not the agent repo,
+// so when this script is invoked via `npx @cohortapp/agent-sdk init` MAESTRO_ROOT
+// points at the npx cache and finds scaffold/. When invoked directly inside
+// an already-bootstrapped agent repo, scaffold/ is absent — that's fine
+// PROVIDED config/voice.yaml{,.disabled} is already in place. Only error if
+// both are missing (which means the agent never went through the wizard).
+const exampleSrc = join(MAESTRO_ROOT, "scaffold/config/voice.yaml.example");
+const cfgDir = join(AGENT_DIR, "config");
+mkdirSync(cfgDir, { recursive: true });
+
+const activePath = join(cfgDir, "voice.yaml");
+const disabledPath = join(cfgDir, "voice.yaml.disabled");
+
+if (existsSync(activePath)) {
+  ok("config/voice.yaml is already in place");
+} else if (existsSync(disabledPath)) {
+  info("config/voice.yaml.disabled is present; rename to config/voice.yaml to activate.");
+} else if (existsSync(exampleSrc)) {
+  copyFileSync(exampleSrc, disabledPath);
+  ok("placed scaffold/voice.yaml.example at config/voice.yaml.disabled");
+} else {
+  warn(`No voice.yaml present and scaffold/config/voice.yaml.example not found at ${MAESTRO_ROOT}.`);
+  warn("Either run `npx @cohortapp/agent-sdk init voice-realtime` (uses scaffold from npm package)");
+  warn("or create config/voice.yaml manually using docs/guides/voice-mode.md as a reference.");
+  process.exit(1);
+}
+
+// ── 2. Patch .env.example with all voice-stack vars ───────────────────────
+const envExamplePath = join(AGENT_DIR, ".env.example");
+if (existsSync(envExamplePath)) {
+  let body = readFileSync(envExamplePath, "utf-8");
+  let changed = false;
+  const placeholders = [
+    ["OPENAI_API_KEY", "OpenAI API key — required for voice; also used as classifier fallback"],
+    ["OPENAI_SAFETY_IDENTIFIER", "Optional hashed-user-id for OpenAI safety telemetry"],
+    ["OPENAI_WEBHOOK_SECRET", "OpenAI webhook signing secret (Settings → Webhooks → realtime.call.incoming)"],
+    ["TWILIO_ACCOUNT_SID", "Twilio account SID — required if using Twilio SIP/voice"],
+    ["TWILIO_AUTH_TOKEN", "Twilio auth token"],
+    ["TWILIO_SIP_TRUNK_SID", "Twilio Elastic SIP Trunk SID for native OpenAI SIP integration"],
+    ["VOICE_RELAY_URL", "Cloud-relay base URL (Railway-deployed). e.g. https://<name>.up.railway.app"],
+    ["VOICE_RELAY_POLL_TOKEN", "Bearer token for polling the cloud-relay drain endpoint"],
+    ["VOICE_TWIML_TOKEN", "Bearer token Twilio presents when fetching the TwiML for Media Streams outbound"],
+    ["VOICE_BROWSER_TOKEN", "Bearer token required to mint browser-side voice/test session"],
+  ];
+  for (const [key, comment] of placeholders) {
+    if (!new RegExp(`^${key}=`, "m").test(body)) {
+      if (!body.endsWith("\n")) body += "\n";
+      body += `\n# ${comment}\n${key}=\n`;
+      changed = true;
+    }
+  }
+  if (changed) {
+    writeFileSync(envExamplePath, body);
+    ok("appended voice env-var placeholders to .env.example");
+  } else {
+    info(".env.example already has voice env-var placeholders");
+  }
+}
+
+// ── 3. Sanity-check the `openai` package ───────────────────────────────────
+try {
+  const candidatePkg = [
+    join(AGENT_DIR, "node_modules/openai/package.json"),
+    join(MAESTRO_ROOT, "node_modules/openai/package.json"),
+  ].find((p) => existsSync(p));
+  if (candidatePkg) {
+    const v = JSON.parse(readFileSync(candidatePkg, "utf-8")).version;
+    const major = parseInt(v.split(".")[0], 10);
+    if (major >= 6) ok(`openai@${v} detected — Realtime helpers available`);
+    else warn(`openai@${v} is below 6.x; install latest with: npm i openai`);
+  } else {
+    info("openai npm package not installed — run `npm i openai` in the agent repo");
+  }
+} catch (err) {
+  warn(`unable to verify openai package: ${err.message}`);
+}
+
+// ── 4. Create transcript / audit dirs ──────────────────────────────────────
+for (const d of [
+  "logs/voice/sessions",
+  "logs/voice",
+  "state/voice",
+  "state/voice/outbound-audio",
+  "state/voice/outbound-briefs",
+  "state/inbox/voice",
+]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// ── 5. Install voice plists + boot them ────────────────────────────────────
+if (skipPlists) {
+  info("--skip-plists set — leaving ~/Library/LaunchAgents/ untouched");
+} else {
+  // Templates live inside the agent's *own* copy of scripts/local-triggers/
+  // (shipped via `npx @cohortapp/agent-sdk upgrade`), so we don't fall back into
+  // a MAESTRO_ROOT lookup. The plist installer hard-fails on missing files.
+  const templatesDir = join(AGENT_DIR, "scripts/local-triggers/templates");
+  const plists = [
+    { template: "voice-webhook.plist.template", label: "voice-webhook" },
+    { template: "voice-relay-poller.plist.template", label: "voice-relay-poller" },
+  ];
+  for (const { template, label } of plists) {
+    const templatePath = join(templatesDir, template);
+    if (!existsSync(templatePath)) {
+      warn(`template not found: ${templatePath} — skipping ${label}`);
+      continue;
+    }
+    try {
+      const { installedPath, changed, label: full } = installPlist({
+        templatePath,
+        firstname,
+        agentRoot: AGENT_DIR,
+        label,
+      });
+      ok(`${changed ? "installed" : "no-op (up-to-date)"} ${full} → ${installedPath}`);
+      if (!skipBoot && changed) {
+        try {
+          bootInLaunchd(installedPath);
+          ok(`booted ${full}`);
+        } catch (err) {
+          warn(`bootstrap failed for ${full}: ${err.message}`);
+          warn(`  retry with: launchctl bootstrap gui/$(id -u) "${installedPath}"`);
+        }
+      }
+    } catch (err) {
+      warn(`failed to install ${label}: ${err.message}`);
+    }
+  }
+}
+
+// ── 6. Print operator next-steps ───────────────────────────────────────────
+ok("done");
+info("Next steps:");
+info("  1. Add OPENAI_API_KEY (+ OPENAI_WEBHOOK_SECRET, VOICE_RELAY_*, TWILIO_*) to .env");
+info("  2. Edit config/voice.yaml.disabled (choose inbound mode + tools) and rename → config/voice.yaml");
+info("  3. Deploy cloud-relay to Railway (one-time): cd scripts/cloud-relay/voice && railway up");
+info("     • Set OPENAI_API_KEY + OPENAI_WEBHOOK_SECRET + VOICE_RELAY_POLL_TOKEN on Railway");
+info("     • Point the OpenAI realtime.call.incoming webhook at <railway-url>/openai/realtime/incoming");
+info("  4. Configure Twilio Elastic SIP Trunk: node scripts/setup/configure-twilio-sip-trunk.mjs");
+info("  5. Reload services: launchctl kickstart -k gui/$(id -u)/ai.maestro.<name>-voice-webhook");
+info("Runbook: docs/guides/voice-mode.md");

package/scripts/setup/init-whatsapp-baileys.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * init-whatsapp-baileys.mjs — Idempotent init for WhatsApp(Baileys).
+ *
+ * This is opt-in (auto: false) because Baileys violates WhatsApp ToS
+ * for business use. The wizard:
+ *   1. Places config/whatsapp.yaml.disabled if no whatsapp.yaml exists.
+ *   2. Creates state/whatsapp/{auth,audio,outbound}/ for Baileys state.
+ *   3. Checks for the `baileys` npm package in the agent's node_modules
+ *      and prints an install hint if missing.
+ *   4. Prints the QR-code instructions.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+const MAESTRO_ROOT = process.env.MAESTRO_ROOT || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[init-whatsapp-baileys]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[init-whatsapp-baileys]  ⚠ ${m}\n`);
+const info = (m) => process.stdout.write(`[init-whatsapp-baileys]  · ${m}\n`);
+
+const exampleSrc = join(MAESTRO_ROOT, "scaffold/config/whatsapp.yaml.example");
+if (!existsSync(exampleSrc)) {
+  warn(`scaffold/config/whatsapp.yaml.example missing in ${MAESTRO_ROOT}`);
+  process.exit(1);
+}
+
+const cfgDir = join(AGENT_DIR, "config");
+mkdirSync(cfgDir, { recursive: true });
+
+const activePath = join(cfgDir, "whatsapp.yaml");
+const disabledPath = join(cfgDir, "whatsapp.yaml.disabled");
+
+if (existsSync(activePath)) {
+  ok("config/whatsapp.yaml already present");
+} else if (existsSync(disabledPath)) {
+  info("config/whatsapp.yaml.disabled present; rename to activate");
+} else {
+  copyFileSync(exampleSrc, disabledPath);
+  ok("placed scaffold/whatsapp.yaml.example at config/whatsapp.yaml.disabled");
+}
+
+for (const d of [
+  "state/whatsapp/auth",
+  "state/whatsapp/audio",
+  "state/whatsapp/outbound",
+]) {
+  const full = join(AGENT_DIR, d);
+  if (!existsSync(full)) {
+    mkdirSync(full, { recursive: true });
+    ok(`created ${d}`);
+  }
+}
+
+// Check for baileys
+const pkg1 = join(AGENT_DIR, "node_modules/baileys/package.json");
+const pkg2 = join(AGENT_DIR, "node_modules/@whiskeysockets/baileys/package.json");
+if (existsSync(pkg1) || existsSync(pkg2)) {
+  ok("baileys npm package present in agent");
+} else {
+  warn("baileys npm package NOT present in agent");
+  info("  Install with: cd " + AGENT_DIR + " && npm i baileys");
+}
+
+info("First-run flow once the daemon starts the channel:");
+info("  1. Daemon prints QR text into state/whatsapp/auth/pending-qr.txt");
+info("  2. Operator renders QR (e.g. `cat … | qrencode -t ANSI`) and scans");
+info("  3. WhatsApp Web → Linked Devices → maestro session is now active");
+info("  4. Auth persists across restarts; do not lose state/whatsapp/auth/");
+warn("REMINDER: Baileys violates WhatsApp ToS for business use. For");
+warn("production / business deployments, use transport: twilio instead.");
+
+ok("done");

package/scripts/setup/install-dev-tools.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# install-dev-tools.sh — Install and configure approved dev tooling for Maestro agents
+#
+# Approved tools (audited 2026-04-18 from #dev-tooling channel):
+#   - claude-pace     — Rate limit status line tracker (Bash plugin)
+#   - agents-observe  — Multi-agent observability dashboard (CC plugin)
+#   - ccxray          — Claude Code token/cost observability proxy
+#   - ClawTeam        — Git worktree swarm orchestrator (CLI)
+#   - code-review-graph — Tree-sitter codebase knowledge graph (MCP)
+#
+# Skipped:
+#   - Superset        — GUI-only, Elastic License v2, not automatable
+#   - claudraband     — Evaluate later; overlaps with maestro session mgmt
+#
+# Usage: ./scripts/setup/install-dev-tools.sh [--all | --tool <name>]
+# Examples:
+#   ./scripts/setup/install-dev-tools.sh --all
+#   ./scripts/setup/install-dev-tools.sh --tool claude-pace
+#   ./scripts/setup/install-dev-tools.sh --tool ccxray
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+info()  { echo "  [INFO]  $1"; }
+ok()    { echo "  [OK]    $1"; }
+skip()  { echo "  [SKIP]  $1"; }
+fail()  { echo "  [FAIL]  $1" >&2; }
+
+# ── Tool installers ─────────────────────────────────────────────────────────
+
+install_claude_pace() {
+  info "Installing claude-pace (rate limit status line tracker)..."
+  if command -v claude >/dev/null 2>&1; then
+    # Install as Claude Code plugin
+    claude plugin install claude-pace 2>/dev/null && ok "claude-pace plugin installed" || {
+      info "Plugin install failed, trying npx setup..."
+      npx claude-pace setup 2>/dev/null && ok "claude-pace configured via npx" || skip "claude-pace: manual setup needed — see https://github.com/Astro-Han/claude-pace"
+    }
+  else
+    skip "claude-pace: Claude Code CLI not found"
+  fi
+}
+
+install_agents_observe() {
+  info "Installing agents-observe (multi-agent observability dashboard)..."
+  if command -v claude >/dev/null 2>&1; then
+    claude plugin install agents-observe 2>/dev/null && ok "agents-observe plugin installed" || {
+      info "Plugin install failed, trying npm global..."
+      npm install -g agents-observe 2>/dev/null && ok "agents-observe installed globally" || skip "agents-observe: manual setup needed — see https://github.com/simple10/agents-observe"
+    }
+  else
+    skip "agents-observe: Claude Code CLI not found"
+  fi
+}
+
+install_ccxray() {
+  info "Installing ccxray (Claude Code token/cost observability)..."
+  # ccxray is zero-install via npx — just verify it's accessible
+  if npx ccxray --version >/dev/null 2>&1; then
+    ok "ccxray available via npx"
+  else
+    info "ccxray will be available via: npx ccxray claude"
+    ok "ccxray: zero-install, run with 'npx ccxray claude' when needed"
+  fi
+
+  # Create a convenience wrapper
+  cat > "$AGENT_DIR/scripts/ccxray-session.sh" << 'WRAPPER'
+#!/bin/bash
+# Launch Claude Code through ccxray observability proxy
+# Usage: ./scripts/ccxray-session.sh [claude args...]
+exec npx ccxray claude "$@"
+WRAPPER
+  chmod +x "$AGENT_DIR/scripts/ccxray-session.sh"
+  ok "Created scripts/ccxray-session.sh convenience wrapper"
+}
+
+install_clawteam() {
+  info "Installing ClawTeam (git worktree swarm orchestrator)..."
+  if command -v pip3 >/dev/null 2>&1; then
+    pip3 install clawteam 2>/dev/null && ok "ClawTeam installed via pip" || {
+      info "pip install failed, trying git clone..."
+      if [ ! -d "$HOME/.clawteam" ]; then
+        git clone https://github.com/win4r/ClawTeam-OpenClaw.git "$HOME/.clawteam" 2>/dev/null && ok "ClawTeam cloned to ~/.clawteam" || skip "ClawTeam: manual setup needed — see https://github.com/win4r/ClawTeam-OpenClaw"
+      else
+        ok "ClawTeam already present at ~/.clawteam"
+      fi
+    }
+  else
+    skip "ClawTeam: pip3 not found"
+  fi
+}
+
+install_code_review_graph() {
+  info "Installing code-review-graph (Tree-sitter codebase knowledge graph)..."
+  if npx code-review-graph --version >/dev/null 2>&1; then
+    ok "code-review-graph available via npx"
+  else
+    npm install -g code-review-graph 2>/dev/null && ok "code-review-graph installed globally" || {
+      info "code-review-graph: available via npx when needed"
+      ok "Run with: npx code-review-graph"
+    }
+  fi
+}
+
+# ── Main ─────────────────────────────────────────────────────────────────────
+
+echo "=========================================="
+echo "  Maestro Dev Tooling Installer"
+echo "  Agent dir: $AGENT_DIR"
+echo "=========================================="
+echo ""
+
+TOOL="${2:-}"
+case "${1:-}" in
+  --all)
+    install_claude_pace
+    install_agents_observe
+    install_ccxray
+    install_clawteam
+    install_code_review_graph
+    ;;
+  --tool)
+    case "$TOOL" in
+      claude-pace)       install_claude_pace ;;
+      agents-observe)    install_agents_observe ;;
+      ccxray)            install_ccxray ;;
+      clawteam)          install_clawteam ;;
+      code-review-graph) install_code_review_graph ;;
+      *) echo "Unknown tool: $TOOL"; echo "Available: claude-pace, agents-observe, ccxray, clawteam, code-review-graph"; exit 1 ;;
+    esac
+    ;;
+  *)
+    echo "Usage: $0 [--all | --tool <name>]"
+    echo ""
+    echo "Available tools:"
+    echo "  claude-pace        — Rate limit status line tracker"
+    echo "  agents-observe     — Multi-agent observability dashboard"
+    echo "  ccxray             — Token/cost observability proxy"
+    echo "  clawteam           — Git worktree swarm orchestrator"
+    echo "  code-review-graph  — Tree-sitter codebase knowledge graph"
+    exit 0
+    ;;
+esac
+
+echo ""
+echo "Done. See docs/guides/dev-tooling.md for usage details."