pi-bro 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.19.0] - 2026-09-25
+
+### Added
+
+- Support for OpenAI Codex CLI (`codex`) across all features: explain, show, BTW, and advisor. Explain and show run under a read-only sandbox with ephemeral session handling; BTW continues natively via `resume` across both conversation-only and full-permission modes; advisor runs in the workspace with sandbox bypassed. Supports seeded models `gpt-5.5` and `gpt-5.4` plus custom model IDs, and reasoning efforts `low`, `medium`, `high`, `xhigh`.
+- Support for Meta Muse Code (`muse`) across all features: explain, show, BTW, and advisor. Explain and show run in a scratch directory with approval, non-shell write, and shell disabled; BTW continues natively via `--session-id` across `/mode` switches; advisor runs in the workspace with `--yolo`. Supports seeded models `muse-spark-1.3-contributor` and `muse-spark-1.3` plus custom model IDs, and reasoning efforts `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (omitted for model default).
+- Configuration modal support in `/bro config` for Codex and Muse, including atomic model selection, custom model ID inputs, and dynamic reasoning effort dropdowns.
+- Doctor diagnostic checks for Codex (version and `codex login status` authentication probe) and Muse (version probe).
+
+## [0.18.1] - 2026-09-30
+
+### Fixed
+
+- Declare host-provided `typebox` and Pi packages as wildcard peer dependencies, keeping pinned copies only for development. This removes the host-dependency warning added in Pi 0.99.0 and avoids installing a separate runtime TypeBox copy.
+
 ## [0.18.0] - 2026-09-24
 
 ### Added

package/README.md

@@ -7,11 +7,13 @@ plain-language explanation — or open a separate side conversation with
 `pi-bro` is an extension for [Earendil Pi](https://github.com/earendil-works/pi).
 It opens explanations in a separate modal and runs them through a CLI backend
 you already have installed and signed in to. Explain, show, BTW, and the
-advisor all work on all three backends:
+advisor all work across five backends:
 
 - [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`) — the default for new settings
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
 - Grok Build (`grok`)
+- [Codex CLI](https://github.com/openai/codex) (`codex`)
+- Meta Muse Code (`muse`)
 
 You only need the backend(s) you select; Agy is the default, not a requirement.
 
@@ -25,7 +27,7 @@ for the default). Then install Bro:
 pi install npm:pi-bro
 ```
 
-Restart Pi or run `/reload`. If you use Claude Code or Grok instead of Agy,
+Restart Pi or run `/reload`. If you use Claude Code, Grok, Codex, or Muse instead of Agy,
 choose it in `/bro config` (for everything, or per feature). Then try:
 
 ```text
@@ -686,6 +688,9 @@ feature. Failed checks explain what to fix.
 - **Claude Code**: installed version and configured authentication.
 - **Grok**: installed version only; authentication and connectivity are not
   verified.
+- **Codex**: installed version and configured authentication.
+- **Muse**: installed version only; authentication and connectivity are not
+  verified.
 
 Doctor never sends source text or runs a model completion. A successful check
 confirms the setup but cannot guarantee that a later provider request will
@@ -729,7 +734,7 @@ Bro reads the file again before each request, so manual edits apply next time.
   Omitted overrides inherit `default`.
 - `effort` must be one the backend offers (`default` omits it and lets the
   model decide). Agy selections are normalized against Agy's installed model
-  catalog. Claude and Grok accept seeded or custom model IDs; a model/effort
+  catalog. Claude, Grok, Codex, and Muse accept seeded or custom model IDs; a model/effort
   combination the account does not support fails with the backend's own error
   instead of silently falling back.
 - `mode` is `brief`, `balanced` (the default), or `faithful`. `showTurns` is
@@ -751,19 +756,27 @@ data under their own settings and policies.
 | **Agy** | Temporary directory, Agy sandbox | Temporary directory, Agy sandbox | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
 | **Claude Code** | Scratch directory, tools/MCP/skills disabled, no session persistence | Workspace, tools disabled | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
 | **Grok** | Temporary directory, **prompt instruction only** | Workspace, **prompt instruction only** | Workspace, permissions bypassed | Fresh workspace process, permissions bypassed |
+| **Codex** | Scratch directory, read-only sandbox, ephemeral session | Workspace, read-only sandbox | Workspace, approvals and sandbox bypassed | Fresh workspace process, approvals and sandbox bypassed |
+| **Muse** | Scratch directory, approval/write/shell disabled, no session log | Workspace, approval/write/shell disabled | Workspace, permissions bypassed (`--yolo`) | Fresh workspace process, permissions bypassed (`--yolo`) |
 
 - Grok always runs with its sandbox off and permissions bypassed; its tools,
   hooks, skills, plugins, and MCP may remain available. "Answer only from the
   supplied context" is a request, not an enforced restriction.
+- Codex's read-only sandbox is not a tool-free mode: workspace reads and
+  sandboxed commands remain available. Bro does not disable configured MCP
+  servers or web search; their access is governed by Codex configuration.
+- Muse's restricted mode disables write and shell tools and approval prompts,
+  not all tools: workspace reads and web tools remain available without approval.
+  It is not a tool-free or network-isolated mode.
 - Claude's restrictions are tool/configuration settings (with safe mode), not
   an OS sandbox; built-in and managed Claude behavior can remain. Running a
   permission-bypassing mode as root may be rejected by Claude.
 - BTW continues natively: Agy by conversation ID, Claude and Grok by
-  `--resume` of the same session, including across `/mode` switches. An Agy
-  conversation stays bound to the workspace it started in, so after a `/mode`
-  switch — or whenever a thread has turns but no native session ID — Bro starts
-  a fresh native session seeded with the main-session context and every
-  earlier turn.
+  `--resume`, Codex by `resume`, and Muse by `--session-id` of the same session,
+  including across `/mode` switches. An Agy conversation stays bound to the
+  workspace it started in, so after a `/mode` switch — or whenever a thread
+  has turns but no native session ID — Bro starts a fresh native session
+  seeded with the main-session context and every earlier turn.
 - Cancellation, deadlines, and invalid output streams stop the backend's
   process group on POSIX, escalating after a five-second grace period. On
   Windows only the direct child is targeted. Detached shell work or external

package/backend.ts

@@ -15,10 +15,14 @@ export type BackendAccess = "restricted" | "workspace-full";
 export type AgySelection = { model: string; effort?: "low" | "medium" | "high" };
 export const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"] as const;
 export const GROK_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export const CODEX_EFFORTS = ["low", "medium", "high", "xhigh"] as const;
+export const MUSE_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type BackendSelection =
 	| ({ backend?: "agy" } & AgySelection)
 	| { backend: "claude"; model: string; effort?: (typeof CLAUDE_EFFORTS)[number] }
-	| { backend: "grok"; model: string; effort?: (typeof GROK_EFFORTS)[number] };
+	| { backend: "grok"; model: string; effort?: (typeof GROK_EFFORTS)[number] }
+	| { backend: "codex"; model: string; effort?: (typeof CODEX_EFFORTS)[number] }
+	| { backend: "muse"; model: string; effort?: (typeof MUSE_EFFORTS)[number] };
 export type BackendContinuation = { id: string };
 export type BackendProgress = { kind: "text"; text: string } | { kind: "activity"; label: string; timestamp: number };
 export type BackendOnProgress = (progress: BackendProgress) => void;
@@ -73,7 +77,11 @@ function processStartMessage(processError: NodeJS.ErrnoException, cli = "Agy"):
 			? "Agy could not start. Make sure Agy is installed and on PATH, then run `/bro doctor`."
 			: cli === "Grok"
 				? "Grok could not start. Make sure `grok` is installed and on PATH, then run `/bro doctor`."
-				: "Claude Code could not start. Make sure `claude` is installed and on PATH, then run `/bro doctor`.";
+				: cli === "Codex"
+					? "Codex could not start. Make sure `codex` is installed and on PATH, then run `/bro doctor`."
+					: cli === "Muse"
+						? "Muse could not start. Make sure `muse` is installed and on PATH, then run `/bro doctor`."
+						: "Claude Code could not start. Make sure `claude` is installed and on PATH, then run `/bro doctor`.";
 	}
 	return `${cli} could not start: ${processError.message}\n\nRun \`/bro doctor\` for setup help.`;
 }
