feat(model): switch between provider/model mid-session (/model, /models, picker)

Switching models used to require restarting with CODEBASE_PROVIDER /
CODEBASE_MODEL env vars. Ship a real switching path now that the proxy
exposes a live model list:

- /model with no args opens an inline picker over the input row. ↑↓ to
  navigate, Enter to commit, r to reset to Codebase Auto, Esc to cancel.
- /model <id> or /model <provider>:<id> switches directly (great for
  muscle memory once you know the id).
- Aliases for common picks: sonnet, opus, haiku, gpt-5, gpt-4o, llama.
- /model auto resets to the default.
- /models lists everything your account can access, grouped by provider,
  with the active model marked.

Mechanically: the agent bundle is now state (not a memo) inside ChatApp,
so /model can abort the current run, snapshot state.messages, rebuild
the bundle with the new model + existing transcript via a new
modelOverride + initialMessages on createAgent, and swap it in via
setBundle. The reducer gets a "model-switched" action that updates
state.model and clears per-agent execution state (tools, streaming,
error) without nuking the conversation.

The choice persists to ~/.codebase/config.json (new `model` field on
Config), so next launch defaults to your last pick. ConfigStore grows
preferredModel() + setPreferredModel() to read/write that field while
preserving every other field in the user config file.

BYOK users get a graceful fallback message — there's no central model
list to fetch for arbitrary upstreams, so /model and /models tell them
to set env vars at launch instead of opening an empty overlay.

