Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(openai-codex): add --code-mode flag and codeMode config

Jack Rudenko0a0fb6d7076f
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 0d3bcb1d..9f57bc2c 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -10,6 +10,12 @@ import { homedir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { EFFORT_LEVELS, isEffortLevel } from "./adapters/base-api-format.js";
+import {
+ CODE_MODE_ENV_VAR,
+ CODE_MODE_SETTINGS,
+ DEFAULT_CODE_MODE_SETTING,
+ parseCodeModeSetting,
+} from "./code-mode/policy.js";
import { ENV } from "./config.js";
import { setStderrQuiet } from "./logger.js";
import {
@@ -49,7 +55,7 @@ import type {
ProbeStepState,
} from "./probe/probe-tui-app.js";
import { startProbeTui } from "./probe/probe-tui-runtime.js";
-import { getModelMapping, loadConfig, readProOnUltracode } from "./profile-config.js";
+import { getModelMapping, loadConfig, readCodeMode, readProOnUltracode } from "./profile-config.js";
import { API_KEY_MAP } from "./providers/api-key-map.js";
import { type KeyProvenance, resolveCredentialProvenance } from "./providers/api-key-provenance.js";
import { normalizeNativeModelSpec } from "./providers/claude-code-aliases.js";
@@ -264,6 +270,7 @@ export const CLAUDISH_FLAG_ARITY: Readonly<Record<string, ClaudishFlagArity>> =
"--effort-override": "value",
"--pro-on-ultracode": "none",
"--no-pro-on-ultracode": "none",
+ "--code-mode": "value",
"--accept-served-model": "none",
"--op-env": "value",
"--op": "value",
@@ -767,6 +774,16 @@ export async function parseArgs(args: string[]): Promise<ClaudishConfig> {
} else if (arg === "--no-pro-on-ultracode") {
// Escape hatch when it is enabled via config/env: off for this run.
config.proOnUltracode = false;
+ } else if (arg === "--code-mode") {
+ // Code mode for `openai-codex`: Claude Code's tools offered as one
+ // freeform `exec` tool running a script. Precedence below.
+ const cmArg = args[++i];
+ const setting = parseCodeModeSetting(cmArg);
+ if (!setting) {
+ console.error(`--code-mode requires one of ${CODE_MODE_SETTINGS.join(", ")}`);
+ process.exit(1);
+ }
+ config.codeMode = setting;
} else if (arg === "--accept-served-model") {
// Some connections serve reasoning-off with a DIFFERENT model (Kimi Code
// k3: thinking off is served by K2.8 Preview — the catalog's
@@ -1142,6 +1159,16 @@ export async function parseArgs(args: string[]): Promise<ClaudishConfig> {
}
}
+ // codeMode precedence: --code-mode flag > CLAUDISH_CODE_MODE env > project
+ // ./.claudish.json > global config.json > off. An env value other than
+ // auto/on/off states nothing and falls through to the config files.
+ if (config.codeMode === undefined) {
+ config.codeMode =
+ parseCodeModeSetting(process.env[CODE_MODE_ENV_VAR]) ??
+ readCodeMode() ??
+ DEFAULT_CODE_MODE_SETTING;
+ }
+
return config as ClaudishConfig;
}
@@ -2314,6 +2341,7 @@ ${h("OPTIONS")}
${green("--effort-override")} ${yellow("<level>")} Pin reasoning effort verbatim, skipping the per-model clamp
${green("--pro-on-ultracode")} Apply the model's catalog preset while in ultracode (opt-in)
${green("--no-pro-on-ultracode")} Force that off for this run (when enabled in config/env)
+ ${green("--code-mode")} ${yellow("<auto|on|off>")} cx@ tools as one exec script tool (default off; env CLAUDISH_CODE_MODE)
${green("--accept-served-model")} Allow a reasoning-off that the connection serves with another model
${green("-y, --auto-approve")} Skip permission prompts (--dangerously-skip-permissions)
${green("--no-auto-approve")} Explicitly enable permission prompts (default)
diff --git a/packages/cli/src/code-mode/policy.ts b/packages/cli/src/code-mode/policy.ts
new file mode 100644
index 00000000..88f1c546
--- /dev/null
+++ b/packages/cli/src/code-mode/policy.ts
@@ -0,0 +1,34 @@
+/**
+ * Code mode for `openai-codex`: the user's setting.
+ *
+ * Precedence: `--code-mode <auto|on|off>` > `CLAUDISH_CODE_MODE` > `codeMode`
+ * in the project `.claudish.json` > `codeMode` in the global config > the
+ * default. The default is `off` until code mode has passed live validation;
+ * `auto` then turns it on where the Codex `/models` endpoint reports
+ * `tool_mode: code_mode_only`.
+ *
+ * Pure: no imports from the request path, so the CLI can read it without
+ * loading anything else of code mode.
+ */
+
+/** `auto`: on where discovery says so; `on`: forced; `off`: never. */
+export type CodeModeSetting = "auto" | "on" | "off";
+
+/** Every accepted value, for parsing and for messages. */
+export const CODE_MODE_SETTINGS: readonly CodeModeSetting[] = ["auto", "on", "off"];
+
+/** The setting when nothing states one. */
+export const DEFAULT_CODE_MODE_SETTING: CodeModeSetting = "off";
+
+/** The env var that sets code mode when no flag does. */
+export const CODE_MODE_ENV_VAR = "CLAUDISH_CODE_MODE";
+
+/**
+ * `value` as a setting (trimmed, case-insensitive), or undefined when it is
+ * not one of `auto`, `on`, `off`.
+ */
+export function parseCodeModeSetting(value: unknown): CodeModeSetting | undefined {
+ if (typeof value !== "string") return undefined;
+ const v = value.trim().toLowerCase();
+ return (CODE_MODE_SETTINGS as readonly string[]).includes(v) ? (v as CodeModeSetting) : undefined;
+}
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index 1654fa96..7369523f 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -38,6 +38,7 @@ import { PLAN_POLL_INTERVAL_MS } from "../auth/quota/types.js";
import type { BehaviorEngine, BehaviorSession } from "../behavior/index.js";
import { getBehaviorEngine } from "../behavior/index.js";
import { accountKeyFromBinding } from "../code-mode/ids.js";
+import type { CodeModeSetting } from "../code-mode/policy.js";
import {
getLogLevel,
log,
@@ -243,6 +244,12 @@ export interface ComposedHandlerOptions {
* layer is never consulted and does no filesystem work.
*/
proOnUltracode?: boolean;
+ /**
+ * Code mode for `openai-codex` (`auto` | `on` | `off`), resolved by the CLI
+ * from `--code-mode` > `CLAUDISH_CODE_MODE` > `codeMode` config. Absent ⇒
+ * `off`. Read only on the `openai-codex` request path.
+ */
+ codeMode?: CodeModeSetting;
/**
* Test seam for the session-event registry. Defaults to the process-wide
* singleton. Only tests should pass this.
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 64355d42..7713c9de 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -1174,6 +1174,7 @@ async function runCli() {
effortOverride: cliConfig.effortOverride,
modelParams: cliConfig.modelParams,
proOnUltracode: cliConfig.proOnUltracode,
+ codeMode: cliConfig.codeMode,
}
)
);
diff --git a/packages/cli/src/profile-config.ts b/packages/cli/src/profile-config.ts
index d6a254c2..1e68dc58 100644
--- a/packages/cli/src/profile-config.ts
+++ b/packages/cli/src/profile-config.ts
@@ -12,6 +12,7 @@
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, parse } from "node:path";
+import { type CodeModeSetting, parseCodeModeSetting } from "./code-mode/policy.js";
import { activeGlobalConfigFile, getConfigFileOverride } from "./config-override.js";
// Config directory and file paths
@@ -257,6 +258,16 @@ export interface ClaudishProfileConfig {
*/
proOnUltracode?: boolean;
+ /**
+ * Code mode for `openai-codex` (`auto` | `on` | `off`, default `off`): Claude
+ * Code's tools are offered to the model as one freeform `exec` tool running
+ * a script, the protocol the official Codex client uses.
+ * Precedence: --code-mode flag > CLAUDISH_CODE_MODE env > project
+ * `.claudish.json` > this field > off. The scoped read is `readCodeMode()`,
+ * NOT this allowlist — same reason as `proOnUltracode`.
+ */
+ codeMode?: CodeModeSetting;
+
/**
* Master switch for connection RECOVERY itself — the retry ladder claudish
* runs when it cannot even reach the provider. Default ON. Turning it off
@@ -418,6 +429,10 @@ export function loadConfig(): ClaudishProfileConfig {
if (config.proOnUltracode !== undefined) {
merged.proOnUltracode = config.proOnUltracode;
}
+ // Same trap: omitted here, `codeMode` is dropped at the first global save.
+ if (config.codeMode !== undefined) {
+ merged.codeMode = config.codeMode;
+ }
// Same trap again, for both recovery switches. Omitted here, the field
// survives on disk until the first global save and is then silently
// dropped — turning the user's off-switch back ON with no error.
@@ -550,6 +565,32 @@ export function readProOnUltracode(
return undefined;
}
+/**
+ * Read `codeMode` from the project file, else the global file.
+ *
+ * A RAW per-file read, for the same reason `readProOnUltracode` is one: a
+ * project `.claudish.json` that sets only this key is invisible to
+ * `loadConfig`. A value other than `auto`/`on`/`off` is skipped (that scope
+ * states nothing). Returns undefined when neither scope states a setting —
+ * the caller then applies the default (`off`).
+ */
+export function readCodeMode(
+ paths: ScopedConfigPaths = defaultScopedConfigPaths
+): CodeModeSetting | undefined {
+ for (const pathFn of [paths.project, paths.global]) {
+ try {
+ const path = pathFn();
+ if (!existsSync(path)) continue;
+ const parsed = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+ const setting = parseCodeModeSetting(parsed?.codeMode);
+ if (setting) return setting;
+ } catch {
+ // Garbled/unreadable file → skip this scope rather than fail the run.
+ }
+ }
+ return undefined;
+}
+
/**
* Read a `{ enabled?: boolean }` switch from the project file, else the global
* file. Shared by `readRecoveryEnabled` and `readRecoveryUi`.
diff --git a/packages/cli/src/providers/provider-profiles.ts b/packages/cli/src/providers/provider-profiles.ts
index 854e6e64..f333c6e1 100644
--- a/packages/cli/src/providers/provider-profiles.ts
+++ b/packages/cli/src/providers/provider-profiles.ts
@@ -98,6 +98,7 @@ export interface ProfileContext {
| "effortOverride"
| "modelParams"
| "proOnUltracode"
+ | "codeMode"
| "wireMode"
| "wireSpeed"
>;
diff --git a/packages/cli/src/proxy-server.ts b/packages/cli/src/proxy-server.ts
index 800765d3..8ad848d6 100644
--- a/packages/cli/src/proxy-server.ts
+++ b/packages/cli/src/proxy-server.ts
@@ -12,6 +12,7 @@ import {
isAutoModeClassifierRequest,
rewriteClassifierForNative,
} from "./classifier-passthrough.js";
+import { type CodeModeSetting, parseCodeModeSetting } from "./code-mode/policy.js";
import {
type AdvisorPresenceMonitor,
createAdvisorPresenceMonitor,
@@ -162,6 +163,11 @@ export interface ProxyServerOptions {
* no filesystem work at all.
*/
proOnUltracode?: boolean;
+ /**
+ * `--code-mode`: code mode for `openai-codex` (`auto` | `on` | `off`).
+ * Absent ⇒ `off`.
+ */
+ codeMode?: CodeModeSetting;
}
/**
@@ -314,7 +320,7 @@ export async function createProxyServer(
*/
const requestShapingOpts: Pick<
ComposedHandlerOptions,
- "effortOverride" | "modelParams" | "proOnUltracode"
+ "effortOverride" | "modelParams" | "proOnUltracode" | "codeMode"
> = {
// Narrowed HERE, not at the CLI: createProxyServer is also entered from
// `serve` and `team`, so the boundary must validate whoever calls it.
@@ -323,6 +329,9 @@ export async function createProxyServer(
effortOverride: isEffortLevel(options.effortOverride) ? options.effortOverride : undefined,
modelParams: options.modelParams,
proOnUltracode: options.proOnUltracode,
+ // Narrowed here for the same reason as effortOverride: `serve` and `team`
+ // enter too. Anything but auto/on/off is dropped, which reads as off.
+ codeMode: parseCodeModeSetting(options.codeMode),
};
const openRouterHandlers = new Map<string, ModelHandler>(); // Map from Target Model ID -> OpenRouter Handler
diff --git a/packages/cli/src/types.ts b/packages/cli/src/types.ts
index 7151676e..f1ca0a40 100644
--- a/packages/cli/src/types.ts
+++ b/packages/cli/src/types.ts
@@ -1,5 +1,7 @@
// Claudish type definitions
+import type { CodeModeSetting } from "./code-mode/policy.js";
+
// Model ID type - any valid OpenRouter model string
export type OpenRouterModel = string;
@@ -85,6 +87,8 @@ export interface ClaudishConfig {
modelParams?: Record<string, unknown>;
/** --pro-on-ultracode: apply the model's catalog provider-preset while in ultracode (opt-in) */
proOnUltracode?: boolean;
+ /** --code-mode auto|on|off: code mode for `openai-codex` (resolved; default off) */
+ codeMode?: CodeModeSetting;
// Cost tracking
costTracking?: boolean;