@@ -495,7 +503,7 @@ async function executeAdvisorStdin(
 
 // Every backend supports every feature. Grok's "restricted" access is a prompt instruction, not
 // enforcement (see GROK_RESTRICTED_PREFIX); Claude's restricted btw runs tool-less.
-export function backendSupports(_backend: "agy" | "claude" | "grok", _feature: BackendFeature): boolean {
+export function backendSupports(_backend: "agy" | "claude" | "grok" | "codex" | "muse", _feature: BackendFeature): boolean {
 	return true;
 }
 
@@ -964,6 +972,458 @@ async function executeGrok(
 	}
 }
 
+type CodexEvent = {
+	type?: unknown;
+	thread_id?: unknown;
+	item?: {
+		id?: unknown;
+		type?: unknown;
+		text?: unknown;
+		message?: unknown;
+		content?: unknown;
+		command?: unknown;
+		cmd?: unknown;
+		path?: unknown;
+		pattern?: unknown;
+		query?: unknown;
+	};
+	error?: { message?: unknown };
+	message?: unknown;
+};
+
+function extractCodexItemText(item: CodexEvent["item"]): string | undefined {
+	if (!item) return undefined;
+	if (typeof item.text === "string") return item.text;
+	if (typeof item.message === "string") return item.message;
+	if (typeof item.content === "string") return item.content;
+	return undefined;
+}
+
+function codexActivityFromEvent(event: CodexEvent): string | undefined {
+	const item = event.item;
+	if (!item || item.type === "reasoning") return undefined;
+	if (event.type === "item.started" || event.type === "item.completed") {
+		if (item.type !== "agent_message") {
+			const itemType = typeof item.type === "string" ? item.type : "item";
+			const candidate = [item.command, item.cmd, item.path, item.pattern, item.query]
+				.find((v) => typeof v === "string" && v.trim());
+			const preview = typeof candidate === "string" ? candidate.replace(/\s+/g, " ").trim() : "";
+			return `${itemType}${preview ? ` ${preview}` : ""}`;
+		}
+		if (item.type === "agent_message") {
+			const text = extractCodexItemText(item);
+			return text?.split("\n").find((line) => line.trim())?.trim();
+		}
+	}
+	return undefined;
+}
+
+async function executeCodex(
+	request: BackendRequest,
+	selection: { model: string; effort?: string },
+	signal: AbortSignal,
+	onProgress: BackendOnProgress | undefined,
+	killEscalationMs: number,
+	deadlineMsOverride: number | undefined,
+): Promise<BackendOutcome> {
+	const isAdvisor = request.feature === "advisor";
+	const isBtw = request.feature === "btw";
+	const full = request.access === "workspace-full";
+	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = isAdvisor ? "Codex returned no advice." : isBtw ? "Codex returned no answer for the side question." : "Codex returned no final explanation.";
+
+	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+	const runDirectory = isAdvisor || isBtw ? undefined : await mkdtemp(join(tmpdir(), "pi-bro-"));
+	if (signal.aborted) {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+		return { status: "cancelled", message: "Canceled." };
+	}
+
+	try {
+		const permissionArgs = full ? ["--dangerously-bypass-approvals-and-sandbox"] : ["--sandbox", "read-only"];
+		const resume = isBtw && request.continuation;
+		const args = [
+			"exec",
+			...permissionArgs,
+			...(resume ? ["resume"] : []),
+			"--json",
+			"--skip-git-repo-check",
+			...(!isBtw ? ["--ephemeral"] : []),
+			"--model",
+			selection.model,
+			...(selection.effort ? ["-c", `model_reasoning_effort="${selection.effort}"`] : []),
+			...(resume ? [request.continuation!.id, "-"] : ["--", "-"]),
+		];
+
+		const child = spawn("codex", args, {
+			cwd: runDirectory ?? request.cwd,
+			stdio: ["pipe", "pipe", "pipe"],
+			windowsHide: true,
+			detached: process.platform !== "win32",
+		});
+
+		const attempt = beginAttempt(child, signal, deadlineMs, killEscalationMs);
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let threadId: string | undefined;
+		let final: string | undefined;
+		let sawTerminal = false;
+		let terminalError: string | undefined;
+		let protocolError: string | undefined;
+		let stdoutBuffer = "";
+
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+		child.stdin?.on("error", () => {
+			// codex exiting before reading stdin is reported through the close/error path.
+		});
+		child.stdin?.end(request.prompt);
+
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			let event: CodexEvent;
+			try {
+				event = JSON.parse(line) as CodexEvent;
+			} catch {
+				throw new Error("Codex emitted invalid JSON output.");
+			}
+			if (event.type === "thread.started" && typeof event.thread_id === "string") {
+				threadId = event.thread_id;
+			}
+			if (event.type === "error") {
+				terminalError ??= `Codex error: ${typeof event.message === "string" && event.message.trim() ? event.message.trim() : "unknown error"}`;
+				return;
+			}
+			if (event.type === "turn.failed") {
+				sawTerminal = true;
+				const err = event.error as { message?: unknown } | undefined;
+				terminalError ??= `Codex failed: ${typeof err?.message === "string" && err.message.trim() ? err.message.trim() : "turn failed"}`;
+				return;
+			}
+			if (event.type === "turn.completed") {
+				sawTerminal = true;
+				return;
+			}
+			const item = event.item;
+			if (isAdvisor && (event.type === "item.started" || event.type === "item.completed")) {
+				const activity = codexActivityFromEvent(event);
+				if (activity) onProgress?.({ kind: "activity", label: activity, timestamp: Date.now() });
+			}
+			if (event.type === "item.completed" && item?.type === "agent_message") {
+				const text = extractCodexItemText(item);
+				if (text !== undefined) {
+					final = text;
+					if (!isAdvisor) {
+						partial += `${partial ? "\n\n" : ""}${text}`;
+						onProgress?.({ kind: "text", text: partial });
+					}
+				}
+			}
+		};
+
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdoutBuffer += chunk;
+			const parts = stdoutBuffer.split(/\r?\n/);
+			stdoutBuffer = parts.pop() ?? "";
+			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
+				protocolError ??= `Codex emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+				stdoutBuffer = "";
+				attempt.stop("protocol");
+				return;
+			}
+			for (const line of parts) {
+				try {
+					handleLine(line);
+				} catch (error) {
+					protocolError ??= errorMessage(error);
+					attempt.stop("protocol");
+					return;
+				}
+			}
+		});
+
+		const { code, exitSignal } = await attempt.closed;
+		attempt.dispose();
+		if (stdoutBuffer.trim()) {
+			try {
+				handleLine(stdoutBuffer);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+			}
+		}
+
+		const partialText = partial ? { partialText: partial } : {};
+		const cause = attempt.causeOf();
+		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", ...partialText };
+		if (cause === "timeout") return { status: "timeout", message: `Codex timed out ${timeoutVerb}. Run \`/bro doctor\` for setup help.`, ...partialText };
+		if (protocolError) return { status: "failure", message: withDoctor(protocolError), ...partialText };
+		if (processError) return { status: "failure", message: processStartMessage(processError as NodeJS.ErrnoException, "Codex") };
+		if (exitSignal || code === null) return { status: "failure", message: unexpectedSignalMessage(exitSignal, "Codex"), ...partialText };
+		if (terminalError) return { status: "failure", message: withDoctor(terminalError), ...partialText };
+		if (code !== 0) {
+			const detail = stderr.trim();
+			return {
+				status: "failure",
+				message: detail
+					? `Codex could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: `Codex could not ${action}. Make sure \`codex\` is installed and signed in, then run \`/bro doctor\`.`,
+				...partialText,
+			};
+		}
+		if (!sawTerminal) {
+			return { status: "failure", message: withDoctor(`Codex exited without a terminal result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), ...partialText };
+		}
+		const text = final?.trim();
+		if (!text) return { status: "failure", message: withDoctor(emptyTextMessage), ...partialText };
+		if (!isBtw) return { status: "success", text };
+		if (!threadId || (request.continuation && threadId !== request.continuation.id)) {
+			return {
+				status: "failure",
+				message: withDoctor(`Codex reported an inconsistent session id (expected ${request.continuation?.id ?? "one id"}, got ${threadId ?? "none"}).`),
+				...partialText,
+			};
+		}
+		return { status: "success", text, continuation: { id: threadId } };
+	} finally {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+type MuseEnvelope = {
+	schema_version?: unknown;
+	payload_type?: unknown;
+	stream?: { kind?: unknown; id?: unknown };
+	payload?: {
+		kind?: unknown;
+		command_id?: unknown;
+		run_stream?: { kind?: unknown; id?: unknown };
+		text?: unknown;
+		reason?: unknown;
+		correlation_facts?: { tool_name?: unknown };
+		event?: { message?: unknown };
+		command?: unknown;
+		path?: unknown;
+		file_path?: unknown;
+		query?: unknown;
+	};
+};
+
+async function executeMuse(
+	request: BackendRequest,
+	selection: { model: string; effort?: string },
+	signal: AbortSignal,
+	onProgress: BackendOnProgress | undefined,
+	killEscalationMs: number,
+	deadlineMsOverride: number | undefined,
+): Promise<BackendOutcome> {
+	const isAdvisor = request.feature === "advisor";
+	const isBtw = request.feature === "btw";
+	const full = request.access === "workspace-full";
+	const deadlineMs = deadlineMsOverride ?? (full ? 610_000 : isBtw ? 130_000 : 125_000);
+	const action = isAdvisor ? "complete the advisor consultation" : isBtw ? "answer the side question" : "simplify the response";
+	const timeoutVerb = isAdvisor ? "during the advisor consultation" : isBtw ? "during the side conversation" : "while simplifying the response";
+	const emptyTextMessage = isAdvisor ? "Muse returned no advice." : isBtw ? "Muse returned no answer for the side question." : "Muse returned no final explanation.";
+
+	if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+	const promptDirectory = await mkdtemp(join(tmpdir(), "pi-bro-muse-"));
+	let runDirectory: string | undefined;
+
+	try {
+		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+		const promptFile = join(promptDirectory, "prompt.txt");
+		await writeFile(promptFile, request.prompt, { encoding: "utf8", mode: 0o600 });
+		if (!isAdvisor && !isBtw) runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+		if (signal.aborted) return { status: "cancelled", message: "Canceled." };
+		const workspace = runDirectory ?? request.cwd!;
+
+		const args = [
+			"exec",
+			"--json",
+			"--provider", "meta",
+			"--workspace", workspace,
+			...(!isBtw ? ["--no-session-log"] : []),
+			...(full ? ["--yolo"] : ["--disable-approval", "--disable-write", "--disable-shell"]),
+			...(isBtw && request.continuation ? ["--session-id", request.continuation.id] : []),
+			"--model", selection.model,
+			...(selection.effort ? ["--reasoning-effort", selection.effort] : []),
+			"--prompt-file", promptFile,
+		];
+
+		const child = spawn("muse", args, {
+			cwd: workspace,
+			stdio: ["ignore", "pipe", "pipe"],
+			windowsHide: true,
+			detached: process.platform !== "win32",
+		});
+
+		const attempt = beginAttempt(child, signal, deadlineMs, killEscalationMs);
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let rootCommandId: string | undefined;
+		let rootRunId: string | undefined;
+		let sessionId: string | undefined;
+		let final: string | undefined;
+		let sawTerminal = false;
+		let terminalError: string | undefined;
+		let protocolError: string | undefined;
+		let stdoutBuffer = "";
+
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+
+		const handleLine = (line: string) => {
+			if (!line.trim() || attempt.causeOf()) return;
+			let envelope: MuseEnvelope;
+			try {
+				envelope = JSON.parse(line) as MuseEnvelope;
+			} catch {
+				throw new Error("Muse emitted invalid JSON output.");
+			}
+			const payload = envelope.payload;
+			if (envelope.stream?.kind === "session" && typeof envelope.stream.id === "string") {
+				if (!sessionId) sessionId = envelope.stream.id;
+			}
+			if (envelope.payload_type === "runtime.command.accepted") {
+				if (!rootCommandId && typeof payload?.command_id === "string") {
+					rootCommandId = payload.command_id;
+				}
+				return;
+			}
+			if (!rootRunId && (envelope.payload_type === "session.run.linked" || envelope.payload_type === "run.lifecycle.started")) {
+				const runStream = payload?.run_stream;
+				if (runStream?.kind === "run" && typeof runStream.id === "string") {
+					if (rootCommandId === undefined || payload?.command_id === rootCommandId) {
+						rootRunId = runStream.id;
+						if (envelope.stream?.kind === "session" && typeof envelope.stream.id === "string") {
+							sessionId = envelope.stream.id;
+						}
+					}
+				}
+				return;
+			}
+			const runStream = payload?.run_stream;
+			const isRoot = rootRunId !== undefined && runStream?.kind === "run" && runStream.id === rootRunId;
+
+			if (isAdvisor) {
+				if (envelope.payload_type === "tool.result") {
+					const facts = payload?.correlation_facts as { tool_name?: unknown } | undefined;
+					const toolName = typeof facts?.tool_name === "string" && facts.tool_name ? facts.tool_name : "tool";
+					const candidate = [payload?.text, payload?.command, payload?.path, payload?.file_path, payload?.query]
+						.find((v) => typeof v === "string" && v.trim());
+					const preview = typeof candidate === "string" ? candidate.replace(/\s+/g, " ").trim() : "";
+					const label = `${toolName}${preview ? ` ${preview}` : ""}`;
+					onProgress?.({ kind: "activity", label, timestamp: Date.now() });
+				} else if (envelope.payload_type === "task.lifecycle.status") {
+					const event = payload?.event as { message?: unknown } | undefined;
+					if (typeof event?.message === "string" && event.message.trim()) {
+						onProgress?.({ kind: "activity", label: event.message.trim(), timestamp: Date.now() });
+					}
+				}
+			} else if (isRoot && envelope.payload_type === "run.output.delta") {
+				if (typeof payload?.text === "string" && payload.text) {
+					partial += payload.text;
+					onProgress?.({ kind: "text", text: partial });
+				}
+			}
+
+			if (!isRoot) return;
+			if (envelope.payload_type === "run.terminal.completed") {
+				sawTerminal = true;
+				if (typeof payload?.text === "string") {
+					final = payload.text;
+				}
+			} else if (envelope.payload_type === "run.terminal.failed") {
+				sawTerminal = true;
+				const reason = typeof payload?.reason === "string" && payload.reason.trim() ? payload.reason.trim() : "run did not complete";
+				terminalError ??= `Muse failed: ${reason}`;
+			}
+		};
+
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdoutBuffer += chunk;
+			const parts = stdoutBuffer.split(/\r?\n/);
+			stdoutBuffer = parts.pop() ?? "";
+			if (stdoutBuffer.length > ADVISOR_MAX_STDOUT_LINE_CHARS || parts.some((line) => line.length > ADVISOR_MAX_STDOUT_LINE_CHARS)) {
+				protocolError ??= `Muse emitted a stdout line over ${ADVISOR_MAX_STDOUT_LINE_CHARS} characters; the stream is unparseable.`;
+				stdoutBuffer = "";
+				attempt.stop("protocol");
+				return;
+			}
+			for (const line of parts) {
+				try {
+					handleLine(line);
+				} catch (error) {
+					protocolError ??= errorMessage(error);
+					attempt.stop("protocol");
+					return;
+				}
+			}
+		});
+
+		const { code, exitSignal } = await attempt.closed;
+		attempt.dispose();
+		if (stdoutBuffer.trim()) {
+			try {
+				handleLine(stdoutBuffer);
+			} catch (error) {
+				protocolError ??= errorMessage(error);
+			}
+		}
+
+		const partialText = partial ? { partialText: partial } : {};
+		const cause = attempt.causeOf();
+		if (cause === "cancelled") return { status: "cancelled", message: "Canceled.", ...partialText };
+		if (cause === "timeout") return { status: "timeout", message: `Muse timed out ${timeoutVerb}. Run \`/bro doctor\` for setup help.`, ...partialText };
+		if (protocolError) return { status: "failure", message: withDoctor(protocolError), ...partialText };
+		if (processError) return { status: "failure", message: processStartMessage(processError as NodeJS.ErrnoException, "Muse") };
+		if (exitSignal || code === null) return { status: "failure", message: unexpectedSignalMessage(exitSignal, "Muse"), ...partialText };
+		if (terminalError) return { status: "failure", message: withDoctor(terminalError), ...partialText };
+		if (code !== 0) {
+			const detail = stderr.trim();
+			return {
+				status: "failure",
+				message: detail
+					? `Muse could not ${action}: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: `Muse could not ${action}. Make sure \`muse\` is installed and signed in, then run \`/bro doctor\`.`,
+				...partialText,
+			};
+		}
+		if (!sawTerminal) {
+			return { status: "failure", message: withDoctor(`Muse exited without a terminal result event${stderr.trim() ? `: ${stderr.trim()}` : "."}`), ...partialText };
+		}
+		const text = final?.trim();
+		if (!text) return { status: "failure", message: withDoctor(emptyTextMessage), ...partialText };
+		if (!isBtw) return { status: "success", text };
+		if (!sessionId || (request.continuation && sessionId !== request.continuation.id)) {
+			return {
+				status: "failure",
+				message: withDoctor(`Muse reported an inconsistent session id (expected ${request.continuation?.id ?? "one id"}, got ${sessionId ?? "none"}).`),
+				...partialText,
+			};
+		}
+		return { status: "success", text, continuation: { id: sessionId } };
+	} finally {
+		if (runDirectory) await rm(runDirectory, { recursive: true, force: true });
+		await rm(promptDirectory, { recursive: true, force: true });
+	}
+}
+
 // Single-attempt executor shared by all four features. Never retries (retries are feature-owned,
 // e.g. advisor's 3-attempt backoff in bro.ts); never spawns a pre-aborted request; on cancellation,
 // host deadline, or a protocol failure, stops the whole POSIX process group (SIGTERM, then SIGKILL
@@ -984,10 +1444,30 @@ export async function execute(
 	) return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
 	const backend = (selection as { backend?: unknown }).backend;
 	// An explicit tag guard: a stale or corrupt runtime tag must fail, never fall through to Agy.
-	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok") {
-		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude or Grok in \`/bro config\`.` };
+	if (backend !== undefined && backend !== "agy" && backend !== "claude" && backend !== "grok" && backend !== "codex" && backend !== "muse") {
+		return { status: "failure", message: `Unknown backend ${JSON.stringify(backend)}: pick Agy, Claude, Grok, Codex or Muse in \`/bro config\`.` };
 	}
 	const killEscalationMs = options?.killEscalationMs ?? DEFAULT_KILL_ESCALATION_MS;
