@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/cli/lib/bundled-marketplace.json

@@ -0,0 +1,439 @@
+{
+  "name": "vellum-assistant",
+  "owner": {
+    "name": "Vellum",
+    "url": "https://github.com/vellum-ai/vellum-assistant"
+  },
+  "plugins": [
+    {
+      "name": "admin-copilot",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/admin-copilot",
+        "ref": "d30596aa50a1c702f5d74e05c45bd965d14e2107"
+      },
+      "description": "Proactive chief-of-staff: a morning digest, propose-then-confirm inbox triage, calendar prep, and a weekly competitor brief.",
+      "category": "productivity",
+      "homepage": "https://github.com/vellum-ai/admin-copilot",
+      "license": "MIT",
+      "icon": "🧑‍💼"
+    },
+    {
+      "name": "agent-wrapped",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/agent-wrapped",
+        "ref": "7e5e7971a38a90120cee9b1e393b733622e24d17"
+      },
+      "description": "Your agent's year in review: conversations, days together, memories formed, swear count, top topics, and the receipt (total tokens + LLM calls). Works with Vellum agents and Claude Code. Presents the stats as data in chat and publishes a shareable page at agent-wrapped.com.",
+      "category": "creative",
+      "license": "MIT",
+      "submittedBy": "marina",
+      "homepage": "https://agent-wrapped.com",
+      "icon": "🎁"
+    },
+    {
+      "name": "ai-hero-engineer-kit",
+      "source": {
+        "source": "github",
+        "repo": "marinatrajk/ai-hero-engineer-kit",
+        "ref": "18d33c62b15a3e2cc22dc070723fe3077749dcec"
+      },
+      "description": "Five engineering skills adapted from Matt Pocock's '5 Agent Skills I Use Every Day' — plans, PRDs, vertical-slice issues, TDD loop, and codebase deepening in one install.",
+      "category": "developer",
+      "homepage": "https://github.com/marinatrajk/ai-hero-engineer-kit",
+      "license": "MIT",
+      "icon": "🧰"
+    },
+    {
+      "name": "amex-perk-reminder",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/amex-perk-reminder",
+        "ref": "48649b3e9f5c37153c7a8b2887a740eadd7c0b1e"
+      },
+      "description": "Track every credit on the Amex cards you hold (Platinum, Gold, Business Platinum, Delta Gold/Platinum/Reserve) with status-aware reminders before any window closes.",
+      "category": "lifestyle",
+      "homepage": "https://github.com/AnitaKirkovska/amex-perk-reminder",
+      "license": "MIT",
+      "icon": "💳"
+    },
+    {
+      "name": "astrology-horoscope",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/astrology-horoscope",
+        "ref": "d226ce2e0a021e12cbf89ca7313f7c76a0bd8e39"
+      },
+      "description": "Western tropical natal chart and transit computation. Local ephemeris (astronomy-engine, no API keys) for planet positions, ascendant/midheaven, whole-sign houses, and aspects, plus a natal-reading skill that interprets the raw chart into a readable report.",
+      "category": "hobby",
+      "homepage": "https://github.com/vellum-ai/astrology-horoscope",
+      "license": "MIT",
+      "icon": "🔮"
+    },
+    {
+      "name": "caveman",
+      "source": {
+        "source": "github",
+        "repo": "JuliusBrussee/caveman",
+        "ref": "63a91ecadbf4c4719a4602a5abb00883f9966034"
+      },
+      "description": "Ultra-compressed communication mode that strips filler words to cut token usage.",
+      "category": "productivity",
+      "homepage": "https://github.com/JuliusBrussee/caveman",
+      "license": "MIT",
+      "icon": "🦴"
+    },
+    {
+      "name": "coffee-aficionado",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/coffee-aficionado",
+        "ref": "facd5a03979605edc894ea61e9a45f7b6a53214a"
+      },
+      "description": "Find great coffee beans and machines matched to your taste profile, budget, and kitchen. Persistent memory learns your preferences over time.",
+      "category": "lifestyle",
+      "homepage": "https://github.com/vellum-ai/coffee-aficionado",
+      "license": "MIT"
+    },
+    {
+      "name": "cofounder",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/cofounder",
+        "ref": "547adf1c0db0cbb32855ff0e4ef46c056248bdea"
+      },
+      "description": "AI co-founder that remembers your company context, challenges your thinking, and tracks your decisions.",
+      "category": "productivity",
+      "homepage": "https://github.com/vellum-ai/cofounder",
+      "license": "MIT",
+      "icon": "🤝"
+    },
+    {
+      "name": "cognee",
+      "source": {
+        "source": "github",
+        "repo": "topoteretes/cognee-integrations",
+        "path": "integrations/vellum-assistant",
+        "ref": "d79bd9a216c9f6d88d27694cc0b42a18b63dba88"
+      },
+      "description": "Cognee knowledge graph memory for Vellum Assistant: session-aware storage, auto-routing recall, and persistent learning across sessions. Supports local mode and Cognee Cloud.",
+      "category": "memory",
+      "homepage": "https://github.com/topoteretes/cognee-integrations/tree/main/integrations/vellum-assistant",
+      "icon": "🕸️"
+    },
+    {
+      "name": "dynamic-notch",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/dynamic-notch",
+        "ref": "9729c3685d60d00d1de73a183b03122b9fa1f8f4"
+      },
+      "description": "Put your Vellum assistant inside your MacBook's notch: click to chat, hold Ctrl+Option to talk, and get a floating task bulb while it works, with live-streamed replies and per-sentence voice.",
+      "category": "interface",
+      "homepage": "https://github.com/AnitaKirkovska/dynamic-notch",
+      "license": "MIT",
+      "icon": "💻"
+    },
+    {
+      "name": "family-briefing",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/family-briefing",
+        "ref": "145f341db7d06ffa81e2052033f187679b8bda4d"
+      },
+      "description": "Daily morning briefing for parents: merges family calendars, triages school emails, and detects scheduling conflicts.",
+      "category": "productivity",
+      "homepage": "https://github.com/AnitaKirkovska/family-briefing",
+      "license": "MIT",
+      "icon": "👨‍👩‍👧‍👦"
+    },
+    {
+      "name": "fitness-companion",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/fitness-companion",
+        "ref": "fe4e02e2b514207a37f2a7e9f9c500ec8a73edcb"
+      },
+      "description": "Fitness and nutrition companion. Logs meals, workouts, and weight; looks up nutrition data from OpenFoodFacts; calculates macro targets; and injects daily fitness context into every conversation.",
+      "category": "health",
+      "homepage": "https://github.com/vellum-ai/fitness-companion",
+      "license": "MIT",
+      "icon": "💪"
+    },
+    {
+      "name": "git-workflow",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/git-workflow",
+        "ref": "829407aa93b63b8bca4717624533f2fc7f702a5d"
+      },
+      "description": "Git workflow tools and multi-perspective code review: branch management, push, stash, PR creation/review/merge/checkout, diffs, logs, changelog generation, and parallel subagent code review with confidence scoring.",
+      "category": "developer",
+      "homepage": "https://github.com/vellum-ai/git-workflow",
+      "license": "MIT",
+      "icon": "🔀"
+    },
+    {
+      "name": "google-drive-search",
+      "source": {
+        "source": "github",
+        "repo": "ZeebBoyBlue/google-drive-search",
+        "ref": "ddd5013477cc1ec8d1fb174db6b599dbfe1cca21"
+      },
+      "description": "Local full-text search across your Google Drive. Indexes file metadata and document content into SQLite FTS5 for instant, private search.",
+      "category": "productivity",
+      "homepage": "https://github.com/ZeebBoyBlue/google-drive-search",
+      "license": "Apache-2.0",
+      "icon": "🔍"
+    },
+    {
+      "name": "influencer-marketing",
+      "source": {
+        "source": "github",
+        "repo": "ZeebBoyBlue/influencer",
+        "ref": "8629b0dcfdacf62246122af2dcd7320baa6db04e"
+      },
+      "description": "Find and research influencers on Instagram, TikTok, and X/Twitter. Includes a strategy builder that walks from campaign brief to research criteria, a research skill that discovers real profiles via browser automation, scores candidates, and exports ranked shortlists, and a dashboard skill that turns the shortlist into an interactive outreach tracker.",
+      "category": "marketing",
+      "homepage": "https://github.com/ZeebBoyBlue/influencer",
+      "license": "MIT",
+      "icon": "📣"
+    },
+    {
+      "name": "kitchen-companion",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/kitchen-companion",
+        "ref": "b6ebdda6992dfa1fd2186a600a642f538fb64584"
+      },
+      "description": "Full kitchen companion. Scan your fridge with a photo to stock a pantry inventory and get 3 makeable-now recipes, get alerts before food expires, clip recipes from any URL into a clean format, and generate meal plans with grocery lists from what you actually have.",
+      "category": "lifestyle",
+      "homepage": "https://github.com/vellum-ai/kitchen-companion",
+      "license": "MIT",
+      "icon": "🍳"
+    },
+    {
+      "name": "level-up",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/level-up",
+        "ref": "d3cbb50f8aba1f8320cd2d59ea3a85d0a4e9210b"
+      },
+      "description": "Surfaces a first-class \"Level Up\" diff card whenever the assistant edits its own skills or plugins, so you can see how it improved itself after the fact.",
+      "category": "developer",
+      "homepage": "https://github.com/vellum-ai/level-up",
+      "license": "MIT",
+      "icon": "🆙"
+    },
+    {
+      "name": "marketing-expert",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/marketing-expert",
+        "ref": "6a85ee33e184c2be56ed63cd5681d1287a941eff"
+      },
+      "description": "Acts as a full-stack marketing expert for any business (B2B or B2C): an on-demand persona plus playbook skills (positioning, demand planning, launches, content & copywriting, brand voice, email sequences, SEO & GEO, competitive teardown, board reporting) and deterministic funnel/positioning/GTM/competitive tools.",
+      "category": "marketing",
+      "homepage": "https://github.com/vellum-ai/marketing-expert",
+      "license": "MIT",
+      "icon": "📈"
+    },
+    {
+      "name": "model-router",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/model-router",
+        "ref": "605100d27b5333b243ada5a29fcb324e2217d336"
+      },
+      "description": "Routes each user-facing message to one of your workspace's inference profiles, so model selection can vary per call instead of staying pinned to a single profile.",
+      "category": "productivity",
+      "homepage": "https://github.com/AnitaKirkovska/model-router",
+      "license": "MIT",
+      "icon": "🚦"
+    },
+    {
+      "name": "motion-design",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/motion-design",
+        "ref": "9cdc798c26e0141dcdf6887d7707559c38bfe00e"
+      },
+      "description": "Teaches the assistant to build polished UI animations with Motion (motion.dev) for React: animated product mockups, chat replays, typing effects, and staggered reveals, with a complete animated chat example included.",
+      "category": "creative",
+      "homepage": "https://github.com/vellum-ai/motion-design",
+      "license": "MIT",
+      "icon": "🎬"
+    },
+    {
+      "name": "originkit",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/originkit",
+        "ref": "9aa260c2561ad9e765832dc342e9bbb5138858a4"
+      },
+      "description": "Browse and import animated UI components from Originkit, a free library of 50 animated components. Browse by category or search term without an API key; fetch component source code (React, Next.js, Vite, Framer) with a free key from originkit.dev.",
+      "category": "productivity",
+      "homepage": "https://github.com/vellum-ai/originkit",
+      "license": "MIT",
+      "icon": "🧱"
+    },
+    {
+      "name": "personal-finance",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/personal-finance",
+        "ref": "f8f9bfba3d86c943001da894b920e7e867507dd4"
+      },
+      "description": "Track expenses, income, recurring bills, and savings funds from your assistant. Multi-currency, receipt OCR, Plaid bank sync, and financial summaries. All data stored locally in SQLite.",
+      "category": "productivity",
+      "homepage": "https://github.com/AnitaKirkovska/personal-finance",
+      "license": "MIT",
+      "icon": "💰"
+    },
+    {
+      "name": "plant-doctor",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/plant-doctor",
+        "ref": "1115ac07a5b7f731600f037b743e011a84bd0597"
+      },
+      "description": "Diagnose plants from photos. Identifies the species, assesses health with visible evidence, and returns a care plan. Named plants get a persistent checkup history so you can track whether they are improving.",
+      "category": "lifestyle",
+      "homepage": "https://github.com/vellum-ai/plant-doctor",
+      "license": "MIT",
+      "icon": "🪴"
+    },
+    {
+      "name": "polyglot",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/polyglot",
+        "ref": "ab607b7c60b64b0ac5c6bf01609840a004cfd002"
+      },
+      "description": "Ambient language acquisition through your assistant. Three graduated modes (practice, ambient, immersive) weave a target language into your real conversations, with SM-2 spaced repetition, error-pattern tracking, and CEFR level history.",
+      "category": "education",
+      "homepage": "https://github.com/vellum-ai/polyglot",
+      "license": "MIT",
+      "icon": "🗣️"
+    },
+    {
+      "name": "proactive-slacks",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/proactive-slacks",
+        "ref": "a5dd35699455ae7a2db3d2243511a8c7edc49aea"
+      },
+      "description": "Let your assistant reach you on Slack on purpose. Route notifications by topic to the right channel at the right volume, with heartbeat-based change detection so it only pings when something actually changed.",
+      "category": "productivity",
+      "homepage": "https://github.com/AnitaKirkovska/proactive-slacks",
+      "license": "MIT",
+      "icon": "💬"
+    },
+    {
+      "name": "reading-pal",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/reading-pal",
+        "ref": "5219474719e67db7ea64848f6bd2a0b7312e4f27"
+      },
+      "description": "Your reading life in one plugin. Track your TBR pile, get guilt-tripped about your backlog, find your next read, and sync from Goodreads.",
+      "category": "hobby",
+      "homepage": "https://github.com/vellum-ai/reading-pal",
+      "license": "MIT",
+      "icon": "📚"
+    },
+    {
+      "name": "simple-memory",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/simple-memory",
+        "ref": "ed09a4c01bf18e4ac8859faee94cb65c7cbd1ca3"
+      },
+      "description": "Reference memory plugin that exercises the full plugin API with low-cost variants of Vellum's memory defaults.",
+      "category": "memory",
+      "homepage": "https://github.com/vellum-ai/simple-memory",
+      "license": "MIT",
+      "icon": "🧠"
+    },
+    {
+      "name": "smb-inbox-brief",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/smb-inbox-brief",
+        "ref": "8e298bd8ded5e0e16c5160edcd547eda1e4d222f"
+      },
+      "description": "Find urgent replies, overdue invoices, quotes, and customer follow-ups before they slip. Scans email, logs business items, delivers urgency-ranked daily briefs.",
+      "category": "productivity",
+      "homepage": "https://github.com/AnitaKirkovska/smb-inbox-brief",
+      "license": "MIT",
+      "icon": "📧"
+    },
+    {
+      "name": "tennis-companion",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/tennis-companion",
+        "ref": "1c6d2bd448ee7b5285d37cfee4e0e413522746d1"
+      },
+      "description": "Tennis journal, drill sessions, court finder, and progress tracking. Log matches with opponent tendencies, generate 30-minute practice sessions with progressions, find nearby courts via OpenStreetMap, and track win rate by surface and conditions.",
+      "category": "health",
+      "homepage": "https://github.com/vellum-ai/tennis-companion",
+      "license": "MIT",
+      "icon": "🎾"
+    },
+    {
+      "name": "travel-planner",
+      "source": {
+        "source": "github",
+        "repo": "AnitaKirkovska/travel-planner",
+        "ref": "10c2c4878b017997cb6766b8204b9803c56bc6cf"
+      },
+      "description": "A travel EA for your assistant. Remembers how you travel (carrier, miles, hotel budget, card benefits), keeps per-trip records, watches Gmail for booking changes, syncs your calendar, and emails an EA-style trip brief 48 hours before departure.",
+      "category": "lifestyle",
+      "homepage": "https://github.com/AnitaKirkovska/travel-planner",
+      "license": "MIT",
+      "icon": "✈️"
+    },
+    {
+      "name": "vellum-client-qa",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/vellum-client-qa",
+        "ref": "4f559d865eaa04b68285f8e4fae4a05fc18fe88f"
+      },
+      "description": "Cross-platform QA rig for vellum-assistant clients: mock the platform backend, boot the real chat UI, and verify feature branches in headless Chromium (web), an iOS simulator, or Electron with screenshot and video proof.",
+      "category": "developer",
+      "homepage": "https://github.com/vellum-ai/vellum-client-qa",
+      "license": "MIT",
+      "icon": "🧪"
+    },
+    {
+      "name": "virlo",
+      "source": {
+        "source": "github",
+        "repo": "Virlo-AI/virlo-integrations",
+        "path": "integrations/vellum",
+        "ref": "e398cfd8a48316b9378e08efe4b42ad3dc42197e"
+      },
+      "description": "Real-time short-form video intelligence across TikTok, YouTube Shorts, and Instagram Reels, powered by Virlo Content Research Agents.",
+      "category": "marketing",
+      "homepage": "https://github.com/Virlo-AI/virlo-integrations/tree/main/integrations/vellum",
+      "license": "MIT",
+      "icon": "📱"
+    },
+    {
+      "name": "writing-coach",
+      "source": {
+        "source": "github",
+        "repo": "vellum-ai/writing-coach",
+        "ref": "9cb2289343fed2fd6ad8b0bb5db07616d1c8181c"
+      },
+      "description": "A writing coach in your pocket. Daily prompts that escalate with your streak, savage-but-constructive draft roasts, query letter critiques, and a word count enforcer that guilt-trips you when you skip.",
+      "category": "hobby",
+      "homepage": "https://github.com/vellum-ai/writing-coach",
+      "license": "MIT",
+      "icon": "✍️"
+    }
+  ]
+}