Author: halfaipg

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codebase-cli",
-	"version": "2.0.0-pre.45",
+	"version": "2.0.0-pre.46",
 	"description": "Codebase CLI — a TypeScript coding agent on the pi-mono runtime. OAuth-aware, any LLM provider, single install.",
 	"keywords": [
 		"ai",

src/agent/agent.ts

@@ -64,6 +64,20 @@ export interface CreateAgentOptions {
 	 * Production code never sets this.
 	 */
 	configOverride?: { model: ResolvedConfig["model"]; apiKey: string; source: ResolvedConfig["source"] };
+	/**
+	 * Runtime model override for proxy/OAuth sessions. Lets the user swap
+	 * models via /model without restarting. Format: `{ provider?, modelId }`.
+	 * Provider is optional — when omitted, the model id is sent verbatim
+	 * through the proxy and the backend's registry resolves it.
+	 */
+	modelOverride?: { provider?: string; modelId: string };
+	/**
+	 * Seed the agent's transcript from an in-memory message list rather
+	 * than from `~/.codebase/sessions/`. Used by the runtime model switch:
+	 * we rebuild the agent with the existing conversation so the user
+	 * doesn't lose context, but we don't want to disk-roundtrip.
+	 */
+	initialMessages?: AgentMessage[];
 }
 
 export interface AgentBundle {
@@ -98,10 +112,19 @@ export interface AgentBundle {
 }
 
 export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
-	const { model, apiKey, source } = opts.configOverride ?? resolveConfig();
 	const cwd = opts.cwd ?? process.cwd();
 	const systemPrompt = opts.systemPrompt ?? buildSystemPrompt(cwd);
 
+	// Persisted model preference from `~/.codebase/config.json` (set via
+	// `/model`) seeds the override when the caller hasn't passed one
+	// explicitly. Explicit runtime overrides still win.
+	const persistedConfig = new ConfigStore({ cwd });
+	const persistedModel = persistedConfig.preferredModel();
+	const effectiveOverride =
+		opts.modelOverride ??
+		(persistedModel?.modelId ? { provider: persistedModel.provider, modelId: persistedModel.modelId } : undefined);
+	const { model, apiKey, source } = opts.configOverride ?? resolveConfig({ modelOverride: effectiveOverride });
+
 	// OAuth-sourced credentials rotate ~hourly; build a refresh-aware getter
 	// so the agent never sends a stale access token after the first refresh
 	// window. BYOK / explicit / auto sources use the static key passed in.
@@ -111,7 +134,7 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 			: null;
 	const getApiKey = tokenManager ? () => tokenManager.getAccessToken() : () => apiKey;
 
-	const config = new ConfigStore({ cwd });
+	const config = persistedConfig;
 	const permissions = new PermissionStore({
 		allowPatterns: config.allowPatterns(),
 		denyPatterns: config.denyPatterns(),
@@ -159,7 +182,7 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 			model,
 			systemPrompt: fullSystemPrompt,
 			tools: buildTools(toolContext),
-			messages: resumed?.messages ?? [],
+			messages: opts.initialMessages ?? resumed?.messages ?? [],
 		},
 		getApiKey: () => apiKey,
 		transformContext: async (messages, signal) => {
@@ -321,6 +344,6 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		diagnostics,
 		subscribe,
 		resumedFrom: resumed ? { updatedAt: resumed.updatedAt, messageCount: resumed.messages.length } : undefined,
-		resumedMessages: resumed?.messages ?? [],
+		resumedMessages: opts.initialMessages ?? resumed?.messages ?? [],
 	};
 }

src/agent/config.ts

@@ -58,12 +58,20 @@ export class ConfigError extends Error {}
 export interface ResolveConfigOptions {
 	env?: NodeJS.ProcessEnv;
 	credentials?: CredentialsStore;
+	/**
+	 * Runtime model override. When set on an OAuth/proxy session, replaces
+	 * the resolved model id (and optionally provider) so a user can swap
+	 * mid-session via `/model <id>` without restarting. Ignored when no
+	 * proxy session is active.
+	 */
+	modelOverride?: { provider?: string; modelId: string };
 }
 
 export function resolveConfig(envOrOpts: NodeJS.ProcessEnv | ResolveConfigOptions = process.env): ResolvedConfig {
 	const opts = isProcessEnv(envOrOpts) ? { env: envOrOpts } : envOrOpts;
 	const env = opts.env ?? process.env;
 	const credentials = opts.credentials ?? new CredentialsStore();
+	const override = opts.modelOverride;
 
 	// 1. Saved credentials. Routing depends on the source:
 	//    - codebase / manual → proxy through codebase.design
@@ -75,7 +83,7 @@ export function resolveConfig(envOrOpts: NodeJS.ProcessEnv | ResolveConfigOption
 			const byok = buildByokConfig(creds.provider as KnownProvider, creds.accessToken);
 			if (byok) return byok;
 		} else if (useProxy) {
-			const proxied = buildProxiedConfig(env, creds.accessToken);
+			const proxied = buildProxiedConfig(env, creds.accessToken, override);
 			if (proxied) return proxied;
 		}
 	}
@@ -165,21 +173,28 @@ export function resolveConfig(envOrOpts: NodeJS.ProcessEnv | ResolveConfigOption
  * the bearer scope on the token, so this works for any model the
  * user's account has access to.
  */
-function buildProxiedConfig(env: NodeJS.ProcessEnv, accessToken: string): ResolvedConfig | null {
-	const explicitProvider = env.CODEBASE_PROVIDER as KnownProvider | undefined;
-	const explicitModel = env.CODEBASE_MODEL;
+function buildProxiedConfig(
+	env: NodeJS.ProcessEnv,
+	accessToken: string,
+	override?: { provider?: string; modelId: string },
+): ResolvedConfig | null {
+	// Runtime override (set via /model) wins over env vars wins over the default.
+	const explicitProvider = (override?.provider ?? env.CODEBASE_PROVIDER) as KnownProvider | undefined;
+	const explicitModel = override?.modelId ?? env.CODEBASE_MODEL;
 	const proxyBase = (env.CODEBASE_PROXY_BASE_URL ?? DEFAULT_PROXY_BASE).replace(/\/+$/, "");
 
-	// Default: "Codebase Auto" — synthesized openai-compat model.
-	// Can't use pi-ai's registry here because "codebase" isn't a
-	// KnownProvider; clone a known chat-completions model and override.
+	// No provider + no model → "Codebase Auto" (the routed default).
+	// No provider + an explicit model id → synthesize an openai-compat model
+	// against that id. Pi-ai dispatches by `model.id` in the request body;
+	// the proxy's model registry is the gatekeeper for what actually exists.
 	if (!explicitProvider) {
 		const template = getModel("groq", "llama-3.3-70b-versatile") as Model<string> | undefined;
 		if (!template) return null;
+		const isDefault = !explicitModel;
 		const model: Model<string> = {
 			...template,
-			id: "MiniMax-M2.7",
-			name: "Codebase Auto",
+			id: explicitModel ?? "MiniMax-M2.7",
+			name: isDefault ? "Codebase Auto" : (explicitModel ?? "Codebase Auto"),
 			baseUrl: proxyBase,
 			// Override provider so the status bar and /model don't lie about
 			// where this is served from. pi-ai uses `provider` mainly for

src/agent/events.test.ts

@@ -504,3 +504,25 @@ describe("reducer · post-abort event suppression", () => {
 		expect(s.status).toBe("aborted");
 	});
 });
+
+describe("reducer · model-switched", () => {
+	it("replaces the model, clears tools/streaming/error, sets status idle, KEEPS messages", () => {
+		const prior: ChatState = {
+			...freshState(),
+			messages: [{ role: "user", content: "preserved", timestamp: 1 } as AgentMessage],
+			tools: new Map([["t1", { id: "t1", name: "shell", args: {}, status: "running", startedAt: 1 }]]),
+			streaming: { role: "assistant" } as AgentMessage,
+			status: "streaming",
+			error: "old error",
+		};
+		const newModel = { provider: "anthropic", id: "claude-sonnet-4-5", name: "Sonnet 4.5" };
+		const s = dispatch(prior, { type: "model-switched", model: newModel });
+		expect(s.model).toEqual(newModel);
+		expect(s.tools.size).toBe(0);
+		expect(s.streaming).toBeUndefined();
+		expect(s.status).toBe("idle");
+		expect(s.error).toBeUndefined();
+		// Transcript continues across model swap.
+		expect(s.messages).toHaveLength(1);
+	});
+});

src/agent/events.ts

@@ -8,7 +8,9 @@ export type Action =
 	| { type: "chat-reply"; text: string }
 	| { type: "abort" }
 	| { type: "error"; message: string }
-	| { type: "reset" };
+	| { type: "reset" }
+	/** Mid-session model swap. Keeps the transcript, refreshes model + clears agent-specific bits. */
+	| { type: "model-switched"; model: ChatState["model"] };
 
 export function initialState(model: ChatState["model"], messages: AgentMessage[] = []): ChatState {
 	return {
@@ -63,6 +65,19 @@ export function reducer(state: ChatState, action: Action): ChatState {
 		case "reset":
 			return initialState(state.model);
 
+		case "model-switched":
+			return {
+				...state,
+				model: action.model,
+				// New agent instance can't honor old tool execution state.
+				tools: new Map(),
+				streaming: undefined,
+				// Status flips to idle so the input row enables immediately
+				// even if the old agent's tail events haven't fully drained.
+				status: "idle",
+				error: undefined,
+			};
+
 		case "agent-event":
 			// When the user has aborted a turn, ignore the abandoned turn's
 			// tail events that would flip status back to thinking/idle (and

src/commands/builtins.ts

@@ -132,12 +132,128 @@ function padNum(n: number, width: number): string {
 	return n.toLocaleString().padStart(width, " ");
 }
 
+/**
+ * Friendly short-name → "<provider>:<modelId>" map. Lets a user type
+ * `/model sonnet` instead of `/model anthropic:claude-sonnet-4-5`. The
+ * actual provider availability still depends on the user's account /
+ * BYOK keys; aliases just shorten the path for the common cases.
+ */
+const MODEL_ALIASES: Record<string, string> = {
+	auto: "auto", // sentinel; resolved to null override in the handler
+	sonnet: "anthropic:claude-sonnet-4-5",
+	opus: "anthropic:claude-opus-4-1",
+	haiku: "anthropic:claude-haiku-4-5",
+	"gpt-5": "openai:gpt-5",
+	"gpt-4": "openai:gpt-4o",
+	"gpt-4o": "openai:gpt-4o",
+	llama: "groq:llama-3.3-70b-versatile",
+	"llama-3.3": "groq:llama-3.3-70b-versatile",
+};
+
+/** Parse `<provider>:<modelId>` or `<modelId>` or an alias into a model spec. */
+function parseModelSpec(raw: string): { provider?: string; modelId: string } | null {
+	const trimmed = raw.trim();
+	if (!trimmed) return null;
+	const lower = trimmed.toLowerCase();
+	if (lower === "auto" || lower === "default" || lower === "reset") return null; // signal: reset
+	const aliased = MODEL_ALIASES[lower];
+	const target = aliased && aliased !== "auto" ? aliased : trimmed;
+	const colonIdx = target.indexOf(":");
+	if (colonIdx === -1) return { modelId: target };
+	return { provider: target.slice(0, colonIdx).trim(), modelId: target.slice(colonIdx + 1).trim() };
+}
+
 const modelCmd: Command = {
 	name: "model",
-	description: "Show the current model.",
-	handler: (_args, ctx) => {
-		const m = ctx.state.model;
-		ctx.emit(`${m.provider}/${m.id} (${m.name})`);
+	description: "Show or switch the active model. `/model <id>` or `/model <provider>:<id>` to switch.",
+	handler: async (args, ctx) => {
+		const arg = args.trim();
+		if (!arg) {
+			// No-args opens the inline picker. For BYOK / non-proxy sessions
+			// there's no live model list to fetch, so print the static info
+			// instead of an empty overlay.
+			if (ctx.bundle.source !== "proxy") {
+				const m = ctx.state.model;
+				ctx.emit(`Current model: ${m.name} (${m.provider}/${m.id})`);
+				ctx.emit("BYOK session — switch via CODEBASE_PROVIDER + CODEBASE_MODEL env vars at launch.");
+				return { handled: true };
+			}
+			ctx.openModelPicker();
+			return { handled: true };
+		}
+		if (arg === "--help" || arg === "-h") {
+			ctx.emit("Usage:");
+			ctx.emit("  /model              show the active model");
+			ctx.emit("  /model <id>         switch (e.g. /model claude-sonnet-4-5)");
+			ctx.emit("  /model <prov>:<id>  switch with explicit provider (e.g. /model anthropic:claude-sonnet-4-5)");
+			ctx.emit("  /model auto         reset to the default (Codebase Auto for proxy users)");
+			ctx.emit("  /model sonnet|opus|haiku|gpt-5|llama  aliases for common picks");
+			return { handled: true };
+		}
+		const spec = parseModelSpec(arg);
+		await ctx.switchModel(spec);
+		return { handled: true };
+	},
+};
+
+const modelsCmd: Command = {
+	name: "models",
+	aliases: ["lm"],
+	description: "List models available to your account (fetched live from the proxy).",
+	handler: async (_args, ctx) => {
+		// BYOK users don't go through our proxy — there's no central
+		// "available models" endpoint for arbitrary upstreams. Tell them
+		// how to switch and bail.
+		if (ctx.bundle.source !== "proxy") {
+			ctx.emit(`Current: ${ctx.state.model.name} (${ctx.state.model.provider}/${ctx.state.model.id})`);
+			ctx.emit("BYOK session — switch by re-launching with CODEBASE_PROVIDER + CODEBASE_MODEL env vars.");
+			return { handled: true };
+		}
+		const baseUrl = (ctx.bundle.model.baseUrl ?? "").replace(/\/+$/, "");
+		if (!baseUrl) {
+			ctx.emit("(model has no baseUrl — can't query the proxy)");
+			return { handled: true };
+		}
+		try {
+			const apiKey = await ctx.bundle.agent.getApiKey?.(ctx.bundle.model.provider);
+			if (!apiKey) {
+				ctx.emit("(not signed in — run `codebase auth login`)");
+				return { handled: true };
+			}
+			const res = await fetch(`${baseUrl}/models`, {
+				headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+			});
+			if (!res.ok) {
+				ctx.emit(`(failed to fetch models: ${res.status} ${res.statusText})`);
+				return { handled: true };
+			}
+			const json = (await res.json()) as { models?: Array<{ id: string; name: string; provider: string }> };
+			const models = json.models ?? [];
+			if (models.length === 0) {
+				ctx.emit("(no models returned)");
+				return { handled: true };
+			}
+			const current = `${ctx.state.model.provider}/${ctx.state.model.id}`;
+			ctx.emit("Available models (* = active):");
+			// Group by provider so the list reads as a tree.
+			const byProvider = new Map<string, Array<{ id: string; name: string }>>();
+			for (const m of models) {
+				const arr = byProvider.get(m.provider) ?? [];
+				arr.push({ id: m.id, name: m.name });
+				byProvider.set(m.provider, arr);
+			}
+			const providers = [...byProvider.keys()].sort();
+			for (const p of providers) {
+				ctx.emit(`  ${p}:`);
+				for (const m of byProvider.get(p) ?? []) {
+					const marker = `${p}/${m.id}` === current ? "*" : " ";
+					ctx.emit(`    ${marker} ${m.id}  ${m.name === m.id ? "" : `· ${m.name}`}`);
+				}
+			}
+			ctx.emit("Switch: /model <id> · /model <provider>:<id>");
+		} catch (err) {
+			ctx.emit(`(error fetching models: ${err instanceof Error ? err.message : String(err)})`);
+		}
 		return { handled: true };
 	},
 };
@@ -595,6 +711,7 @@ export const BUILTIN_COMMANDS: readonly Command[] = [
 	session,
 	cost,
 	modelCmd,
+	modelsCmd,
 	whoami,
 	copy,
 	diff,

src/commands/registry.test.ts

@@ -10,6 +10,8 @@ function fakeCtx(overrides: Partial<CommandContext> = {}): CommandContext {
 		clearDisplay: vi.fn(),
 		exit: vi.fn(),
 		registry: new CommandRegistry(),
+		switchModel: vi.fn(async () => {}),
+		openModelPicker: vi.fn(),
 		...overrides,
 	};
 }

src/commands/types.ts

@@ -17,6 +17,18 @@ export interface CommandContext {
 	 * needing to import every command's metadata separately.
 	 */
 	registry: CommandRegistry;
+	/**
+	 * Mid-session model swap. `spec === null` resets to the default model
+	 * (Codebase Auto for proxy users). Aborts the current turn if active,
+	 * rebuilds the agent with the new model, preserves the transcript.
+	 */
+	switchModel: (spec: { provider?: string; modelId: string } | null) => Promise<void>;
+	/**
+	 * Open the inline interactive model picker. Triggered by `/model` with
+	 * no args. The picker fetches the available-models list, renders an
+	 * arrow-navigable overlay, and calls back into switchModel on Enter.
+	 */
+	openModelPicker: () => void;
 }
 
 export interface CommandResult {