ai-whisper 0.1.0 → 0.1.2

package/NOTICE

@@ -0,0 +1,4 @@
+ai-whisper
+Copyright 2026 Vu Phan
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -0,0 +1,123 @@
+# ai-whisper
+
+ai-whisper turns two coding agents — Claude and Codex — into a terminal-native pair that hand work back and forth under a single baton, so one agent implements while the other reviews, and a structured workflow drives the loop to a finished, reviewed deliverable without a human babysitting every round.
+
+## Magic moment
+
+Mount each agent in its own terminal. Each `mount` claims the current shell, launches the real provider CLI, and binds it to the collab:
+
+```bash
+# terminal 1
+whisper collab mount claude
+# terminal 2
+whisper collab mount codex
+```
+
+Then, from inside either agent's session, kick off a structured workflow against a spec — just ask in plain language:
+
+```text
+Run spec-driven-development using docs/spec.md
+```
+
+From there ai-whisper runs the workflow autonomously:
+
+- **Implementer / reviewer assignment** — the agent you trigger the workflow from becomes the implementer and the other agent becomes the reviewer; pass `--implementer` / `--reviewer` to choose explicitly. (Started outside a mounted session with no flags, it falls back to a default pairing and warns.) The baton passes between them; only one owns the turn at a time.
+- **Autonomous execution** — the implementer does each step in its real session and hands the result back. An LLM evaluator judges whether the deliverable meets the request.
+- **Review loops** — when work isn't good enough yet, the reviewer's findings are composed into a follow-up handoff and the implementer iterates. The loop repeats until the work is approved or the round budget is exhausted.
+- **Resumability** — workflow and chain state is durable. If the broker restarts or you stop for the day, you recover and reconnect rather than starting over.
+- **Deliverables** — you get committed code plus a review trail (per-step verdicts, round counts), inspectable at any time with `whisper collab dashboard`.
+
+## Visual proof
+
+A real `spec-driven-development` run: Claude (left) and Codex (middle) work in their own mounted
+sessions while the dashboard (right) tracks the baton handoffs and per-phase verdicts (~20s).
+Click the still to watch it play on the project page.
+
+[![ai-whisper running a spec-driven-development workflow across two mounted agent sessions and the dashboard](docs/assets/workflow-demo-poster.png)](https://ai-creed.dev/projects/ai-whisper/)
+
+## Who this is for
+
+ai-whisper is for engineers who already lean on coding agents and want more structure around them:
+
+- you already use coding agents heavily and want two of them to check each other.
+- you work terminal-first and want the agents to live in real terminal sessions, not a web UI.
+- you want multi-agent review — a second model gating the first model's output.
+- you run long, structured workflows (spec → plan → implement → review) rather than one-off prompts.
+
+It is **not** for:
+
+- one-shot "vibe coding" where you just want a quick answer.
+- invisible background automation you never watch.
+- people new to coding agents looking for a guided, hand-holding experience.
+
+## Quickstart
+
+Install from npm:
+
+```bash
+npm install -g ai-whisper
+```
+
+Or from a repo checkout:
+
+```bash
+pnpm install
+pnpm build
+```
+
+Install the bundled agent skills once (they let the agents verify, kick off, and report on workflows):
+
+```bash
+whisper skill install
+```
+
+Workflows require an LLM evaluator with credentials — set this up before running one. See [Evaluator configuration](docs/evaluator-configuration.md).
+
+Then mount both agents and run a workflow:
+
+```bash
+# terminal 1
+whisper collab mount claude
+# terminal 2
+whisper collab mount codex
+```
+
+The first `mount` creates the collab and starts the broker daemon for the workspace; the second binds the other agent. From either session, start a workflow against a spec or goal file (`spec-driven-development` for a spec, `ralph-loop` for an open-ended goal). Watch it run with:
+
+```bash
+whisper collab dashboard
+```
+
+> Running from a repo checkout instead of a packaged install? Build first (`pnpm build`) and invoke the CLI as `node packages/cli/dist/bin/whisper.js ...` wherever these examples say `whisper ...`.
+
+## Core concepts
+
+ai-whisper is **not a swarm**. The agents never type at once — work moves by a single baton, one owner at a time. Mounted sessions are *real* Claude and Codex sessions in your terminal, and those sessions are the source of truth. Autonomy is supervised: every handoff, verdict, and round is inspectable, and runs are resumable rather than fire-and-forget. Work is organized as structured workflows — explicit loops and state transitions, not a free-form chat.
+
+Claude and Codex are supported today; the architecture is provider-agnostic by design, so other coding-agent CLIs can be added behind the same relay.
+
+For the full mental model, read [Concepts](docs/concepts.md).
+
+## Learn more
+
+- [Workflows](docs/workflows.md) — how to use the workflows well: choosing between `spec-driven-development` and `ralph-loop`, and authoring the spec or goal that drives the run.
+- [Concepts](docs/concepts.md) — the mental model: baton handoff, real mounted sessions, supervised autonomy, workflow-first execution.
+- [Relay & handoff flows](docs/relay-handoff-flows.md) — the complete handoff state machine, capture-status table, hotkey reference, per-step verdicts, and troubleshooting.
+- [Evaluator configuration](docs/evaluator-configuration.md) — required credentials and options for the LLM evaluator that gates workflows.
+- [Legacy attach mode](docs/legacy-attach.md) — the shelved `attach` / `adopt` flows, kept for historical reference.
+
+## Workspace commands
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm lint
+pnpm format
+```
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Contributions are
+accepted under the [Developer Certificate of Origin](CONTRIBUTING.md) (sign off with
+`git commit -s`).

package/dist/bin/companion-agent.js

@@ -5866,12 +5866,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn2(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn2(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6169,12 +6173,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn4(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn4(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;

package/dist/bin/whisper.js

@@ -6168,12 +6168,16 @@ function createNodePty(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath
   });
-  return spawn3(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn3(input.config.executable, input.config.execArgs, buildClaudePtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildClaudePtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "claude";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createClaudeLiveSession(input) {
   let pty = null;
@@ -6471,12 +6475,16 @@ function createNodePty2(input) {
   ensureNodePtySpawnHelperExecutable({
     unixTerminalPath: nodePtyUnixTerminalPath2
   });
-  return spawn5(input.config.executable, input.config.execArgs, {
-    name: "xterm-256color",
-    cols: input.cols,
-    rows: input.rows,
-    cwd: input.cwd
-  });
+  return spawn5(input.config.executable, input.config.execArgs, buildCodexPtySpawnOptions({ cols: input.cols, rows: input.rows, cwd: input.cwd }));
+}
+function buildCodexPtySpawnOptions(input) {
+  const env = {};
+  for (const [key, value] of Object.entries(input.baseEnv ?? process.env)) {
+    if (typeof value === "string")
+      env[key] = value;
+  }
+  env.AI_WHISPER_AGENT = "codex";
+  return { name: "xterm-256color", cols: input.cols, rows: input.rows, cwd: input.cwd, env };
 }
 function createCodexLiveSession(input) {
   let pty = null;
@@ -10802,21 +10810,62 @@ async function runWorkflowStart(deps) {
     }
   }
   const def = getWorkflowDefinition(deps.workflowType);
-  const implementer = deps.implementer ?? def?.defaultImplementer;
-  const reviewer = deps.reviewer ?? def?.defaultReviewer;
-  if (!implementer || !reviewer) {
-    throw new Error(
-      `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
-    );
+  let resolved;
+  try {
+    resolved = resolveRoleBindings({
+      explicitImplementer: deps.implementer,
+      explicitReviewer: deps.reviewer,
+      callerAgent: deps.callerAgent ?? null,
+      def
+    });
+  } catch (e) {
+    if (e instanceof Error && /no default role bindings/.test(e.message)) {
+      throw new Error(
+        `Workflow type "${deps.workflowType}" has no default role bindings. Pass --implementer and --reviewer explicitly.`
+      );
+    }
+    throw e;
   }