+	if (selection.backend === "codex") {
+		// Codex btw always runs (and resumes) in the caller's workspace, even restricted.
+		if (request.feature === "btw" && !request.cwd?.trim()) {
+			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
+		}
+		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !CODEX_EFFORTS.includes(selection.effort))) {
+			return { status: "failure", message: "Unsupported Codex selection: check the model and effort (low, medium, high or xhigh)." };
+		}
+		return executeCodex(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
+	}
+	if (selection.backend === "muse") {
+		// Muse btw always runs (and resumes) in the caller's workspace, even restricted.
+		if (request.feature === "btw" && !request.cwd?.trim()) {
+			return { status: "failure", message: "Unsupported execution request: check feature access, workspace cwd and continuation." };
+		}
+		if (typeof selection.model !== "string" || !selection.model.trim() || (selection.effort !== undefined && !MUSE_EFFORTS.includes(selection.effort))) {
+			return { status: "failure", message: "Unsupported Muse selection: check the model and effort (minimal, low, medium, high, xhigh or max)." };
+		}
+		return executeMuse(request, selection, signal, onProgress, killEscalationMs, options?.deadlineMs);
+	}
 	if (selection.backend === "grok") {
 		// Grok btw always runs (and resumes) in the caller's workspace, even restricted.
 		if (request.feature === "btw" && !request.cwd?.trim()) {

package/bro.ts

@@ -23,6 +23,8 @@ import {
 	advisorFlagErrorHint,
 	CLAUDE_EFFORTS,
 	GROK_EFFORTS,
+	CODEX_EFFORTS,
+	MUSE_EFFORTS,
 	backendSupports,
 	execute as executeBackend,
 	parseBtwAgyLine,
@@ -67,13 +69,15 @@ type BtwTurn = { question: string; answer: string };
 // thread; `sessionFull` is the access mode the native session last ran in.
 type BtwThread = { turns: BtwTurn[]; conversationId?: string; full: boolean; backend?: BackendName; model?: string; context?: string; sessionFull?: boolean };
 const EFFORTS = ["default", "low", "medium", "high"] as const;
-const BACKENDS = ["agy", "claude", "grok"] as const;
+const BACKENDS = ["agy", "claude", "grok", "codex", "muse"] as const;
 type BackendName = (typeof BACKENDS)[number];
-type BroEffort = "default" | "low" | "medium" | "high" | "xhigh" | "max";
-type AgyEffort = Exclude<BroEffort, "default" | "xhigh" | "max">;
+type BroEffort = "default" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+type AgyEffort = Exclude<BroEffort, "default" | "minimal" | "xhigh" | "max">;
 type ClaudeEffort = (typeof CLAUDE_EFFORTS)[number];
-export { GROK_EFFORTS };
+export { GROK_EFFORTS, CODEX_EFFORTS, MUSE_EFFORTS };
 type GrokEffort = (typeof GROK_EFFORTS)[number];
+type CodexEffort = (typeof CODEX_EFFORTS)[number];
+type MuseEffort = (typeof MUSE_EFFORTS)[number];
 // "advisor" is a real capability (command, Agy invocation, Doctor check) like the other three;
 // see docs/plans/2026-09-19-bro-advisor-design.md. All four share one model/effort resolution,
 // override, and Doctor-check path via this single list -- there is no configuration-only tier.
@@ -99,6 +103,14 @@ export const GROK_MODELS = [
 	{ id: "grok-4.7", label: "Grok 4.7" },
 	{ id: "grok-4.7-build-fast", label: "Grok 4.7 Build Fast" },
 ] as const;
+export const CODEX_MODELS = [
+	{ id: "gpt-5.5", label: "GPT-5.5" },
+	{ id: "gpt-5.4", label: "GPT-5.4" },
+] as const;
+export const MUSE_MODELS = [
+	{ id: "muse-spark-1.3-contributor", label: "Muse Spark 1.3 Contributor" },
+	{ id: "muse-spark-1.3", label: "Muse Spark 1.3" },
+] as const;
 export { backendSupports as supportsBackend };
 type AgyModelFamily = {
 	id: string;
@@ -508,7 +520,7 @@ export async function extractWebPage(input: string, signal?: AbortSignal): Promi
 
 function parseBackend(value: unknown, context: string): BackendName {
 	if (typeof value !== "string" || !BACKENDS.some((backend) => backend === value)) {
-		throw new Error(`${context} backend must be "agy", "claude", or "grok".`);
+		throw new Error(`${context} backend must be "agy", "claude", "grok", "codex", or "muse".`);
 	}
 	return value as BackendName;
 }
@@ -525,6 +537,14 @@ function isGrokEffort(effort: unknown): effort is GrokEffort | "default" {
 	return effort === "default" || GROK_EFFORTS.some((item) => item === effort);
 }
 
+function isCodexEffort(effort: unknown): effort is CodexEffort | "default" {
+	return effort === "default" || CODEX_EFFORTS.some((item) => item === effort);
+}
+
+function isMuseEffort(effort: unknown): effort is MuseEffort | "default" {
+	return effort === "default" || MUSE_EFFORTS.some((item) => item === effort);
+}
+
 function parseModelEffortPair(value: unknown, context: string): ModelEffortPair {
 	if (!isRecord(value) || typeof value.model !== "string" || !value.model.trim()) {
 		throw new Error(`${context} must contain a model and effort set to "default", "low", "medium", or "high".`);
@@ -542,6 +562,18 @@ function parseModelEffortPair(value: unknown, context: string): ModelEffortPair
 		}
 		return { backend, model: value.model.trim(), effort: value.effort };
 	}
+	if (backend === "codex") {
+		if (!isCodexEffort(value.effort)) {
+			throw new Error(`${context} must contain a model and effort set to "default", "low", "medium", "high", or "xhigh".`);
+		}
+		return { backend, model: value.model.trim(), effort: value.effort };
+	}
+	if (backend === "muse") {
+		if (!isMuseEffort(value.effort)) {
+			throw new Error(`${context} must contain a model and effort set to "default", "minimal", "low", "medium", "high", "xhigh", or "max".`);
+		}
+		return { backend, model: value.model.trim(), effort: value.effort };
+	}
 	if (!isAgyEffort(value.effort)) {
 		throw new Error(`${context} must contain a model and effort set to "default", "low", "medium", or "high".`);
 	}
@@ -590,14 +622,25 @@ export function parseBroSettings(value: unknown): BroSettings {
 		throw new Error('Settings must contain a model and effort set to "default", "low", "medium", or "high".');
 	}
 	const backend = value.backend === undefined ? undefined : parseBackend(value.backend, "Settings");
-	const effortOk = backend === "claude" ? isClaudeEffort(value.effort) : backend === "grok" ? isGrokEffort(value.effort) : isAgyEffort(value.effort);
+	const effortOk =
+		backend === "claude"
+			? isClaudeEffort(value.effort)
+			: backend === "grok"
+				? isGrokEffort(value.effort)
+				: backend === "codex"
+					? isCodexEffort(value.effort)
+					: backend === "muse"
+						? isMuseEffort(value.effort)
+						: isAgyEffort(value.effort);
 	if (!effortOk) {
 		throw new Error(
 			backend === "claude"
 				? 'Settings must contain a model and effort set to "default", "low", "medium", "high", "xhigh", or "max".'
-				: backend === "grok"
+				: backend === "grok" || backend === "codex"
 					? 'Settings must contain a model and effort set to "default", "low", "medium", "high", or "xhigh".'
-					: 'Settings must contain a model and effort set to "default", "low", "medium", or "high".',
+					: backend === "muse"
+						? 'Settings must contain a model and effort set to "default", "minimal", "low", "medium", "high", "xhigh", or "max".'
+						: 'Settings must contain a model and effort set to "default", "low", "medium", or "high".',
 		);
 	}
 	const mode = value.mode === undefined ? DEFAULT_BRO_MODE : parseBroMode(value.mode);
@@ -649,8 +692,8 @@ export function resolveModelEffort(
 	pair: ModelEffortPair,
 	families: AgyModelFamily[],
 ): { pair: ModelEffortPair; family?: AgyModelFamily } {
-	// Claude/Grok selections never resolve through the Agy catalog; they pass through untouched.
-	if (pair.backend === "claude" || pair.backend === "grok") return { pair };
+	// Claude/Grok/Codex/Muse selections never resolve through the Agy catalog; they pass through untouched.
+	if (pair.backend === "claude" || pair.backend === "grok" || pair.backend === "codex" || pair.backend === "muse") return { pair };
 	const family = families.find((item) => item.id === pair.model || item.variants.some((variant) => variant.id === pair.model));
 	if (!family) return { pair };
 	const variant = family.variants.find((item) => item.id === pair.model);
@@ -688,17 +731,41 @@ export function resolveGrokModel(input: string): string {
 	return trimmed;
 }
 
+// Codex seeds resolve to themselves; any other non-empty string passes through
+// untouched as an explicit user-entered model ID.
+export function resolveCodexModel(input: string): string {
+	const trimmed = input.trim();
+	if (!trimmed) throw new Error("Codex model must be a non-empty model ID (gpt-5.5, gpt-5.4, or an explicit model ID).");
+	return trimmed;
+}
+
+// Muse seeds resolve to themselves; any other non-empty string passes through
+// untouched as an explicit user-entered model ID.
+export function resolveMuseModel(input: string): string {
+	const trimmed = input.trim();
+	if (!trimmed) throw new Error("Muse model must be a non-empty model ID (muse-spark-1.3-contributor, muse-spark-1.3, or an explicit model ID).");
+	return trimmed;
+}
+
 // Routes one capability's whole pair to its backend execution selection. Agy keeps the
-// existing model/effort split; Claude/Grok carry the model plus an optional effort
+// existing model/effort split; Claude/Grok/Codex/Muse carry the model plus an optional effort
 // ("default" means the CLI's own default and is omitted). Throws for an effort the
 // resolved backend does not support instead of silently sending a mismatched pair.
 export function selectionForCapability(settings: BroSettings, capability: Capability): BackendSelection {
 	const pair = capabilityPair(settings, capability);
 	const backend = capabilityBackend(settings, capability);
-	if (backend === "claude" || backend === "grok") {
-		const valid = backend === "claude" ? isClaudeEffort(pair.effort) : isGrokEffort(pair.effort);
+	if (backend === "claude" || backend === "grok" || backend === "codex" || backend === "muse") {
+		const valid =
+			backend === "claude"
+				? isClaudeEffort(pair.effort)
+				: backend === "grok"
+					? isGrokEffort(pair.effort)
+					: backend === "codex"
+						? isCodexEffort(pair.effort)
+						: isMuseEffort(pair.effort);
 		if (!valid) {
-			throw new Error(`\`${pair.effort}\` is not supported on the ${backend === "claude" ? "Claude" : "Grok"} backend. Run \`/bro config\` to fix this.`);
+			const label = backend === "claude" ? "Claude" : backend === "grok" ? "Grok" : backend === "codex" ? "Codex" : "Muse";
+			throw new Error(`\`${pair.effort}\` is not supported on the ${label} backend. Run \`/bro config\` to fix this.`);
 		}
 		return (
 			pair.effort === "default"
@@ -970,6 +1037,67 @@ async function checkGrokVersion(pi: ExtensionAPI, signal: AbortSignal): Promise<
 	}
 }
 
+async function checkCodexVersion(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("codex", ["--version"], { cwd: runDirectory, signal, timeout: 10_000 });
+		if (signal.aborted) throw new Error("Canceled.");
+		if (result.killed || result.code !== 0) {
+			const detail = result.stderr.trim() || result.stdout.trim();
+			throw new Error(
+				detail
+					? `Codex could not start: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: "Codex could not start. Make sure Codex is installed and on PATH, then run `/bro doctor`.",
+			);
+		}
+		const version = result.stdout.trim() || result.stderr.trim();
+		if (!version) throw new Error("Codex returned no version information. Update Codex, then run `/bro doctor` again.");
+		return version;
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+// Auth status only: a version/auth answer without a model request. A passing answer here
+// says the CLI starts and reports signed-in state -- it does not imply connectivity.
+async function checkCodexAuth(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("codex", ["login", "status"], { cwd: runDirectory, signal, timeout: 15_000 });
+		if (signal.aborted) throw new Error("Canceled.");
+		if (result.killed || result.code !== 0) {
+			const detail = result.stderr.trim() || result.stdout.trim();
+			throw new Error(detail ? `Codex auth status: ${detail}` : "Codex is not logged in. Run `codex login`.");
+		}
+		const status = result.stdout.trim() || result.stderr.trim();
+		if (!status || !/logged in/i.test(status)) throw new Error("Codex is not logged in. Run `codex login`.");
+		return "authentication configured (not a connectivity test)";
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+async function checkMuseVersion(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("muse", ["--version"], { cwd: runDirectory, signal, timeout: 10_000 });
+		if (signal.aborted) throw new Error("Canceled.");
+		if (result.killed || result.code !== 0) {
+			const detail = result.stderr.trim() || result.stdout.trim();
+			throw new Error(
+				detail
+					? `Muse could not start: ${detail}\n\nRun \`/bro doctor\` for setup help.`
+					: "Muse could not start. Make sure Muse is installed and on PATH, then run `/bro doctor`.",
+			);
+		}
+		const version = result.stdout.trim() || result.stderr.trim();
+		if (!version) throw new Error("Muse returned no version information. Update Muse, then run `/bro doctor` again.");
+		return version;
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
 async function checkAgyUsage(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
 	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 	try {
@@ -1016,11 +1144,13 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 		fail("Prompt", error);
 	}
 
-	// Probe only the backends some feature actually selects: a Claude/Grok-only setup never
+	// Probe only the backends some feature actually selects: a Claude/Grok/Codex/Muse-only setup never
 	// requires Agy to be installed, and vice versa.
 	const agyInUse = !settings || capabilityBackend(settings, "explain") === "agy" || capabilityBackend(settings, "show") === "agy" || capabilityBackend(settings, "btw") === "agy" || capabilityBackend(settings, "advisor") === "agy" || (settings.backend ?? "agy") === "agy";
 	const claudeInUse = !!settings && (capabilityBackend(settings, "explain") === "claude" || capabilityBackend(settings, "show") === "claude" || capabilityBackend(settings, "btw") === "claude" || capabilityBackend(settings, "advisor") === "claude" || settings.backend === "claude");
 	const grokInUse = !!settings && (capabilityBackend(settings, "explain") === "grok" || capabilityBackend(settings, "show") === "grok" || capabilityBackend(settings, "btw") === "grok" || capabilityBackend(settings, "advisor") === "grok" || settings.backend === "grok");
+	const codexInUse = !!settings && (capabilityBackend(settings, "explain") === "codex" || capabilityBackend(settings, "show") === "codex" || capabilityBackend(settings, "btw") === "codex" || capabilityBackend(settings, "advisor") === "codex" || settings.backend === "codex");
+	const museInUse = !!settings && (capabilityBackend(settings, "explain") === "muse" || capabilityBackend(settings, "show") === "muse" || capabilityBackend(settings, "btw") === "muse" || capabilityBackend(settings, "advisor") === "muse" || settings.backend === "muse");
 
 	let agyStarted = false;
 	if (agyInUse) {
@@ -1087,6 +1217,38 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 		pass("Grok", "not probed — no feature selects the Grok backend");
 	}
 
+	// Version and auth status only, never a model request.
+	if (codexInUse) {
+		try {
+			pass("Codex", await checkCodexVersion(pi, signal));
+		} catch (error) {
+			if (signal.aborted) throw error;
+			fail("Codex", error);
+		}
+		try {
+			pass("Codex auth", await checkCodexAuth(pi, signal));
+		} catch (error) {
+			if (signal.aborted) throw error;
+			fail("Codex auth", error);
+		}
+	} else {
+		pass("Codex", "not probed — no feature selects the Codex backend");
+	}
+
+	// Version only, never a model request. No Muse auth probe exists, so a passing
+	// version says the CLI starts — it says nothing about auth or connectivity.
+	if (museInUse) {
+		try {
+			pass("Muse", await checkMuseVersion(pi, signal));
+		} catch (error) {
+			if (signal.aborted) throw error;
+			fail("Muse", error);
+		}
+		pass("Muse auth", "unverified — no auth probe exists (version does not imply auth or connectivity)");
+	} else {
+		pass("Muse", "not probed — no feature selects the Muse backend");
+	}
+
 	if (settings) {
 		const defaultBackend = settings.backend ?? "agy";
 		if (defaultBackend === "claude") {
@@ -1107,6 +1269,24 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 			} else {
 				pass("Reasoning effort", settings.effort);
 			}
+		} else if (defaultBackend === "codex") {
+			pass("Selected model", `codex \`${settings.model}\``);
+			if (!isCodexEffort(settings.effort)) {
+				fail("Reasoning effort", `\`${settings.effort}\` is unsupported. Run \`/bro config\` to choose another.`);
+			} else if (settings.effort === "default") {
+				pass("Reasoning effort", "built into the selected model");
+			} else {
+				pass("Reasoning effort", settings.effort);
+			}
+		} else if (defaultBackend === "muse") {
+			pass("Selected model", `muse \`${settings.model}\``);
+			if (!isMuseEffort(settings.effort)) {
+				fail("Reasoning effort", `\`${settings.effort}\` is unsupported. Run \`/bro config\` to choose another.`);
+			} else if (settings.effort === "default") {
+				pass("Reasoning effort", "built into the selected model");
+			} else {
+				pass("Reasoning effort", settings.effort);
+			}
 		} else if (models) {
 			const current = resolveCatalogSettings(settings, models);
 			if (!current.family) {
@@ -1159,6 +1339,40 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 				);
 				continue;
 			}
+			if (backend === "codex") {
+				if (!backendSupports("codex", capability)) {
+					fail(label, `\`${capability}\` is not supported on the Codex backend for this capability. Run \`/bro config\` to give it another backend.`);
+					continue;
+				}
+				if (!isCodexEffort(pair.effort)) {
+					fail(label, `\`${pair.effort}\` is unsupported for codex \`${pair.model}\`. Run \`/bro config\` to fix this.`);
+					continue;
+				}
+				pass(
+					label,
+					override
+						? `override codex \`${pair.model}\`${pair.effort === "default" ? "" : ` (${pair.effort})`}`
+						: `codex \`${pair.model}\`${pair.effort === "default" ? "" : ` (${pair.effort})`} · using the shared default`,
+				);
+				continue;
+			}
+			if (backend === "muse") {
+				if (!backendSupports("muse", capability)) {
+					fail(label, `\`${capability}\` is not supported on the Muse backend for this capability. Run \`/bro config\` to give it another backend.`);
+					continue;
+				}
+				if (!isMuseEffort(pair.effort)) {
+					fail(label, `\`${pair.effort}\` is unsupported for muse \`${pair.model}\`. Run \`/bro config\` to fix this.`);
+					continue;
+				}
+				pass(
+					label,
+					override
+						? `override muse \`${pair.model}\`${pair.effort === "default" ? "" : ` (${pair.effort})`}`
+						: `muse \`${pair.model}\`${pair.effort === "default" ? "" : ` (${pair.effort})`} · using the shared default`,
+				);
+				continue;
+			}
 			if (!models) continue;
 			const resolved = resolveCapabilitySettings(settings, capability, models);
 			if (!resolved.family) {
@@ -1193,13 +1407,17 @@ async function doctorReport(pi: ExtensionAPI, ctx: ExtensionCommandContext, sign
 		pass("Advisor compatibility", "Claude backend — no Agy version floor applies");
 	} else if (settings && capabilityBackend(settings, "advisor") === "grok") {
 		pass("Advisor compatibility", "Grok backend — no Agy version floor applies; auth/connectivity unverified (no probe)");
+	} else if (settings && capabilityBackend(settings, "advisor") === "codex") {
+		pass("Advisor compatibility", "Codex backend — no Agy version floor applies");
+	} else if (settings && capabilityBackend(settings, "advisor") === "muse") {
+		pass("Advisor compatibility", "Muse backend — no Agy version floor applies; auth/connectivity unverified (no probe)");
 	} else if (agyVersion && advisorAgyCompatible(agyVersion)) pass("Advisor compatibility", ADVISOR_COMPATIBILITY);
 	else if (agyVersion) fail("Advisor compatibility", `installed \`${agyVersion}\`; requires Agy >=1.1.15. Run \`agy update\`.`);
 
 	return `# Bro doctor\n\n${lines.join("\n")}\n\n**${failed ? "Bro needs attention." : "Bro is ready."}**\n\n${
 		failed
 			? "Fix the failed items, then press **R** to check again."
-			: "No assistant response was sent and no model turn was run. Version/auth checks do not imply connectivity (Grok auth is unverified — no probe exists)."
+			: "No assistant response was sent and no model turn was run. Version/auth checks do not imply connectivity (Grok and Muse auth are unverified — no probe exists)."
 	}`;
 }
 
@@ -1787,7 +2005,7 @@ export function advisorAttemptLabel(details: AdvisorToolDetails): string {
 		return `Bro advisor · ${details.model ?? "unknown model"} · ${details.attempt} attempt${details.attempt === 1 ? "" : "s"} · ${Math.ceil((details.durationMs ?? details.elapsedMs) / 1_000)}s`;
 	}
 	const latest = details.activity?.at(-1);
-	const backendLabel = details.backend === "claude" ? "Claude" : details.backend === "grok" ? "Grok" : "Agy";
+	const backendLabel = details.backend === "claude" ? "Claude" : details.backend === "grok" ? "Grok" : details.backend === "codex" ? "Codex" : details.backend === "muse" ? "Muse" : "Agy";
 	// "last reported" + freshness, never a claim about what the backend is doing right now and never
 	// "stalled" -- silence since lastActivityAt is not itself evidence of a stuck run.
 	const activityLabel = latest
@@ -1807,10 +2025,12 @@ function showTurnsValues(current: number): string[] {
 // falsely healthy for an unavailable model), and flags a stored effort that isn't one of the
 // resolved family's supported efforts instead of silently showing it as if it were valid.
 function effortDisplay(resolved: { pair: ModelEffortPair; family?: AgyModelFamily }, backend: BackendName): string {
-	// Claude/Grok selections never touch the Agy catalog: the stored effort is valid exactly
+	// Claude/Grok/Codex/Muse selections never touch the Agy catalog: the stored effort is valid exactly
 	// when it is one of that backend's levels (or "default" for the CLI's own default).
 	if (backend === "claude") return isClaudeEffort(resolved.pair.effort) ? resolved.pair.effort : `${resolved.pair.effort} (unsupported)`;
 	if (backend === "grok") return isGrokEffort(resolved.pair.effort) ? resolved.pair.effort : `${resolved.pair.effort} (unsupported)`;
+	if (backend === "codex") return isCodexEffort(resolved.pair.effort) ? resolved.pair.effort : `${resolved.pair.effort} (unsupported)`;
+	if (backend === "muse") return isMuseEffort(resolved.pair.effort) ? resolved.pair.effort : `${resolved.pair.effort} (unsupported)`;
 	if (!resolved.family) return "unavailable";
 	const fixed = !resolved.family.efforts.length;
 	const valid = fixed ? resolved.pair.effort === "default" : resolved.family.efforts.includes(resolved.pair.effort as AgyEffort);
@@ -1818,7 +2038,7 @@ function effortDisplay(resolved: { pair: ModelEffortPair; family?: AgyModelFamil
 	return fixed ? "fixed" : resolved.pair.effort;
 }
 
-// Model-picker values that switch backend carry a "claude:"/"grok:" prefix so one
+// Model-picker values that switch backend carry a "claude:"/"grok:"/"codex:"/"muse:" prefix so one
 // atomic picker commit changes backend+model together -- cancelling the picker (Esc)
 // leaves both unchanged via the existing submenu-cancel path.
 const CLAUDE_OPTION_PREFIX = "claude:";
@@ -1833,11 +2053,27 @@ function parseGrokOption(value: string): string | undefined {
 		? value.slice(GROK_OPTION_PREFIX.length)
 		: undefined;
 }
-function parseBackendOption(value: string): { backend: "claude" | "grok"; id: string } | undefined {
+const CODEX_OPTION_PREFIX = "codex:";
+function parseCodexOption(value: string): string | undefined {
+	return value.startsWith(CODEX_OPTION_PREFIX) && value.length > CODEX_OPTION_PREFIX.length
+		? value.slice(CODEX_OPTION_PREFIX.length)
+		: undefined;
+}
+const MUSE_OPTION_PREFIX = "muse:";
+function parseMuseOption(value: string): string | undefined {
+	return value.startsWith(MUSE_OPTION_PREFIX) && value.length > MUSE_OPTION_PREFIX.length
+		? value.slice(MUSE_OPTION_PREFIX.length)
+		: undefined;
+}
+function parseBackendOption(value: string): { backend: "claude" | "grok" | "codex" | "muse"; id: string } | undefined {
 	const claudeId = parseClaudeOption(value);
 	if (claudeId !== undefined) return { backend: "claude", id: claudeId };
 	const grokId = parseGrokOption(value);
 	if (grokId !== undefined) return { backend: "grok", id: grokId };
+	const codexId = parseCodexOption(value);
+	if (codexId !== undefined) return { backend: "codex", id: codexId };
+	const museId = parseMuseOption(value);
+	if (museId !== undefined) return { backend: "muse", id: museId };
 	return undefined;
 }
 
@@ -1877,7 +2113,7 @@ export function createConfigModal(
 					value: family.id,
 					label: `${family.label}${family.efforts.length ? "" : " · fixed effort"}`,
 				})),
-				// Claude/Grok entries stay last so existing Agy keyboard navigation is unaffected.
+				// Alternative CLI entries stay last so existing Agy keyboard navigation is unaffected.
 				...CLAUDE_MODELS.map((model) => ({
 					value: `${CLAUDE_OPTION_PREFIX}${model.id}`,
 					label: `${model.label} · claude`,
@@ -1886,13 +2122,33 @@ export function createConfigModal(
 					value: `${GROK_OPTION_PREFIX}${model.id}`,
 					label: `${model.label} · grok`,
 				})),
+				...CODEX_MODELS.map((model) => ({
+					value: `${CODEX_OPTION_PREFIX}${model.id}`,
+					label: `${model.label} · codex`,
+				})),
+				...MUSE_MODELS.map((model) => ({
+					value: `${MUSE_OPTION_PREFIX}${model.id}`,
+					label: `${model.label} · muse`,
+				})),
 			];
 			options.push({ value: "__claude_custom__", label: "Claude · custom model ID…" });
 			options.push({ value: "__grok_custom__", label: "Grok · custom model ID…" });
+			options.push({ value: "__codex_custom__", label: "Codex · custom model ID…" });
+			options.push({ value: "__muse_custom__", label: "Muse · custom model ID…" });
 			const input = new Input();
-			let enteringBackend: "claude" | "grok" | undefined;
+			let enteringBackend: "claude" | "grok" | "codex" | "muse" | undefined;
 			input.onSubmit = (value) => {
-				if (value.trim() && enteringBackend) pickerDone(`${enteringBackend === "claude" ? CLAUDE_OPTION_PREFIX : GROK_OPTION_PREFIX}${value.trim()}`);
+				if (value.trim() && enteringBackend) {
+					const prefix =
+						enteringBackend === "claude"
+							? CLAUDE_OPTION_PREFIX
+							: enteringBackend === "grok"
+								? GROK_OPTION_PREFIX
+								: enteringBackend === "codex"
+									? CODEX_OPTION_PREFIX
+									: MUSE_OPTION_PREFIX;
+					pickerDone(`${prefix}${value.trim()}`);
+				}
 			};
 			const picker = new SelectList(options, Math.min(options.length, 8), getSelectListTheme());
 			const selectedIndex = capability && current === "Default" ? 0 : options.findIndex((option) => option.value === current);
@@ -1900,11 +2156,14 @@ export function createConfigModal(
 			picker.onSelect = (item) => {
 				if (item.value === "__claude_custom__") { enteringBackend = "claude"; tui.requestRender(); }
 				else if (item.value === "__grok_custom__") { enteringBackend = "grok"; tui.requestRender(); }
+				else if (item.value === "__codex_custom__") { enteringBackend = "codex"; tui.requestRender(); }
+				else if (item.value === "__muse_custom__") { enteringBackend = "muse"; tui.requestRender(); }
 				else pickerDone(item.value);
 			};
 			picker.onCancel = () => pickerDone();
+			const customLabel = () => enteringBackend === "claude" ? "Claude" : enteringBackend === "grok" ? "Grok" : enteringBackend === "codex" ? "Codex" : "Muse";
 			return {
-				render: (width: number) => enteringBackend ? [`${enteringBackend === "claude" ? "Claude" : "Grok"} model ID (Enter saves, Esc cancels)`, ...input.render(width)] : picker.render(width),
+				render: (width: number) => enteringBackend ? [`${customLabel()} model ID (Enter saves, Esc cancels)`, ...input.render(width)] : picker.render(width),
 				invalidate: () => { picker.invalidate(); input.invalidate(); },
 				handleInput: (data: string) => {
 					if (enteringBackend && matchesKey(data, "escape")) pickerDone();
@@ -1945,9 +2204,29 @@ export function createConfigModal(
 		function refresh(): void {
 			const defaultBackend = settings.backend ?? "agy";
 			const def = resolveModelEffort({ backend: settings.backend, model: settings.model, effort: settings.effort }, families);
-			modelItem.currentValue = defaultBackend === "claude" ? `${CLAUDE_OPTION_PREFIX}${settings.model}` : defaultBackend === "grok" ? `${GROK_OPTION_PREFIX}${settings.model}` : (def.family?.id ?? settings.model);
+			modelItem.currentValue =
+				defaultBackend === "claude"
+					? `${CLAUDE_OPTION_PREFIX}${settings.model}`
+					: defaultBackend === "grok"
+						? `${GROK_OPTION_PREFIX}${settings.model}`
+						: defaultBackend === "codex"
+							? `${CODEX_OPTION_PREFIX}${settings.model}`
+							: defaultBackend === "muse"
+								? `${MUSE_OPTION_PREFIX}${settings.model}`
+								: (def.family?.id ?? settings.model);
 			effortItem.currentValue = effortDisplay(def, defaultBackend);
-			effortItem.values = defaultBackend === "claude" ? ["default", ...CLAUDE_EFFORTS] : defaultBackend === "grok" ? ["default", ...GROK_EFFORTS] : def.family?.efforts.length ? [...def.family.efforts] : undefined;
+			effortItem.values =
+				defaultBackend === "claude"
+					? ["default", ...CLAUDE_EFFORTS]
+					: defaultBackend === "grok"
+						? ["default", ...GROK_EFFORTS]
+						: defaultBackend === "codex"
+							? ["default", ...CODEX_EFFORTS]
+							: defaultBackend === "muse"
+								? ["default", ...MUSE_EFFORTS]
+								: def.family?.efforts.length
+									? [...def.family.efforts]
+									: undefined;
 			modeItem.currentValue = settings.mode;
 			showTurnsItem.currentValue = String(settings.showTurns);
 			showTurnsItem.values = showTurnsValues(settings.showTurns);
@@ -1963,9 +2242,24 @@ export function createConfigModal(
 						? `${CLAUDE_OPTION_PREFIX}${override.model}`
 						: backend === "grok"
 							? `${GROK_OPTION_PREFIX}${override.model}`
-							: (resolved.family?.id ?? override.model);
+							: backend === "codex"
+								? `${CODEX_OPTION_PREFIX}${override.model}`
+								: backend === "muse"
+									? `${MUSE_OPTION_PREFIX}${override.model}`
+									: (resolved.family?.id ?? override.model);
 				rows.effort.currentValue = backendSupports(backend, capability) ? effortDisplay(resolved, backend) : "unsupported backend";
-				rows.effort.values = backend === "claude" ? ["default", ...CLAUDE_EFFORTS] : backend === "grok" ? ["default", ...GROK_EFFORTS] : resolved.family?.efforts.length ? [...resolved.family.efforts] : undefined;
+				rows.effort.values =
+					backend === "claude"
+						? ["default", ...CLAUDE_EFFORTS]
+						: backend === "grok"
+							? ["default", ...GROK_EFFORTS]
+							: backend === "codex"
+								? ["default", ...CODEX_EFFORTS]
+								: backend === "muse"
+									? ["default", ...MUSE_EFFORTS]
+									: resolved.family?.efforts.length
+										? [...resolved.family.efforts]
+										: undefined;
 			}
 		}
 		refresh();
@@ -2025,9 +2319,15 @@ export function createConfigModal(
 					if (switched.backend === "claude") {
 						const effort = settings.backend === "claude" && isClaudeEffort(settings.effort) ? settings.effort : "default";
 						settings = { ...settings, backend: "claude", model: resolveClaudeModel(switched.id), effort };
-					} else {
+					} else if (switched.backend === "grok") {
 						const effort = settings.backend === "grok" && isGrokEffort(settings.effort) ? settings.effort : "default";
 						settings = { ...settings, backend: "grok", model: resolveGrokModel(switched.id), effort };
+					} else if (switched.backend === "codex") {
+						const effort = settings.backend === "codex" && isCodexEffort(settings.effort) ? settings.effort : "default";
+						settings = { ...settings, backend: "codex", model: resolveCodexModel(switched.id), effort };
+					} else {
+						const effort = settings.backend === "muse" && isMuseEffort(settings.effort) ? settings.effort : "default";
+						settings = { ...settings, backend: "muse", model: resolveMuseModel(switched.id), effort };
 					}
 				} else {
 					const family = findFamily(newValue);
@@ -2044,6 +2344,12 @@ export function createConfigModal(
 				} else if ((settings.backend ?? "agy") === "grok") {
 					if (!isGrokEffort(newValue)) return;
 					settings = { ...settings, effort: newValue };
+				} else if ((settings.backend ?? "agy") === "codex") {
+					if (!isCodexEffort(newValue)) return;
+					settings = { ...settings, effort: newValue };
+				} else if ((settings.backend ?? "agy") === "muse") {
+					if (!isMuseEffort(newValue)) return;
+					settings = { ...settings, effort: newValue };
 				} else {
 					// Effort-only edit: pin the resolved family's canonical id, same reasoning as the
 					// capability-override effort-only edit below -- otherwise a shared default created
@@ -2076,12 +2382,24 @@ export function createConfigModal(
 									model: resolveClaudeModel(switched.id),
 									effort: capabilityBackend(settings, capability) === "claude" && isClaudeEffort(currentEffort) ? currentEffort : "default",
 								});
-							} else {
+							} else if (switched.backend === "grok") {
 								settings = withCapabilityOverride(settings, capability, {
 									backend: "grok",
 									model: resolveGrokModel(switched.id),
 									effort: capabilityBackend(settings, capability) === "grok" && isGrokEffort(currentEffort) ? currentEffort : "default",
 								});
+							} else if (switched.backend === "codex") {
+								settings = withCapabilityOverride(settings, capability, {
+									backend: "codex",
+									model: resolveCodexModel(switched.id),
+									effort: capabilityBackend(settings, capability) === "codex" && isCodexEffort(currentEffort) ? currentEffort : "default",
+								});
+							} else {
+								settings = withCapabilityOverride(settings, capability, {
+									backend: "muse",
+									model: resolveMuseModel(switched.id),
+									effort: capabilityBackend(settings, capability) === "muse" && isMuseEffort(currentEffort) ? currentEffort : "default",
+								});
 							}
 						} else {
 							const family = findFamily(newValue);
@@ -2104,6 +2422,16 @@ export function createConfigModal(
 					const existing = capabilityOverride(settings, capability);
 					const model = existing?.model ?? settings.model;
 					settings = withCapabilityOverride(settings, capability, { backend: "grok", model, effort: newValue });
+				} else if (capabilityBackend(settings, capability) === "codex") {
+					if (!isCodexEffort(newValue)) return;
+					const existing = capabilityOverride(settings, capability);
+					const model = existing?.model ?? settings.model;
+					settings = withCapabilityOverride(settings, capability, { backend: "codex", model, effort: newValue });
+				} else if (capabilityBackend(settings, capability) === "muse") {
+					if (!isMuseEffort(newValue)) return;
+					const existing = capabilityOverride(settings, capability);
+					const model = existing?.model ?? settings.model;
+					settings = withCapabilityOverride(settings, capability, { backend: "muse", model, effort: newValue });
 				} else {
 					// Effort-only edit: pin the resolved family's canonical id, never whatever raw
 					// string happens to sit in settings.model/override.model (which — for a shared
@@ -2173,7 +2501,7 @@ export async function showBroConfigModal(ctx: ExtensionCommandContext, pi: Exten
 		families = await listAgyModels(pi);
 	} catch (error) {
 		families = [];
-		ctx.ui.notify("Agy model catalog unavailable — showing Claude/Grok settings without Agy choices.", "warning");
+		ctx.ui.notify("Agy model catalog unavailable — showing other backend settings without Agy choices.", "warning");
 	}
 	await ctx.ui.custom<void>(createConfigModal(settings, families, writeSettings), {
 		overlay: true,
@@ -2705,7 +3033,7 @@ export function toggleBtwMode(thread: BtwThread): void {
 	thread.full = !thread.full;
 }
 
-// Claude and Grok run btw in the workspace for both modes and resume one native session across
+// Claude, Grok, Codex, and Muse run btw in the workspace for both modes and resume one native session across
 // /mode switches. An Agy conversation stays bound to the workspace it started in (a sandbox scratch
 // dir vs. the repo), so an access change drops it; the next turn reseeds a fresh native session
 // with the main-session context and the whole thread.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "An Earendil Pi extension that explains pasted text, assistant responses, local documents, public webpages, and recent session turns (as shapes) in a context-isolated window, opens a sandboxed side conversation with /bro btw, and provides a second-opinion advisor tool for executor agents.",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,9 @@
     "btw",
     "side-conversation",
     "advisor",
-    "second-opinion"
+    "second-opinion",
+    "codex",
+    "muse"
   ],
   "files": [
     "bro.ts",
@@ -50,7 +52,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && node --test prompt.test.ts backend.test.ts claude.test.ts grok.test.ts settings.test.ts benchmark/*.test.ts && sh ./smoke-test.sh",
+    "test": "npm run typecheck && node --test prompt.test.ts backend.test.ts claude.test.ts grok.test.ts codex.test.ts muse.test.ts settings.test.ts benchmark/*.test.ts && sh ./smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",
@@ -62,20 +64,21 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.2 <1",
-    "@earendil-works/pi-tui": ">=0.84.2 <1"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
     "@earendil-works/pi-tui": "0.84.2",
     "@types/node": "^24.0.0",
+    "typebox": "1.3.7",
     "typescript": "6.0.2"
   },
   "dependencies": {
     "defuddle": "0.19.2",
     "linkedom": "0.18.13",
     "mammoth": "^1.12.1",
-    "typebox": "1.3.7",
     "unpdf": "^1.8.1"
   }
 }