capyai 0.3.1 → 0.3.3

package/README.md

@@ -1,13 +1,13 @@
-# capy-cli
+# capyai
 
-Agent orchestrator with quality gates for [Capy.ai](https://capy.ai). Zero dependencies.
+Agent orchestrator with quality gates for [Capy.ai](https://capy.ai).
 
-Works with Claude Code, Codex, OpenClaw, or any AI agent that can run shell commands.
+Works with Claude Code, Codex, OpenClaw, Poke, or any AI agent that can run shell commands.
 
 ## Install
 
 ```bash
-npm i -g capy-cli
+npm i -g capyai
 capy init
 ```
 
@@ -18,6 +18,8 @@ export CAPY_API_KEY=capy_...
 export CAPY_PROJECT_ID=...
 ```
 
+Requires [Bun](https://bun.sh) runtime and GitHub CLI (`gh`) for quality gate checks.
+
 ## Usage
 
 ```bash
@@ -25,6 +27,9 @@ export CAPY_PROJECT_ID=...
 capy captain "Implement feature X. Files: src/foo.ts. Tests required."
 capy build "Fix typo in README"
 
+# Wait for completion (blocks until done)
+capy wait <thread-id> --timeout=600
+
 # Monitor
 capy status
 capy watch <thread-id>
@@ -37,6 +42,38 @@ capy retry <task-id> --fix="fix the failing test"
 
 Every command supports `--json` for machine-readable output.
 
+## For Agents
+
+The core orchestration loop:
+
+```bash
+capy captain "precise prompt" --json        # start work
+capy wait <thread-id> --timeout=600 --json  # block until done
+capy review <task-id> --json                # check quality gates
+capy approve <task-id> --json               # approve if gates pass
+capy retry <task-id> --fix="..." --json     # or retry with context
+```
+
+### MCP Server
+
+For agents that prefer MCP (Cursor, some Codex configs):
+
+```json
+{
+  "mcpServers": {
+    "capy": {
+      "command": "capy-mcp"
+    }
+  }
+}
+```
+
+### Skills.sh
+
+```bash
+npx skills add yazcaleb/capy-cli
+```
+
 ## Quality Gates
 
 `capy review` checks pass/fail gates:
@@ -51,14 +88,7 @@ Every command supports `--json` for machine-readable output.
 | `threads` | No unresolved review threads |
 | `tests` | Diff includes test files |
 
-Configure which gates run via `capy config quality.reviewProvider greptile|capy|both|none`.
-
-## For Agents
-
-```bash
-capy review TASK-1 --json   # parse quality.pass boolean
-capy status --json           # full state dump
-```
+Configure via `capy config quality.reviewProvider greptile|capy|both|none`.
 
 ## Config
 
@@ -70,10 +100,6 @@ capy config notifyCommand "notify-send {text}"
 
 Env vars: `CAPY_API_KEY`, `CAPY_PROJECT_ID`, `CAPY_SERVER`, `CAPY_ENV_FILE`, `GREPTILE_API_KEY`.
 
-## Requirements
-
-[Bun](https://bun.sh) runtime. GitHub CLI (`gh`) for quality gate checks.
-
 ## License
 
 MIT

package/bin/capy-mcp.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/mcp.js";

package/bin/capy.ts

@@ -33,6 +33,7 @@ const main = defineCommand({
     watch:       () => import("../src/commands/monitoring.js").then(m => m.watch),
     unwatch:     () => import("../src/commands/monitoring.js").then(m => m.unwatch),
     watches:     () => import("../src/commands/monitoring.js").then(m => m.watches),
+    wait:        () => import("../src/commands/monitoring.js").then(m => m.wait),
     _poll:       () => import("../src/commands/monitoring.js").then(m => m._poll),
     init:        () => import("../src/commands/setup.js").then(m => m.init),
     config:      () => import("../src/commands/setup.js").then(m => m.config),

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "capyai",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Unofficial Capy.ai CLI for agent orchestration with quality gates",
   "bin": {
-    "capy": "./bin/capy.js"
+    "capy": "./bin/capy.js",
+    "capy-mcp": "./bin/capy-mcp.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18"
@@ -22,7 +24,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/PlawIO/capy-cli"
+    "url": "https://github.com/yazcaleb/capy-cli"
   },
   "keywords": [
     "capy",
@@ -33,6 +35,8 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.2.0",
-    "citty": "^0.2.2"
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "citty": "^0.2.2",
+    "zod": "^3.24.0"
   }
 }

package/skills/capy/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: capy
+description: Orchestrate Capy.ai coding agents with quality gates. Delegate coding work, wait for completion, review quality, approve or retry.
+metadata:
+  author: yazcaleb
+  version: "0.3.2"
+---
+
+# capy
+
+Orchestrate Capy.ai coding agents. Start tasks, wait for them, enforce quality gates, approve or retry. Works with any AI agent (Claude Code, Codex, OpenClaw, Poke).
+
+## Install
+
+```bash
+npm i -g capyai
+capy init
+```
+
+Or set env vars directly:
+```bash
+export CAPY_API_KEY=capy_...
+export CAPY_PROJECT_ID=...
+```
+
+## Agent workflow
+
+The core loop for any agent:
+
+```bash
+# 1. Start work
+capy captain "Implement feature X. Files: src/foo.ts. Tests required." --json
+
+# 2. Wait for completion (blocks until done)
+capy wait <thread-id> --timeout=600 --json
+
+# 3. Check quality gates
+capy review <task-id> --json
+# Parse quality.pass boolean
+
+# 4a. If pass: approve
+capy approve <task-id> --json
+
+# 4b. If fail: retry with context
+capy retry <task-id> --fix="fix the failing CI check" --json
+# Go back to step 2
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `capy captain "<prompt>"` | Start Captain thread (primary agent) |
+| `capy build "<prompt>"` | Start Build agent (isolated, small tasks) |
+| `capy wait <id>` | Block until task/thread reaches terminal state |
+| `capy review <id>` | Run quality gates (pr_exists, ci, greptile, threads, tests) |
+| `capy approve <id>` | Approve if all gates pass |
+| `capy retry <id> --fix="..."` | Retry with failure context from previous attempt |
+| `capy status` | Dashboard of all threads and tasks |
+| `capy list [status]` | List tasks, optionally filtered |
+| `capy get <id>` | Task or thread details |
+| `capy diff <id>` | View diff from task |
+| `capy pr <id>` | Create PR for task |
+| `capy threads list` | List Captain threads |
+| `capy threads get <id>` | Thread details |
+| `capy threads msg <id> <text>` | Message a thread |
+| `capy threads stop <id>` | Stop a thread |
+| `capy threads messages <id>` | View thread messages |
+
+All commands support `--json` for machine-readable output.
+
+## Quality gates
+
+`capy review` checks pass/fail gates:
+
+- **pr_exists** — PR was created
+- **pr_open** — PR is OPEN or MERGED
+- **ci** — CI checks passing
+- **greptile** — No unaddressed Greptile issues
+- **threads** — No unresolved GitHub review threads
+- **tests** — Diff includes test files
+
+Configure which run via `capy config quality.reviewProvider greptile|capy|both|none`.
+
+## JSON output
+
+Every command returns structured JSON with `--json`. Errors return `{ "error": { "code": "...", "message": "..." } }`.
+
+Key fields for agents:
+- `capy review --json` → `quality.pass` (boolean), `quality.gates` (array)
+- `capy wait --json` → full task/thread object on completion, `error.code: "timeout"` on timeout
+- `capy retry --json` → `newThread` (thread ID to wait on)
+
+## Prompting tips
+
+Bad: "Fix the CI issue"
+Good: "Fix CI for crypto-trading pack. The changeset file is missing. Add a changeset entry for @veto/crypto-trading. Run changeset validation. Reference: PLW-201."
+
+Specific files, specific functions, specific acceptance criteria.
+
+## Triggers
+
+Keywords: capy, captain, build agent, quality gates, delegate coding, orchestrate agents, send to capy, approve task, retry task

package/src/api.ts

@@ -1,6 +1,16 @@
 import * as config from "./config.js";
+import { IS_JSON } from "./output.js";
 import type { Task, Thread, ThreadMessage, DiffData, Model, ListResponse, PullRequestRef } from "./types.js";
 
+function fail(code: string, message: string): never {
+  if (IS_JSON) {
+    console.log(JSON.stringify({ error: { code, message } }));
+  } else {
+    console.error(`capy: ${message}`);
+  }
+  process.exit(1);
+}
+
 async function rawRequest(apiKey: string, server: string, method: string, path: string, body?: unknown): Promise<any> {
   const url = `${server}${path}`;
   const headers: Record<string, string> = {
@@ -17,29 +27,25 @@ async function rawRequest(apiKey: string, server: string, method: string, path:
   try {
     res = await fetch(url, init);
   } catch (e: unknown) {
-    console.error(`capy: request failed — ${(e as Error).message}`);
-    process.exit(1);
+    fail("network_error", `request failed — ${(e as Error).message}`);
   }
 
   const text = await res.text();
   try {
     const data = JSON.parse(text);
     if (data.error) {
-      console.error(`capy: API error — ${data.error.message || data.error.code}`);
-      process.exit(1);
+      fail("api_error", `API error — ${data.error.message || data.error.code}`);
     }
     return data;
   } catch {
-    console.error("capy: bad API response:", text.slice(0, 200));
-    process.exit(1);
+    fail("bad_response", `bad API response: ${text.slice(0, 200)}`);
   }
 }
 
 async function request(method: string, path: string, body?: unknown): Promise<any> {
   const cfg = config.load();
   if (!cfg.apiKey) {
-    console.error("capy: API key not configured. Run: capy init");
-    process.exit(1);
+    fail("no_api_key", "API key not configured. Run: capy init");
   }
   return rawRequest(cfg.apiKey, cfg.server, method, path, body);
 }

package/src/commands/monitoring.ts

@@ -56,6 +56,45 @@ export const watches = defineCommand({
   },
 });
 
+export const wait = defineCommand({
+  meta: { name: "wait", description: "Block until task/thread reaches terminal state" },
+  args: {
+    id: { type: "positional", description: "Task or thread ID", required: true },
+    timeout: { type: "string", description: "Timeout in seconds", default: "300" },
+    interval: { type: "string", description: "Poll interval in seconds", default: "10" },
+    ...jsonArg,
+  },
+  async run({ args }) {
+    const api = await import("../api.js");
+    const fmt = await import("../output.js");
+
+    const timeoutMs = Math.max(10, parseInt(args.timeout) || 300) * 1000;
+    const intervalMs = Math.max(5, Math.min(parseInt(args.interval) || 10, 60)) * 1000;
+    const isThread = args.id.length > 20 || (args.id.length > 10 && !args.id.match(/^[A-Z]+-\d+$/));
+    const terminalTask = new Set(["needs_review", "archived", "completed", "failed"]);
+    const terminalThread = new Set(["idle", "archived", "completed"]);
+    const terminal = isThread ? terminalThread : terminalTask;
+
+    const start = Date.now();
+    if (!args.json) process.stderr.write(`Waiting for ${args.id} (${isThread ? "thread" : "task"})...`);
+
+    while (Date.now() - start < timeoutMs) {
+      const data = isThread ? await api.getThread(args.id) : await api.getTask(args.id);
+      if (terminal.has(data.status)) {
+        if (args.json) { fmt.out(data); return; }
+        console.log(`\n${isThread ? "Thread" : "Task"} ${data.status}.`);
+        return;
+      }
+      if (!args.json) process.stderr.write(".");
+      await new Promise(r => setTimeout(r, intervalMs));
+    }
+
+    if (args.json) { fmt.out({ error: { code: "timeout", message: `Timed out after ${args.timeout}s` } }); process.exit(1); }
+    console.error(`\ncapy: timed out after ${args.timeout}s`);
+    process.exit(1);
+  },
+});
+
 export const _poll = defineCommand({
   meta: { name: "_poll", description: "Internal cron poll", hidden: true },
   args: {

package/src/commands/quality.ts

@@ -21,7 +21,7 @@ export const review = defineCommand({
     const reviewProvider = cfg.quality?.reviewProvider || "greptile";
 
     if (!task.pullRequest?.number) {
-      if (args.json) { fmt.out({ error: "no_pr", task: task.identifier }); return; }
+      if (args.json) { fmt.out({ error: { code: "no_pr", message: `${task.identifier}: No PR` }, task: task.identifier }); return; }
       log.warn(`${task.identifier}: No PR. Create one first: capy pr ${task.identifier}`);
       return;
     }
@@ -115,17 +115,20 @@ export const reReview = defineCommand({
     const reviewProvider = cfg.quality?.reviewProvider || "greptile";
 
     if (reviewProvider !== "greptile" && reviewProvider !== "both") {
+      if (args.json) { fmt.out({ error: { code: "wrong_provider", message: `re-review requires Greptile provider (current: ${reviewProvider})` } }); process.exit(1); }
       console.error(`capy: re-review requires Greptile provider (current: ${reviewProvider})`);
       process.exit(1);
     }
 
     if (!cfg.greptileApiKey && !process.env.GREPTILE_API_KEY) {
+      if (args.json) { fmt.out({ error: { code: "no_greptile_key", message: "GREPTILE_API_KEY not set" } }); process.exit(1); }
       console.error("capy: GREPTILE_API_KEY not set. Run: capy config greptileApiKey <key>");
       process.exit(1);
     }
 
     const task = await api.getTask(args.id);
     if (!task.pullRequest?.number) {
+      if (args.json) { fmt.out({ error: { code: "no_pr", message: `${task.identifier}: No PR` } }); process.exit(1); }
       console.error(`${task.identifier}: No PR. Create one first: capy pr ${task.identifier}`);
       process.exit(1);
     }
@@ -176,7 +179,16 @@ export const approve = defineCommand({
     const cfg = config.load();
     const q = await quality.check(task);
 
-    if (args.json) { fmt.out({ task: task.identifier, quality: q, approved: q.pass || args.force }); return; }
+    const approved = q.pass || !!args.force;
+
+    if (args.json) {
+      if (!approved) {
+        fmt.out({ task: task.identifier, quality: q, approved: false, error: { code: "gates_failed", message: q.summary } });
+        process.exit(1);
+      }
+      fmt.out({ task: task.identifier, quality: q, approved: true });
+      return;
+    }
 
     log.info(`${task.identifier} \u2014 ${task.title}\n`);
     q.gates.forEach(g => {
@@ -187,7 +199,7 @@ export const approve = defineCommand({
     if (q.pass) log.success(q.summary);
     else log.warn(q.summary);
 
-    if (!q.pass && !args.force) {
+    if (!approved) {
       log.error("Blocked. Fix the failing gates or use --force to override.");
       process.exit(1);
     }
@@ -197,12 +209,13 @@ export const approve = defineCommand({
       const approveCmd = cfg.approveCommand;
       if (approveCmd) {
         try {
-          const { execSync } = await import("node:child_process");
-          const expanded = approveCmd
+          const { execFileSync } = await import("node:child_process");
+          const parts = approveCmd
             .replace("{task}", task.identifier || task.id)
             .replace("{title}", task.title || "")
-            .replace("{pr}", String(task.pullRequest?.number || ""));
-          execSync(expanded, { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+            .replace("{pr}", String(task.pullRequest?.number || ""))
+            .split(/\s+/);
+          execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
           log.info("Post-approve hook ran.");
         } catch {}
       }
@@ -294,18 +307,19 @@ export const retry = defineCommand({
     retryPrompt += `Fix the issues from the previous attempt. Do not repeat the same mistakes.\n`;
     retryPrompt += `Include tests. Run tests before completing. Verify CI will pass.\n`;
 
-    if (args.json) {
-      fmt.out({ originalTask: task.identifier, retryPrompt, context });
-      return;
-    }
-
     if (task.status === "in_progress") {
       await api.stopTask(args.id, "Retrying with fixes");
-      log.info(`Stopped ${task.identifier}.`);
+      if (!args.json) log.info(`Stopped ${task.identifier}.`);
     }
 
     const model = resolveModel(args) || cfg.defaultModel;
     const data = await api.createThread(retryPrompt, model);
+
+    if (args.json) {
+      fmt.out({ originalTask: task.identifier, newThread: data.id, model, contextLines: context.split("\n").length });
+      return;
+    }
+
     log.success(`Retry started: https://capy.ai/project/${cfg.projectId}/captain/${data.id}`);
     log.info(`Thread: ${data.id}  Model: ${model}`);
     log.info(`Context included: ${context.split("\n").length} lines from previous attempt.`);

package/src/commands/setup.ts

@@ -117,6 +117,7 @@ export const config = defineCommand({
     if (!args.value) {
       const val = configMod.get(args.key);
       if (val === undefined) {
+        if (args.json) { fmt.out({ error: { code: "unknown_key", message: `unknown config key "${args.key}"` } }); process.exit(1); }
         console.error(`capy: unknown config key "${args.key}"`);
         process.exit(1);
       }
@@ -173,6 +174,7 @@ export const tools = defineCommand({
       "re-review":{ args: "<id>",                  desc: "Trigger Greptile re-review" },
       approve:    { args: "<id>",                  desc: "Approve if gates pass" },
       retry:      { args: "<id> [--fix=...]",      desc: "Retry with failure context" },
+      wait:       { args: "<id>",                  desc: "Block until done" },
       watch:      { args: "<id>",                  desc: "Poll + notify on completion" },
       unwatch:    { args: "<id>",                  desc: "Stop watching" },
       watches:    { args: "",                      desc: "List watches" },
@@ -219,7 +221,7 @@ export const status = defineCommand({
 
     const cfg = config.load();
 
-    let threads: any, tasks: any;
+    let threads: Awaited<ReturnType<typeof api.listThreads>>, tasks: Awaited<ReturnType<typeof api.listTasks>>;
     if (!args.json) {
       const s = spinner();
       s.start("Loading dashboard...");

package/src/commands/tasks.ts

@@ -31,10 +31,22 @@ export const get = defineCommand({
   },
   async run({ args }) {
     const api = await import("../api.js");
+    const config = await import("../config.js");
+    const github = await import("../github.js");
     const fmt = await import("../output.js");
     const { log } = await import("@clack/prompts");
 
     const data = await api.getTask(args.id);
+
+    // Capy API reports merged PRs as "closed". Cross-ref with GitHub for real state.
+    if (data.pullRequest?.number && data.pullRequest.state === "closed") {
+      const repo = data.pullRequest.repoFullName || config.load().repos[0]?.repoFullName;
+      if (repo) {
+        const ghPR = github.getPR(repo, data.pullRequest.number);
+        if (ghPR) data.pullRequest.state = ghPR.state.toLowerCase();
+      }
+    }
+
     if (args.json) { fmt.out(data); return; }
     log.info(`Task:    ${data.identifier} \u2014 ${data.title}\nStatus:  ${data.status}\nCreated: ${data.createdAt}`);
     if (data.pullRequest) {

package/src/commands/threads.ts

@@ -51,7 +51,9 @@ const msg = defineCommand({
   },
   async run({ args }) {
     const api = await import("../api.js");
-    await api.messageThread(args.id, args.text);
+    const fmt = await import("../output.js");
+    const result = await api.messageThread(args.id, args.text);
+    if (args.json) { fmt.out(result); return; }
     console.log("Message sent.");
   },
 });
@@ -64,7 +66,9 @@ const stop = defineCommand({
   },
   async run({ args }) {
     const api = await import("../api.js");
-    await api.stopThread(args.id);
+    const fmt = await import("../output.js");
+    const result = await api.stopThread(args.id);
+    if (args.json) { fmt.out(result); return; }
     console.log(`Stopped thread ${args.id}.`);
   },
 });

package/src/config.ts

@@ -85,6 +85,7 @@ export function set(key: string, value: string): void {
     if (value === "true") parsed = true;
     else if (value === "false") parsed = false;
     else if (/^\d+$/.test(value)) parsed = parseInt(value);
+    else if (/^\d+\.\d+$/.test(value)) parsed = parseFloat(value);
     obj[parts[parts.length - 1]] = parsed;
   } else {
     cfg[key] = value;

package/src/github.ts

@@ -98,8 +98,9 @@ export function diffHasTests(files: DiffFile[]): boolean {
 
 export function getUnresolvedThreads(repo: string, number: number): { body: string; author: string }[] {
   try {
-    const query = `query { repository(owner:"${repo.split("/")[0]}", name:"${repo.split("/")[1]}") { pullRequest(number:${number}) { reviewThreads(first:100) { nodes { isResolved isOutdated comments(first:1) { nodes { body author { login } } } } } } } }`;
-    const out = execFileSync("gh", ["api", "graphql", "-f", `query=${query}`], {
+    const query = `query($owner: String!, $name: String!, $number: Int!) { repository(owner: $owner, name: $name) { pullRequest(number: $number) { reviewThreads(first:100) { nodes { isResolved isOutdated comments(first:1) { nodes { body author { login } } } } } } } }`;
+    const [owner, name] = repo.split("/");
+    const out = execFileSync("gh", ["api", "graphql", "-f", `query=${query}`, "-F", `owner=${owner}`, "-F", `name=${name}`, "-F", `number=${number}`], {
       encoding: "utf8", timeout: 15000,
     });
     const data = JSON.parse(out);

package/src/greptile.ts

@@ -1,14 +1,19 @@
 import * as config from "./config.js";
+import { IS_JSON } from "./output.js";
 import type { UnaddressedIssue } from "./types.js";
 
 const MCP_URL = "https://api.greptile.com/mcp";
 
+function warn(msg: string): void {
+  if (!IS_JSON) console.error(msg);
+}
+
 async function mcp(method: string, params: Record<string, unknown>): Promise<any> {
   const cfg = config.load();
   const apiKey = cfg.greptileApiKey || process.env.GREPTILE_API_KEY || "";
   if (!apiKey) {
-    console.error("capy: GREPTILE_API_KEY not set. Run: capy config greptileApiKey <key>");
-    process.exit(1);
+    warn("capy: GREPTILE_API_KEY not set. Run: capy config greptileApiKey <key>");
+    return null;
   }
 
   const body = {
@@ -34,7 +39,7 @@ async function mcp(method: string, params: Record<string, unknown>): Promise<any
       signal: AbortSignal.timeout(30000),
     });
   } catch (e: unknown) {
-    console.error(`greptile: request failed — ${(e as Error).message}`);
+    warn(`greptile: request failed — ${(e as Error).message}`);
     return null;
   }
 
@@ -42,7 +47,7 @@ async function mcp(method: string, params: Record<string, unknown>): Promise<any
   try {
     const data = JSON.parse(text);
     if (data.error) {
-      console.error(`greptile: ${data.error.message || JSON.stringify(data.error)}`);
+      warn(`greptile: ${data.error.message || JSON.stringify(data.error)}`);
       return null;
     }
     if (data.result?.content) {
@@ -53,7 +58,7 @@ async function mcp(method: string, params: Record<string, unknown>): Promise<any
     }
     return data.result;
   } catch {
-    console.error("greptile: bad response:", text.slice(0, 300));
+    warn(`greptile: bad response: ${text.slice(0, 300)}`);
     return null;
   }
 }
@@ -121,7 +126,7 @@ export async function freshReview(repo: string, prNumber: number, defaultBranch?
   const reviewId = trigger.codeReviewId || trigger.id;
   if (!reviewId) return trigger;
 
-  console.error(`greptile: review triggered (${reviewId}), waiting...`);
+  warn(`greptile: review triggered (${reviewId}), waiting...`);
   return waitForReview(reviewId);
 }
 

package/src/mcp.ts

@@ -0,0 +1,136 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createRequire } from "node:module";
+import * as api from "./api.js";
+import * as config from "./config.js";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+const server = new McpServer({
+  name: "capy",
+  version,
+});
+
+server.tool("capy_captain", "Start a Captain thread to delegate coding work", {
+  prompt: z.string().describe("What the agent should do. Be specific: files, functions, acceptance criteria."),
+  model: z.string().optional().describe("Model ID override"),
+}, async ({ prompt, model }) => {
+  const cfg = config.load();
+  const data = await api.createThread(prompt, model);
+  return { content: [{ type: "text", text: JSON.stringify({ threadId: data.id, url: `https://capy.ai/project/${cfg.projectId}/captain/${data.id}` }) }] };
+});
+
+server.tool("capy_status", "Get task or thread status, or full dashboard", {
+  id: z.string().optional().describe("Task or thread ID. Omit for dashboard."),
+}, async ({ id }) => {
+  if (id) {
+    const isThread = id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
+    const data: any = isThread ? await api.getThread(id) : await api.getTask(id);
+    // Capy API reports merged PRs as "closed". Cross-ref with GitHub for real state.
+    if (!isThread && data.pullRequest?.number && data.pullRequest.state === "closed") {
+      const { getPR } = await import("./github.js");
+      const cfg = config.load();
+      const repo = data.pullRequest.repoFullName || cfg.repos[0]?.repoFullName;
+      if (repo) {
+        const ghPR = getPR(repo, data.pullRequest.number);
+        if (ghPR) data.pullRequest.state = ghPR.state.toLowerCase();
+      }
+    }
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+  }
+  const [threads, tasks] = await Promise.all([api.listThreads({ limit: 10 }), api.listTasks({ limit: 30 })]);
+  return { content: [{ type: "text", text: JSON.stringify({ threads: threads.items || [], tasks: tasks.items || [] }) }] };
+});
+
+server.tool("capy_review", "Run quality gates on a task", {
+  id: z.string().describe("Task ID"),
+}, async ({ id }) => {
+  const qualityEngine = await import("./quality-engine.js");
+  const task = await api.getTask(id);
+  if (!task.pullRequest?.number) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: "no_pr", task: task.identifier }) }] };
+  }
+  const q = await qualityEngine.check(task);
+  return { content: [{ type: "text", text: JSON.stringify({ task: task.identifier, quality: q }) }] };
+});
+
+server.tool("capy_approve", "Approve a task if quality gates pass. Runs the configured approveCommand hook on success.", {
+  id: z.string().describe("Task ID"),
+  force: z.boolean().optional().describe("Override failing gates"),
+}, async ({ id, force }) => {
+  const qualityEngine = await import("./quality-engine.js");
+  const task = await api.getTask(id);
+  const cfg = config.load();
+  const q = await qualityEngine.check(task);
+  const approved = q.pass || !!force;
+
+  if (approved && cfg.approveCommand) {
+    try {
+      const { execFileSync } = await import("node:child_process");
+      const parts = cfg.approveCommand
+        .replace("{task}", task.identifier || task.id)
+        .replace("{title}", task.title || "")
+        .replace("{pr}", String(task.pullRequest?.number || ""))
+        .split(/\s+/);
+      execFileSync(parts[0], parts.slice(1), { encoding: "utf8", timeout: 15000, stdio: "pipe" });
+    } catch {}
+  }
+
+  return { content: [{ type: "text", text: JSON.stringify({ task: task.identifier, quality: q, approved }) }] };
+});
+
+server.tool("capy_retry", "Retry a failed task with context from previous attempt", {
+  id: z.string().describe("Task ID to retry"),
+  fix: z.string().optional().describe("Specific fix instructions"),
+  model: z.string().optional().describe("Model ID override"),
+}, async ({ id, fix, model }) => {
+  const task = await api.getTask(id);
+  const cfg = config.load();
+
+  let context = `Previous attempt: ${task.identifier} "${task.title}" [${task.status}]\n`;
+  try {
+    const d = await api.getDiff(id);
+    if (d.stats?.files && d.stats.files > 0) {
+      context += `\nPrevious diff: +${d.stats.additions} -${d.stats.deletions} in ${d.stats.files} files\n`;
+    }
+  } catch {}
+
+  let retryPrompt = `RETRY: This is a retry of a previous attempt that had issues.\n\nOriginal task: ${task.prompt || task.title}\n\n--- CONTEXT ---\n${context}\n`;
+  if (fix) retryPrompt += `--- FIX ---\n${fix}\n\n`;
+  retryPrompt += `Fix the issues. Include tests. Run tests before completing.\n`;
+
+  if (task.status === "in_progress") {
+    await api.stopTask(id, "Retrying with fixes");
+  }
+
+  const data = await api.createThread(retryPrompt, model || cfg.defaultModel);
+  return { content: [{ type: "text", text: JSON.stringify({ originalTask: task.identifier, newThread: data.id, model: model || cfg.defaultModel }) }] };
+});
+
+server.tool("capy_wait", "Poll until a task or thread reaches terminal state", {
+  id: z.string().describe("Task or thread ID"),
+  timeout: z.number().optional().describe("Timeout in seconds (default 300)"),
+  interval: z.number().optional().describe("Poll interval in seconds (default 10)"),
+}, async ({ id, timeout, interval }) => {
+  const timeoutMs = (timeout || 300) * 1000;
+  const intervalMs = Math.max(5, Math.min(interval || 10, 60)) * 1000;
+  const isThread = id.length > 20 || (id.length > 10 && !id.match(/^[A-Z]+-\d+$/));
+  const terminalTask = new Set(["needs_review", "archived", "completed", "failed"]);
+  const terminalThread = new Set(["idle", "archived", "completed"]);
+  const terminal = isThread ? terminalThread : terminalTask;
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const data = isThread ? await api.getThread(id) : await api.getTask(id);
+    if (terminal.has(data.status)) {
+      return { content: [{ type: "text", text: JSON.stringify(data) }] };
+    }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  return { content: [{ type: "text", text: JSON.stringify({ error: { code: "timeout", message: `Timed out after ${timeout || 300}s` } }) }] };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/output.ts

@@ -19,7 +19,8 @@ export function out(data: unknown): void {
 
 export function table(headers: string[], rows: (string | number | null | undefined)[][]): void {
   if (IS_JSON) {
-    console.log(JSON.stringify(rows, null, 2));
+    const keyed = rows.map(r => Object.fromEntries(headers.map((h, i) => [h.toLowerCase(), r[i] ?? null])));
+    console.log(JSON.stringify(keyed, null, 2));
     return;
   }
   const widths = headers.map((h, i) =>

package/src/watch.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import * as config from "./config.js";
 import type { WatchEntry } from "./types.js";
 
@@ -9,7 +9,7 @@ function getCrontab(): string {
 }
 
 function setCrontab(content: string): void {
-  execSync(`echo ${JSON.stringify(content)} | crontab -`, { encoding: "utf8" });
+  execSync("crontab -", { input: content, encoding: "utf8" });
 }
 
 export function add(id: string, type: string, intervalMin: number): boolean {
@@ -53,8 +53,9 @@ export function notify(text: string): boolean {
   const cfg = config.load();
   const cmd = cfg.notifyCommand || "openclaw system event --text {text} --mode now";
   try {
-    execSync(cmd.replace("{text}", JSON.stringify(text)), {
-      encoding: "utf8", timeout: 15000,
+    const parts = cmd.replace("{text}", text).split(/\s+/);
+    execFileSync(parts[0], parts.slice(1), {
+      encoding: "utf8", timeout: 15000, stdio: "pipe",
     });
     return true;
   } catch { return false; }