-  return deps.broker.control.createWorkflow({
+  const { workflowId } = deps.broker.control.createWorkflow({
     collabId: deps.collabId,
     workflowType: deps.workflowType,
     specPath: deps.specPath,
-    roleBindings: { implementer, reviewer },
+    roleBindings: { implementer: resolved.implementer, reviewer: resolved.reviewer },
     ...deps.name ? { name: deps.name } : {},
     now: deps.now
   });
+  return { workflowId, ...resolved.warning ? { roleWarning: resolved.warning } : {} };
+}
+var otherAgent = (a) => a === "claude" ? "codex" : "claude";
+function resolveRoleBindings(input) {
+  const { explicitImplementer, explicitReviewer, callerAgent, def } = input;
+  if (explicitImplementer || explicitReviewer) {
+    const implementer2 = explicitImplementer ?? (explicitReviewer ? otherAgent(explicitReviewer) : void 0);
+    const reviewer2 = explicitReviewer ?? (explicitImplementer ? otherAgent(explicitImplementer) : void 0);
+    if (implementer2 && reviewer2) {
+      if (implementer2 === reviewer2) {
+        throw new Error("implementer and reviewer cannot be the same agent");
+      }
+      return { implementer: implementer2, reviewer: reviewer2, source: "explicit" };
+    }
+  }
+  if (callerAgent) {
+    return { implementer: callerAgent, reviewer: otherAgent(callerAgent), source: "caller" };
+  }
+  const implementer = def?.defaultImplementer;
+  const reviewer = def?.defaultReviewer;
+  if (!implementer || !reviewer) {
+    throw new Error("no default role bindings");
+  }
+  return {
+    implementer,
+    reviewer,
+    source: "default",
+    warning: `No triggering agent detected; defaulted to implementer=${implementer} / reviewer=${reviewer}. Pass --implementer / --reviewer to choose explicitly.`
+  };
+}
+function parseCallerAgent(raw) {
+  return raw === "claude" || raw === "codex" ? raw : null;
 }
 
 // src/commands/workflow/list.ts
@@ -11184,8 +11233,10 @@ Not attached (stdin/stdout is not a TTY). To view the tmux session, run:
           ...opts.implementer ? { implementer: opts.implementer } : {},
           ...opts.reviewer ? { reviewer: opts.reviewer } : {},
           ...opts.name ? { name: opts.name } : {},
+          callerAgent: parseCallerAgent(process.env.AI_WHISPER_AGENT),
           now: (/* @__PURE__ */ new Date()).toISOString()
         });