package/src/cli/lib/cli-command-help.ts

@@ -1,4 +1,4 @@
-import type { Command } from "commander";
+import { type Command, Option } from "commander";
 
 /**
  * Fully declarative description of a top-level `assistant` CLI command and its
@@ -9,7 +9,21 @@ import type { Command } from "commander";
  */
 export interface CliCommandHelp {
   name: string;
+  /**
+   * Positional-argument spec appended to the name at registration, e.g.
+   * `"<command>"`. Use {@link commandSpec} to build the Commander registration
+   * string; `name` stays the bare command name so consumers (dedup, slugs,
+   * rendering) never parse argument syntax out of it.
+   */
+  args?: string;
   description: string;
+  /**
+   * Positional arguments that carry their own description, applied via
+   * Commander's `argument(name, description)` (rendered in the generated
+   * `Arguments:` help section). Use `args` instead when the positional needs
+   * no description.
+   */
+  arguments?: CliArgumentHelp[];
   /** Options declared directly on the top-level command. */
   options?: CliOptionHelp[];
   /** Extra help appended after the option list (`addHelpText("after", …)`). */
@@ -19,10 +33,29 @@ export interface CliCommandHelp {
 
 export interface CliSubcommandHelp {
   name: string;
+  /** Positional-argument spec, e.g. `"<path>"` — see {@link CliCommandHelp.args}. */
+  args?: string;
   description: string;
+  /**
+   * Positional arguments that carry their own description, applied via
+   * Commander's `argument(name, description)` (rendered in the generated
+   * `Arguments:` help section). Use `args` instead when the positional needs
+   * no description.
+   */
+  arguments?: CliArgumentHelp[];
   options?: CliOptionHelp[];
   /** Extra help appended after the option list (`addHelpText("after", …)`). */
   helpText?: string;
+  /** When true, this subcommand runs when the parent is invoked without one. */
+  isDefault?: boolean;
+  /** Nested subcommand groups (e.g. `avatar character update`). */
+  subcommands?: CliSubcommandHelp[];
+}
+
+export interface CliArgumentHelp {
+  /** Commander argument spec, e.g. `"<channel>"` or `"[value]"`. */
+  name: string;
+  description: string;
 }
 
 export interface CliOptionHelp {
@@ -32,15 +65,32 @@ export interface CliOptionHelp {
   /** When true, applied via `requiredOption` (missing → error) rather than `option`. */
   required?: boolean;
   /** Default value passed to `option(flags, description, defaultValue)`. */
-  defaultValue?: string;
+  defaultValue?: string | number | boolean;
+  /** Allowed values, applied via Commander's `Option.choices()` (invalid → error). */
+  choices?: readonly string[];
 }
 
 function applyOptions(command: Command, options?: CliOptionHelp[]): void {
   for (const option of options ?? []) {
-    if (option.required) {
+    if (option.choices) {
+      const built = new Option(option.flags, option.description).choices([
+        ...option.choices,
+      ]);
+      if (option.required) {
+        built.makeOptionMandatory(true);
+      }
+      if (option.defaultValue !== undefined) {
+        built.default(option.defaultValue);
+      }
+      command.addOption(built);
+    } else if (option.required) {
       command.requiredOption(option.flags, option.description);
     } else if (option.defaultValue !== undefined) {
-      command.option(option.flags, option.description, option.defaultValue);
+      command.addOption(
+        new Option(option.flags, option.description).default(
+          option.defaultValue,
+        ),
+      );
     } else {
       command.option(option.flags, option.description);
     }
@@ -49,25 +99,48 @@ function applyOptions(command: Command, options?: CliOptionHelp[]): void {
 
 /**
  * Configure a Commander command from its declarative {@link CliCommandHelp}:
- * top-level options, appended help text, and subcommands (with their options).
- * Does not set the top-level name/description — `registerCommand` owns those —
- * and does not attach action handlers; the command module attaches those to the
- * command or its subcommands.
+ * top-level options, appended help text, and subcommands (with their options,
+ * recursively). Does not set the top-level name/description — `registerCommand`
+ * owns those — and does not attach action handlers; the command module attaches
+ * those to the command or its subcommands.
  */
 export function applyCommandHelp(command: Command, help: CliCommandHelp): void {
+  for (const argument of help.arguments ?? []) {
+    command.argument(argument.name, argument.description);
+  }
   applyOptions(command, help.options);
   if (help.helpText) {
     command.addHelpText("after", help.helpText);
   }
-  for (const sub of help.subcommands ?? []) {
-    const child = command.command(sub.name).description(sub.description);
+  applySubcommands(command, help.subcommands);
+}
+
+function applySubcommands(parent: Command, subs?: CliSubcommandHelp[]): void {
+  for (const sub of subs ?? []) {
+    const child = parent
+      .command(commandSpec(sub), { isDefault: sub.isDefault ?? false })
+      .description(sub.description);
+    for (const argument of sub.arguments ?? []) {
+      child.argument(argument.name, argument.description);
+    }
     applyOptions(child, sub.options);
     if (sub.helpText) {
       child.addHelpText("after", sub.helpText);
     }
+    applySubcommands(child, sub.subcommands);
   }
 }
 
+/**
+ * Commander registration spec for a command: the bare name plus its
+ * positional-argument spec, if any (`"bash <command>"`, `"add <path>"`).
+ */
+export function commandSpec(
+  help: Pick<CliCommandHelp, "name" | "args">,
+): string {
+  return help.args ? `${help.name} ${help.args}` : help.name;
+}
+
 /** Return a subcommand by name, throwing if absent. */
 export function subcommand(parent: Command, name: string): Command {
   const found = parent.commands.find((c) => c.name() === name);

package/src/cli/lib/global-json-option.ts

@@ -0,0 +1,41 @@
+import type { Command } from "commander";
+
+const JSON_FLAG = "--json";
+
+/**
+ * Register a `--json` option on every leaf command in the tree that does not
+ * already declare one.
+ *
+ * Commander only recognizes an option at the position of the command it is
+ * attached to, so a single option on the root program would still reject
+ * `assistant status --json` with "unknown option '--json'". Attaching `--json`
+ * to each leaf command makes the flag accepted everywhere it is actually
+ * invoked, which is what callers (and agents) expect when they append `--json`
+ * to a command.
+ *
+ * Only **leaf** commands (those with no subcommands) get the option. Commander
+ * consumes a recognized option at the *outermost* command that declares it,
+ * even when the flag appears after the subcommand name — so putting `--json`
+ * on a group command like `clients` would swallow `clients list --json` before
+ * the `list` action ever sees it (`opts.json` would be undefined). Attaching it
+ * only to leaves keeps the flag bound to the command that reads it.
+ *
+ * Commands that render output through `writeOutput`/`shouldOutputJson` (which
+ * walk the parent chain) honor the flag automatically; leaves that declare
+ * their own `--json` are left untouched so their description and behavior win.
+ */
+export function registerGlobalJsonOption(program: Command): void {
+  const walk = (cmd: Command): void => {
+    const isLeaf = cmd.commands.length === 0;
+    const alreadyDeclared = cmd.options.some((opt) => opt.long === JSON_FLAG);
+    if (isLeaf && !alreadyDeclared) {
+      cmd.option(JSON_FLAG, "Output machine-readable JSON");
+    }
+    for (const child of cmd.commands) {
+      walk(child);
+    }
+  };
+  for (const child of program.commands) {
+    walk(child);
+  }
+}