oh-my-codex 0.14.0 → 0.14.1

package/Cargo.lock

@@ -32,11 +32,11 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "omx-explore-harness"
-version = "0.14.0"
+version = "0.14.1"
 
 [[package]]
 name = "omx-mux"
-version = "0.14.0"
+version = "0.14.1"
 dependencies = [
  "serde",
  "serde_json",
@@ -44,7 +44,7 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime"
-version = "0.14.0"
+version = "0.14.1"
 dependencies = [
  "omx-mux",
  "omx-runtime-core",
@@ -53,7 +53,7 @@ dependencies = [
 
 [[package]]
 name = "omx-runtime-core"
-version = "0.14.0"
+version = "0.14.1"
 dependencies = [
  "fs2",
  "serde",
@@ -62,7 +62,7 @@ dependencies = [
 
 [[package]]
 name = "omx-sparkshell"
-version = "0.14.0"
+version = "0.14.1"
 dependencies = [
  "omx-mux",
 ]

package/Cargo.toml

@@ -10,7 +10,7 @@ resolver = "2"
 
 [workspace.package]
 
-version = "0.14.0"
+version = "0.14.1"
 
 edition = "2021"
 license = "MIT"

package/README.md

@@ -12,7 +12,9 @@
 [![Discord](https://img.shields.io/discord/1452487457085063218?color=5865F2&logo=discord&logoColor=white&label=Discord)](https://discord.gg/PUwSMR9XNk)
 
 **Website:** https://yeachan-heo.github.io/oh-my-codex-website/
+
 **Docs:** [Getting Started](./docs/getting-started.html) · [Agents](./docs/agents.html) · [Skills](./docs/skills.html) · [Integrations](./docs/integrations.html) · [Demo](./DEMO.md) · [OpenClaw guide](./docs/openclaw-integration.md)
+
 **Community:** [Discord](https://discord.gg/PUwSMR9XNk) — shared OMX/community server for oh-my-codex and related tooling.
 
 OMX is a workflow layer for [OpenAI Codex CLI](https://github.com/openai/codex).
@@ -58,10 +60,11 @@ If you want the default OMX experience, start here:
 
 ```bash
 npm install -g @openai/codex oh-my-codex
-omx setup
 omx --madmax --high
 ```
 
+On a real `oh-my-codex` version bump, the global npm install now launches the interactive `omx setup` refresh automatically when a TTY is available. If npm scripts are skipped or the install is non-interactive, run `omx setup` manually or use `omx update` to force the same refresh path later.
+
 Then work normally inside Codex:
 
 ```text
@@ -145,13 +148,14 @@ Most users should think of OMX as **better task routing + better workflow + bett
 
 ## Start here if you are new
 
-1. Run `omx setup`
-2. Run `omx doctor`
-3. Run a real execution smoke test: `codex login status` and `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"`
-4. Launch with `omx --madmax --high`
-5. Use `$deep-interview "..."` when the request or boundaries are still unclear
-6. Use `$ralplan "..."` to approve the plan and review tradeoffs
-7. Choose `$team` for coordinated parallel execution or `$ralph` for persistent completion loops
+1. Install or update OMX with `npm install -g @openai/codex oh-my-codex`
+2. Let the interactive `omx setup` refresh run automatically on real OMX version bumps, or run `omx setup` / `omx update` yourself when scripts are skipped or you want to rerun it
+3. Run `omx doctor`
+4. Run a real execution smoke test: `codex login status` and `omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"`
+5. Launch with `omx --madmax --high`
+6. Use `$deep-interview "..."` when the request or boundaries are still unclear
+7. Use `$ralplan "..."` to approve the plan and review tradeoffs
+8. Choose `$team` for coordinated parallel execution or `$ralph` for persistent completion loops
 
 ## Recommended workflow
 
@@ -190,6 +194,8 @@ These are operator/support surfaces:
 - `omx setup` installs prompts, skills, AGENTS scaffolding, `.codex/config.toml`, and OMX-managed native Codex hooks in `.codex/hooks.json`
   - setup refresh preserves non-OMX hook entries in `.codex/hooks.json` and only rewrites OMX-managed wrappers
   - `omx uninstall` removes OMX-managed wrappers from `.codex/hooks.json` but keeps the file when user hooks remain
+- `omx update` checks npm immediately, installs the newest global OMX build, then reruns the same interactive setup refresh path
+- fresh OMX-managed `gpt-5.4` config seeding now recommends `model_context_window = 250000` and `model_auto_compact_token_limit = 200000`, but only when those keys are missing
 - `omx doctor` verifies the install when something seems wrong; it does not prove that the active Codex profile can make an authenticated model call
 - `omx hud --watch` is a monitoring/status surface, not the primary user workflow
 

package/crates/omx-explore/src/main.rs

@@ -26,6 +26,7 @@ struct Args {
     cwd: PathBuf,
     prompt: String,
     prompt_file: PathBuf,
+    instructions_file: PathBuf,
     spark_model: String,
     fallback_model: String,
 }
@@ -155,6 +156,7 @@ where
     let mut cwd: Option<PathBuf> = None;
     let mut prompt: Option<String> = None;
     let mut prompt_file: Option<PathBuf> = None;
+    let mut instructions_file: Option<PathBuf> = None;
     let mut spark_model: Option<String> = None;
     let mut fallback_model: Option<String> = None;
 
@@ -166,6 +168,12 @@ where
             "--prompt-file" => {
                 prompt_file = Some(PathBuf::from(next_required(&mut args, "--prompt-file")?))
             }
+            "--instructions-file" => {
+                instructions_file = Some(PathBuf::from(next_required(
+                    &mut args,
+                    "--instructions-file",
+                )?))
+            }
             "--model-spark" => spark_model = Some(next_required(&mut args, "--model-spark")?),
             "--model-fallback" => {
                 fallback_model = Some(next_required(&mut args, "--model-fallback")?)
@@ -179,6 +187,8 @@ where
         cwd: cwd.ok_or_else(|| format!("missing --cwd\n{}", usage()))?,
         prompt: prompt.ok_or_else(|| format!("missing --prompt\n{}", usage()))?,
         prompt_file: prompt_file.ok_or_else(|| format!("missing --prompt-file\n{}", usage()))?,
+        instructions_file: instructions_file
+            .ok_or_else(|| format!("missing --instructions-file\n{}", usage()))?,
         spark_model: spark_model.ok_or_else(|| format!("missing --model-spark\n{}", usage()))?,
         fallback_model: fallback_model
             .ok_or_else(|| format!("missing --model-fallback\n{}", usage()))?,
@@ -198,7 +208,7 @@ where
 }
 
 fn usage() -> &'static str {
-    "Usage: omx-explore --cwd <dir> --prompt <text> --prompt-file <explore-prompt.md> --model-spark <model> --model-fallback <model>"
+    "Usage: omx-explore --cwd <dir> --prompt <text> --prompt-file <explore-prompt.md> --instructions-file <AGENTS.md> --model-spark <model> --model-fallback <model>"
 }
 
 fn invoke_codex(args: &Args, model: &str, prompt_contract: &str) -> io::Result<AttemptResult> {
@@ -220,6 +230,11 @@ fn invoke_codex(args: &Args, model: &str, prompt_contract: &str) -> io::Result<A
         .arg("-c")
         .arg("model_reasoning_effort=\"low\"")
         .arg("-c")
+        .arg(format!(
+            "model_instructions_file=\"{}\"",
+            escape_toml_string(&args.instructions_file.display().to_string())
+        ))
+        .arg("-c")
         .arg("shell_environment_policy.inherit=all")
         .arg("--skip-git-repo-check")
         .arg("-o")
@@ -240,6 +255,10 @@ fn invoke_codex(args: &Args, model: &str, prompt_contract: &str) -> io::Result<A
     })
 }
 
+fn escape_toml_string(value: &str) -> String {
+    value.replace('\\', "\\\\").replace('"', "\\\"")
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct CodexLaunch {
     program: String,
@@ -982,6 +1001,8 @@ mod tests {
                 "find auth",
                 "--prompt-file",
                 "/tmp/explore.md",
+                "--instructions-file",
+                "/tmp/explore-agents.md",
                 "--model-spark",
                 "gpt-5.3-codex-spark",
                 "--model-fallback",
@@ -995,6 +1016,7 @@ mod tests {
         assert_eq!(args.cwd, Path::new("/tmp/repo"));
         assert_eq!(args.prompt, "find auth");
         assert_eq!(args.prompt_file, Path::new("/tmp/explore.md"));
+        assert_eq!(args.instructions_file, Path::new("/tmp/explore-agents.md"));
         assert_eq!(args.spark_model, "gpt-5.3-codex-spark");
         assert_eq!(args.fallback_model, "gpt-5.4");
     }
@@ -1618,6 +1640,8 @@ exit 17
                 "find tests",
                 "--prompt-file",
                 prompt_file.to_str().expect("prompt path"),
+                "--instructions-file",
+                prompt_file.to_str().expect("instructions path"),
                 "--model-spark",
                 "spark-model",
                 "--model-fallback",
@@ -1675,6 +1699,7 @@ printf '# Answer\nok\n' > "$output_path"
                 cwd: repo.clone(),
                 prompt: "find tests".to_string(),
                 prompt_file,
+                instructions_file: repo.join("AGENTS.md"),
                 spark_model: "spark-model".to_string(),
                 fallback_model: "fallback-model".to_string(),
             },
@@ -1696,6 +1721,74 @@ printf '# Answer\nok\n' > "$output_path"
         );
     }
 
+    #[test]
+    fn invoke_codex_injects_model_instructions_file_override() {
+        let _guard = env_lock();
+        let root = temp_allowlist_dir().expect("temp root");
+        let repo = root.path.join("repo");
+        create_dir_all(&repo).expect("create repo");
+        let prompt_file = root.path.join("prompt.md");
+        write(&prompt_file, "contract").expect("write prompt");
+        let capture_path = root.path.join("argv.txt");
+        let fake_codex = root.path.join("codex-stub");
+        write_executable(
+            &fake_codex,
+            &format!(
+                r#"#!/bin/sh
+set -eu
+output_path=""
+capture={}
+printf '' > "$capture"
+while [ "$#" -gt 0 ]; do
+  printf '%s\n' "$1" >> "$capture"
+  if [ "$1" = "-o" ]; then
+    shift
+    output_path="$1"
+  fi
+  shift
+done
+printf '# Answer\nok\n' > "$output_path"
+"#,
+                shell_quote(&capture_path.display().to_string())
+            ),
+        )
+        .expect("write fake codex");
+
+        unsafe {
+            env::set_var(CODEX_BIN_ENV, &fake_codex);
+        }
+        let instructions_path = repo.join("custom instructions.md");
+        let attempt = invoke_codex(
+            &Args {
+                cwd: repo.clone(),
+                prompt: "find tests".to_string(),
+                prompt_file,
+                instructions_file: instructions_path.clone(),
+                spark_model: "spark-model".to_string(),
+                fallback_model: "fallback-model".to_string(),
+            },
+            "spark-model",
+            "contract",
+        )
+        .expect("invoke codex");
+        unsafe {
+            env::remove_var(CODEX_BIN_ENV);
+        }
+
+        assert_eq!(attempt.status_code, 0);
+        let captured = read_to_string(&capture_path).expect("read capture");
+        let expected = format!(
+            "model_instructions_file=\"{}\"",
+            escape_toml_string(&instructions_path.display().to_string())
+        );
+        assert!(
+            captured.contains(&expected),
+            "expected {:?} in {:?}",
+            expected,
+            captured
+        );
+    }
+
     #[test]
     fn sanitize_explore_subprocess_env_blocks_bash_env_startup_hooks() {
         let _guard = env_lock();

package/crates/omx-sparkshell/src/codex_bridge.rs

@@ -9,7 +9,7 @@ use std::time::{Duration, Instant};
 
 pub const DEFAULT_SUMMARY_TIMEOUT_MS: u64 = 60_000;
 pub const DEFAULT_SPARK_MODEL: &str = "gpt-5.3-codex-spark";
-pub const DEFAULT_FRONTIER_MODEL: &str = "gpt-5.4";
+pub const DEFAULT_STANDARD_MODEL: &str = "gpt-5.4-mini";
 
 pub fn resolve_model() -> String {
     env::var("OMX_SPARKSHELL_MODEL")
@@ -33,11 +33,18 @@ pub fn resolve_fallback_model() -> String {
         .ok()
         .filter(|value| !value.trim().is_empty())
         .or_else(|| {
-            env::var("OMX_DEFAULT_FRONTIER_MODEL")
+            env::var("OMX_DEFAULT_STANDARD_MODEL")
                 .ok()
                 .filter(|value| !value.trim().is_empty())
         })
-        .unwrap_or_else(|| DEFAULT_FRONTIER_MODEL.to_string())
+        .unwrap_or_else(|| DEFAULT_STANDARD_MODEL.to_string())
+}
+
+pub fn resolve_instructions_file() -> Option<String> {
+    env::var("OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE")
+        .ok()
+        .map(|value| value.trim().to_string())
+        .filter(|value| !value.is_empty())
 }
 
 pub fn read_summary_timeout_ms() -> u64 {
@@ -125,6 +132,12 @@ fn run_codex_exec(
         .arg("read-only")
         .arg("-c")
         .arg("model_reasoning_effort=\"low\"")
+        .args(resolve_instructions_file().into_iter().flat_map(|path| {
+            [
+                "-c".to_string(),
+                format!("model_instructions_file=\"{}\"", escape_toml_string(&path)),
+            ]
+        }))
         .arg("--skip-git-repo-check")
         .arg("--color")
         .arg("never")
@@ -191,6 +204,10 @@ fn run_codex_exec(
     ))
 }
 
+fn escape_toml_string(value: &str) -> String {
+    value.replace('\\', "\\\\").replace('"', "\\\"")
+}
+
 fn normalize_summary(raw: &str) -> Option<String> {
     let mut summary = Vec::new();
     let mut failures = Vec::new();
@@ -271,8 +288,9 @@ fn render_section(name: &str, entries: &[String]) -> String {
 #[cfg(test)]
 mod tests {
     use super::{
-        normalize_summary, read_summary_timeout_ms, resolve_fallback_model, resolve_model,
-        DEFAULT_FRONTIER_MODEL, DEFAULT_SPARK_MODEL, DEFAULT_SUMMARY_TIMEOUT_MS,
+        normalize_summary, read_summary_timeout_ms, resolve_fallback_model,
+        resolve_instructions_file, resolve_model, DEFAULT_SPARK_MODEL, DEFAULT_STANDARD_MODEL,
+        DEFAULT_SUMMARY_TIMEOUT_MS,
     };
     use crate::test_support::env_lock;
     use std::env;
@@ -293,23 +311,23 @@ mod tests {
     }
 
     #[test]
-    fn fallback_model_resolution_prefers_override_then_default_frontier() {
+    fn fallback_model_resolution_prefers_override_then_default_standard() {
         let _guard = env_lock();
         unsafe {
             env::remove_var("OMX_SPARKSHELL_FALLBACK_MODEL");
-            env::remove_var("OMX_DEFAULT_FRONTIER_MODEL");
+            env::remove_var("OMX_DEFAULT_STANDARD_MODEL");
         }
-        assert_eq!(resolve_fallback_model(), DEFAULT_FRONTIER_MODEL);
+        assert_eq!(resolve_fallback_model(), DEFAULT_STANDARD_MODEL);
 
         unsafe {
-            env::set_var("OMX_DEFAULT_FRONTIER_MODEL", "frontier-a");
+            env::set_var("OMX_DEFAULT_STANDARD_MODEL", "standard-a");
         }
-        assert_eq!(resolve_fallback_model(), "frontier-a");
+        assert_eq!(resolve_fallback_model(), "standard-a");
 
         unsafe {
-            env::set_var("OMX_SPARKSHELL_FALLBACK_MODEL", "frontier-b");
+            env::set_var("OMX_SPARKSHELL_FALLBACK_MODEL", "standard-b");
         }
-        assert_eq!(resolve_fallback_model(), "frontier-b");
+        assert_eq!(resolve_fallback_model(), "standard-b");
     }
 
     #[test]
@@ -347,6 +365,35 @@ mod tests {
         }
     }
 
+    #[test]
+    fn instructions_file_resolution_prefers_override_and_ignores_blank() {
+        let _guard = env_lock();
+        unsafe {
+            env::remove_var("OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE");
+        }
+        assert_eq!(resolve_instructions_file(), None);
+
+        unsafe {
+            env::set_var(
+                "OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE",
+                " /tmp/sparkshell-agents.md ",
+            );
+        }
+        assert_eq!(
+            resolve_instructions_file(),
+            Some("/tmp/sparkshell-agents.md".to_string())
+        );
+
+        unsafe {
+            env::set_var("OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE", "   ");
+        }
+        assert_eq!(resolve_instructions_file(), None);
+
+        unsafe {
+            env::remove_var("OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE");
+        }
+    }
+
     #[test]
     fn timeout_defaults_for_zero_and_invalid_values() {
         let _guard = env_lock();

package/crates/omx-sparkshell/tests/execution.rs

@@ -97,6 +97,54 @@ fn summary_mode_uses_codex_exec_and_model_override() {
     let _ = fs::remove_dir_all(temp);
 }
 
+#[test]
+fn summary_mode_injects_model_instructions_file_override() {
+    let temp = unique_temp_dir("codex-instructions-file");
+    let codex = temp.join("codex");
+    let args_log = temp.join("args.log");
+    let instructions_file = temp.join("sparkshell-lightweight-AGENTS.md");
+    write_executable(
+        &codex,
+        &format!(
+            "#!/bin/sh\nprintf '%s\n' \"$@\" > '{}'\nprintf '%s\n' '- summary: command produced long output'\n",
+            args_log.display()
+        ),
+    );
+    fs::write(&instructions_file, "# sparkshell instructions\n").expect("write instructions file");
+
+    let path = format!(
+        "{}:{}",
+        temp.display(),
+        env::var("PATH").unwrap_or_default()
+    );
+    let output = Command::new(sparkshell_bin())
+        .env("PATH", path)
+        .env("OMX_SPARKSHELL_LINES", "1")
+        .env(
+            "OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE",
+            instructions_file.display().to_string(),
+        )
+        .arg("sh")
+        .arg("-c")
+        .arg("printf 'one\ntwo\n'")
+        .output()
+        .expect("run sparkshell");
+
+    assert!(output.status.success());
+    let args = fs::read_to_string(args_log).expect("args log");
+    assert!(args.contains("model_reasoning_effort=\"low\""));
+    assert!(args.contains(&format!(
+        "model_instructions_file=\"{}\"",
+        instructions_file
+            .display()
+            .to_string()
+            .replace('\\', "\\\\")
+            .replace('"', "\\\"")
+    )));
+
+    let _ = fs::remove_dir_all(temp);
+}
+
 #[test]
 fn summary_failure_falls_back_to_raw_output_with_notice() {
     let temp = unique_temp_dir("codex-fail");

package/dist/cli/__tests__/explore.test.js

@@ -578,12 +578,43 @@ describe('buildExploreHarnessArgs', () => {
         assert.deepEqual(args.slice(4), [
             '--prompt-file',
             '/pkg/prompts/explore-harness.md',
+            '--instructions-file',
+            '/pkg/templates/model-instructions/explore-lightweight-AGENTS.md',
             '--model-spark',
             'spark-model',
             '--model-fallback',
-            'gpt-5.4',
+            'gpt-5.4-mini',
         ]);
     });
+    it('honors configured env overrides for fallback model and instructions file', async () => {
+        const codexHome = await mkdtemp(join(tmpdir(), 'omx-explore-config-env-'));
+        await writeFile(join(codexHome, '.omx-config.json'), JSON.stringify({
+            env: {
+                OMX_DEFAULT_STANDARD_MODEL: 'standard-local',
+                OMX_DEFAULT_SPARK_MODEL: 'spark-local',
+                OMX_EXPLORE_MODEL_INSTRUCTIONS_FILE: '/config/explore-instructions.md',
+            },
+        }));
+        try {
+            const wd = join(tmpdir(), 'omx-explore-arg-test');
+            const args = buildExploreHarnessArgs('find auth', wd, {
+                CODEX_HOME: codexHome,
+            }, '/pkg');
+            assert.deepEqual(args.slice(4), [
+                '--prompt-file',
+                '/pkg/prompts/explore-harness.md',
+                '--instructions-file',
+                '/config/explore-instructions.md',
+                '--model-spark',
+                'spark-local',
+                '--model-fallback',
+                'standard-local',
+            ]);
+        }
+        finally {
+            await rm(codexHome, { recursive: true, force: true });
+        }
+    });
 });
 describe('resolveExploreSparkShellRoute', () => {
     it('keeps natural-language exploration prompts on the direct harness path', () => {
@@ -764,6 +795,7 @@ describe('exploreCommand', () => {
                 assert.match(captured, /ALLOWED_STATUS=0/);
                 assert.match(captured, /BLOCKED_STATUS=(?!0)\d+/);
                 assert.match(captured, /--ARGV--[\s\S]*\nexec\n/);
+                assert.match(captured, /model_instructions_file=.*explore-lightweight-AGENTS\.md/);
                 assert.match(captured, /--ALLOWED_STDOUT--[\s\S]*ripgrep/i);
                 assert.match(captured, /--BLOCKED_STDERR--[\s\S]*not on the omx explore allowlist/);
             });