+        if (result.roleWarning) console.error(result.roleWarning);
         console.log(`Workflow started: ${result.workflowId}`);
       } finally {
         await broker.stop();

package/dist/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/dist/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-whisper",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Terminal-first relay for paired AI coding agents (Claude + Codex), driven by structured workflows.",
   "license": "Apache-2.0",
   "repository": {
@@ -30,17 +30,20 @@
     "@types/react": "^19.2.14",
     "ink-testing-library": "^4.0.0",
     "@ai-whisper/adapter-claude": "0.0.0",
-    "@ai-whisper/adapter-codex": "0.0.0",
+    "@ai-whisper/broker": "0.0.0",
     "@ai-whisper/companion-core": "0.0.0",
     "@ai-whisper/shared": "0.0.0",
-    "@ai-whisper/broker": "0.0.0"
+    "@ai-whisper/adapter-codex": "0.0.0"
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "scripts": {
-    "build": "node scripts/bundle.mjs && node scripts/copy-skills.mjs",
+    "build": "node scripts/bundle.mjs && node scripts/copy-skills.mjs && node scripts/copy-package-files.mjs",
     "typecheck": "tsc -b --emitDeclarationOnly"
   }
 }

package/skills/ai-whisper-ralph/SKILL.md

@@ -97,7 +97,7 @@ Run:
 whisper workflow start --type=ralph-loop --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills ralph defaults: implementer=claude, reviewer=codex. `--spec` names the goal file.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override. `--spec` names the goal file.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).
 

package/skills/ai-whisper-sdd/SKILL.md

@@ -94,7 +94,7 @@ Run:
 whisper workflow start --type=spec-driven-development --spec=<resolved-absolute-path>
 ```
 
-(No `--implementer` / `--reviewer` — the CLI fills SDD defaults: implementer=claude, reviewer=codex.)
+(No `--implementer` / `--reviewer` needed — the agent triggering this skill becomes the implementer and the other agent the reviewer. Pass `--implementer <agent> --reviewer <agent>` only to override.)
 
 Parse the workflowId from stdout (format: `Workflow started: <workflowId>`).