Release 0.34.0

# External (non-OpenAI) Pull Request Requirements

Currently, mcp server fail to start with:
```
🖐  MCP client for `<CLIENT>` failed to start: missing field `user_agent`
````

It isn't clear to me yet why this is happening. My understanding is that
this struct is simply added as a new field to the response but this
should fix it until I figure out the full story here.

<img width="714" height="262" alt="CleanShot 2025-09-10 at 13 58 59"
src="https://github.com/user-attachments/assets/946b1313-5c1c-43d3-8ae8-ecc3de3406fc"
/>

README.md

@@ -32,14 +32,6 @@ Then simply run `codex` to get started:
 codex
 ```
 
-To update Codex after installing it, run:
-
-```shell
-codex update
-```
-
-You can also run `codex upgrade`. The CLI will reuse the installation method you originally used (npm or Homebrew).
-
 <details>
 <summary>You can also go to the <a href="https://github.com/openai/codex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>
 

codex-cli/README.md

@@ -132,14 +132,6 @@ Run interactively:
 codex
 ```
 
-To upgrade Codex after installing it, run:
-
-```shell
-codex update
-```
-
-(`codex upgrade` works too.) The CLI reuses the installation method you originally used (npm or Homebrew).
-
 Or, run with a prompt as input (and optionally in `Full Auto` mode):
 
 ```shell

codex-rs/Cargo.toml

@@ -22,7 +22,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.0.0"
+version = "0.34.0"
 # Track the edition for all workspace crates in one place. Individual
 # crates can still override this value, but keeping it here means new
 # crates created with `cargo new -w ...` automatically inherit the 2024

codex-rs/cli/Cargo.toml

@@ -38,6 +38,3 @@ tokio = { version = "1", features = [
 tracing = "0.1.41"
 tracing-subscriber = "0.3.19"
 codex-protocol-ts = { path = "../protocol-ts" }
-
-[dev-dependencies]
-pretty_assertions = "1"

codex-rs/cli/src/lib.rs

@@ -2,7 +2,6 @@ pub mod debug_sandbox;
 mod exit_status;
 pub mod login;
 pub mod proto;
-pub mod update;
 
 use clap::Parser;
 use codex_common::CliConfigOverrides;

codex-rs/cli/src/main.rs

@@ -12,7 +12,6 @@ use codex_cli::login::run_login_with_api_key;
 use codex_cli::login::run_login_with_chatgpt;
 use codex_cli::login::run_logout;
 use codex_cli::proto;
-use codex_cli::update::run_update_command;
 use codex_common::CliConfigOverrides;
 use codex_exec::Cli as ExecCli;
 use codex_tui::Cli as TuiCli;
@@ -74,10 +73,6 @@ enum Subcommand {
     #[clap(visible_alias = "a")]
     Apply(ApplyCommand),
 
-    /// Update Codex using the original installation method.
-    #[clap(visible_alias = "upgrade")]
-    Update,
-
     /// Internal: generate TypeScript protocol bindings.
     #[clap(hide = true)]
     GenerateTs(GenerateTsCommand),
@@ -217,9 +212,6 @@ async fn cli_main(codex_linux_sandbox_exe: Option<PathBuf>) -> anyhow::Result<()
         Some(Subcommand::GenerateTs(gen_cli)) => {
             codex_protocol_ts::generate_ts(&gen_cli.out_dir, gen_cli.prettier.as_deref())?;
         }
-        Some(Subcommand::Update) => {
-            run_update_command().await;
-        }
     }
 
     Ok(())

codex-rs/cli/src/update.rs

@@ -1,157 +0,0 @@
-use std::path::Path;
-use std::path::PathBuf;
-use std::process::Stdio;
-
-use tokio::process::Command;
-
-use crate::exit_status::handle_exit_status;
-
-const RELEASE_URL: &str = "https://github.com/openai/codex/releases/latest";
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum InstallMethod {
-    Npm,
-    Brew,
-}
-
-#[derive(Debug)]
-struct InstallEnvironment {
-    managed_by_npm: bool,
-    current_exe: Option<PathBuf>,
-    is_macos: bool,
-}
-
-impl InstallEnvironment {
-    fn from_system() -> Self {
-        Self {
-            managed_by_npm: std::env::var_os("CODEX_MANAGED_BY_NPM").is_some(),
-            current_exe: std::env::current_exe().ok(),
-            is_macos: cfg!(target_os = "macos"),
-        }
-    }
-}
-
-pub async fn run_update_command() -> ! {
-    let env = InstallEnvironment::from_system();
-    let Some(method) = detect_install_method(&env) else {
-        eprintln!("Unable to determine how Codex was installed.");
-        eprintln!("If you installed Codex with npm, run `npm install -g @openai/codex@latest`.",);
-        eprintln!("If you installed Codex with Homebrew, run `brew upgrade codex`.");
-        eprintln!("For other installation methods, see {RELEASE_URL}.");
-        std::process::exit(1);
-    };
-
-    let (program, args) = match method {
-        InstallMethod::Npm => ("npm", ["install", "-g", "@openai/codex@latest"]),
-        InstallMethod::Brew => ("brew", ["upgrade", "codex"]),
-    };
-
-    run_external_command(program, &args).await;
-}
-
-fn detect_install_method(env: &InstallEnvironment) -> Option<InstallMethod> {
-    if env.managed_by_npm {
-        return Some(InstallMethod::Npm);
-    }
-
-    if env.is_macos
-        && env
-            .current_exe
-            .as_deref()
-            .is_some_and(is_homebrew_executable)
-    {
-        return Some(InstallMethod::Brew);
-    }
-
-    None
-}
-
-fn is_homebrew_executable(exe: &Path) -> bool {
-    const HOMEBREW_PREFIXES: &[&str] = &["/opt/homebrew", "/usr/local"];
-    HOMEBREW_PREFIXES
-        .iter()
-        .any(|prefix| exe.starts_with(prefix))
-}
-
-async fn run_external_command(program: &str, args: &[&str]) -> ! {
-    let command_display = format_command(program, args);
-    eprintln!("Running `{command_display}` to update Codex...");
-
-    let status = Command::new(program)
-        .args(args)
-        .stdin(Stdio::inherit())
-        .stdout(Stdio::inherit())
-        .stderr(Stdio::inherit())
-        .status()
-        .await;
-
-    match status {
-        Ok(status) => handle_exit_status(status),
-        Err(err) => {
-            eprintln!("Failed to execute `{command_display}`: {err}");
-            std::process::exit(1);
-        }
-    }
-}
-
-fn format_command(program: &str, args: &[&str]) -> String {
-    let mut command = String::from(program);
-    for arg in args {
-        command.push(' ');
-        command.push_str(arg);
-    }
-    command
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use pretty_assertions::assert_eq;
-
-    #[test]
-    fn detects_npm_when_env_var_is_present() {
-        let env = InstallEnvironment {
-            managed_by_npm: true,
-            current_exe: Some(PathBuf::from("/opt/homebrew/bin/codex")),
-            is_macos: true,
-        };
-        assert_eq!(detect_install_method(&env), Some(InstallMethod::Npm));
-    }
-
-    #[test]
-    fn detects_homebrew_install_on_macos() {
-        let env = InstallEnvironment {
-            managed_by_npm: false,
-            current_exe: Some(PathBuf::from("/opt/homebrew/bin/codex")),
-            is_macos: true,
-        };
-        assert_eq!(detect_install_method(&env), Some(InstallMethod::Brew));
-    }
-
-    #[test]
-    fn returns_none_when_install_method_is_unknown() {
-        let env = InstallEnvironment {
-            managed_by_npm: false,
-            current_exe: Some(PathBuf::from("/tmp/codex")),
-            is_macos: false,
-        };
-        assert_eq!(detect_install_method(&env), None);
-    }
-
-    #[test]
-    fn homebrew_prefixes_are_detected() {
-        assert!(is_homebrew_executable(Path::new("/opt/homebrew/bin/codex")));
-        assert!(is_homebrew_executable(Path::new("/usr/local/bin/codex")));
-        assert!(!is_homebrew_executable(Path::new(
-            "/home/user/.local/bin/codex"
-        )));
-    }
-
-    #[test]
-    fn command_formatting_is_readable() {
-        assert_eq!(
-            format_command("npm", &["install", "-g", "@openai/codex@latest"]),
-            "npm install -g @openai/codex@latest"
-        );
-    }
-}

codex-rs/core/src/codex.rs

@@ -9,6 +9,9 @@ use std::sync::atomic::AtomicU64;
 use std::time::Duration;
 
 use crate::AuthManager;
+use crate::config_edit::CONFIG_KEY_EFFORT;
+use crate::config_edit::CONFIG_KEY_MODEL;
+use crate::config_edit::persist_non_null_overrides;
 use crate::event_mapping::map_response_item_to_event_messages;
 use async_channel::Receiver;
 use async_channel::Sender;
@@ -1100,10 +1103,10 @@ async fn submission_loop(
                 let provider = prev.client.get_provider();
 
                 // Effective model + family
-                let (effective_model, effective_family) = if let Some(m) = model {
+                let (effective_model, effective_family) = if let Some(ref m) = model {
                     let fam =
-                        find_family_for_model(&m).unwrap_or_else(|| config.model_family.clone());
-                    (m, fam)
+                        find_family_for_model(m).unwrap_or_else(|| config.model_family.clone());
+                    (m.clone(), fam)
                 } else {
                     (prev.client.get_model(), prev.client.get_model_family())
                 };
@@ -1161,6 +1164,23 @@ async fn submission_loop(
 
                 // Install the new persistent context for subsequent tasks/turns.
                 turn_context = Arc::new(new_turn_context);
+
+                // Optionally persist changes to model / effort
+                let effort_str = effort.map(|_| effective_effort.to_string());
+
+                if let Err(e) = persist_non_null_overrides(
+                    &config.codex_home,
+                    config.active_profile.as_deref(),
+                    &[
+                        (&[CONFIG_KEY_MODEL], model.as_deref()),
+                        (&[CONFIG_KEY_EFFORT], effort_str.as_deref()),
+                    ],
+                )
+                .await
+                {
+                    warn!("failed to persist overrides: {e:#}");
+                }
+
                 if cwd.is_some() || approval_policy.is_some() || sandbox_policy.is_some() {
                     sess.record_conversation_items(&[ResponseItem::from(EnvironmentContext::new(
                         cwd,

codex-rs/core/src/config.rs

@@ -38,7 +38,7 @@ const OPENAI_DEFAULT_MODEL: &str = "gpt-5";
 /// the context window.
 pub(crate) const PROJECT_DOC_MAX_BYTES: usize = 32 * 1024; // 32 KiB
 
-const CONFIG_TOML_FILE: &str = "config.toml";
+pub(crate) const CONFIG_TOML_FILE: &str = "config.toml";
 
 /// Application configuration loaded from disk and merged with overrides.
 #[derive(Debug, Clone, PartialEq)]
@@ -174,6 +174,10 @@ pub struct Config {
 
     /// Include the `view_image` tool that lets the agent attach a local image path to context.
     pub include_view_image_tool: bool,
+
+    /// The active profile name used to derive this `Config` (if any).
+    pub active_profile: Option<String>,
+
     /// When true, disables burst-paste detection for typed input entirely.
     /// All characters are inserted as they are received, and no buffering
     /// or placeholder replacement will occur for fast keypress bursts.
@@ -653,7 +657,11 @@ impl Config {
             tools_web_search_request: override_tools_web_search_request,
         } = overrides;
 
-        let config_profile = match config_profile_key.as_ref().or(cfg.profile.as_ref()) {
+        let active_profile_name = config_profile_key
+            .as_ref()
+            .or(cfg.profile.as_ref())
+            .cloned();
+        let config_profile = match active_profile_name.as_ref() {
             Some(key) => cfg
                 .profiles
                 .get(key)
@@ -819,6 +827,7 @@ impl Config {
                 .experimental_use_exec_command_tool
                 .unwrap_or(false),
             include_view_image_tool,
+            active_profile: active_profile_name,
             disable_paste_burst: cfg.disable_paste_burst.unwrap_or(false),
         };
         Ok(config)
@@ -1193,6 +1202,7 @@ model_verbosity = "high"
                 preferred_auth_method: AuthMode::ChatGPT,
                 use_experimental_streamable_shell_tool: false,
                 include_view_image_tool: true,
+                active_profile: Some("o3".to_string()),
                 disable_paste_burst: false,
             },
             o3_profile_config
@@ -1249,6 +1259,7 @@ model_verbosity = "high"
             preferred_auth_method: AuthMode::ChatGPT,
             use_experimental_streamable_shell_tool: false,
             include_view_image_tool: true,
+            active_profile: Some("gpt3".to_string()),
             disable_paste_burst: false,
         };
 
@@ -1320,6 +1331,7 @@ model_verbosity = "high"
             preferred_auth_method: AuthMode::ChatGPT,
             use_experimental_streamable_shell_tool: false,
             include_view_image_tool: true,
+            active_profile: Some("zdr".to_string()),
             disable_paste_burst: false,
         };
 
@@ -1377,6 +1389,7 @@ model_verbosity = "high"
             preferred_auth_method: AuthMode::ChatGPT,
             use_experimental_streamable_shell_tool: false,
             include_view_image_tool: true,
+            active_profile: Some("gpt5".to_string()),
             disable_paste_burst: false,
         };
 
@@ -1452,6 +1465,4 @@ trust_level = "trusted"
 
         Ok(())
     }
-
-    // No test enforcing the presence of a standalone [projects] header.
 }

codex-rs/core/src/config_edit.rs

@@ -0,0 +1,582 @@
+use crate::config::CONFIG_TOML_FILE;
+use anyhow::Result;
+use std::path::Path;
+use tempfile::NamedTempFile;
+use toml_edit::DocumentMut;
+
+pub const CONFIG_KEY_MODEL: &str = "model";
+pub const CONFIG_KEY_EFFORT: &str = "model_reasoning_effort";
+
+/// Persist overrides into `config.toml` using explicit key segments per
+/// override. This avoids ambiguity with keys that contain dots or spaces.
+pub async fn persist_overrides(
+    codex_home: &Path,
+    profile: Option<&str>,
+    overrides: &[(&[&str], &str)],
+) -> Result<()> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+
+    let mut doc = match tokio::fs::read_to_string(&config_path).await {
+        Ok(s) => s.parse::<DocumentMut>()?,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+            tokio::fs::create_dir_all(codex_home).await?;
+            DocumentMut::new()
+        }
+        Err(e) => return Err(e.into()),
+    };
+
+    let effective_profile = if let Some(p) = profile {
+        Some(p.to_owned())
+    } else {
+        doc.get("profile")
+            .and_then(|i| i.as_str())
+            .map(|s| s.to_string())
+    };
+
+    for (segments, val) in overrides.iter().copied() {
+        let value = toml_edit::value(val);
+        if let Some(ref name) = effective_profile {
+            if segments.first().copied() == Some("profiles") {
+                apply_toml_edit_override_segments(&mut doc, segments, value);
+            } else {
+                let mut seg_buf: Vec<&str> = Vec::with_capacity(2 + segments.len());
+                seg_buf.push("profiles");
+                seg_buf.push(name.as_str());
+                seg_buf.extend_from_slice(segments);
+                apply_toml_edit_override_segments(&mut doc, &seg_buf, value);
+            }
+        } else {
+            apply_toml_edit_override_segments(&mut doc, segments, value);
+        }
+    }
+
+    let tmp_file = NamedTempFile::new_in(codex_home)?;
+    tokio::fs::write(tmp_file.path(), doc.to_string()).await?;
+    tmp_file.persist(config_path)?;
+
+    Ok(())
+}
+
+/// Persist overrides where values may be optional. Any entries with `None`
+/// values are skipped. If all values are `None`, this becomes a no-op and
+/// returns `Ok(())` without touching the file.
+pub async fn persist_non_null_overrides(
+    codex_home: &Path,
+    profile: Option<&str>,
+    overrides: &[(&[&str], Option<&str>)],
+) -> Result<()> {
+    let filtered: Vec<(&[&str], &str)> = overrides
+        .iter()
+        .filter_map(|(k, v)| v.map(|vv| (*k, vv)))
+        .collect();
+
+    if filtered.is_empty() {
+        return Ok(());
+    }
+
+    persist_overrides(codex_home, profile, &filtered).await
+}
+
+/// Apply a single override onto a `toml_edit` document while preserving
+/// existing formatting/comments.
+/// The key is expressed as explicit segments to correctly handle keys that
+/// contain dots or spaces.
+fn apply_toml_edit_override_segments(
+    doc: &mut DocumentMut,
+    segments: &[&str],
+    value: toml_edit::Item,
+) {
+    use toml_edit::Item;
+
+    if segments.is_empty() {
+        return;
+    }
+
+    let mut current = doc.as_table_mut();
+    for seg in &segments[..segments.len() - 1] {
+        if !current.contains_key(seg) {
+            current[*seg] = Item::Table(toml_edit::Table::new());
+            if let Some(t) = current[*seg].as_table_mut() {
+                t.set_implicit(true);
+            }
+        }
+
+        let maybe_item = current.get_mut(seg);
+        let Some(item) = maybe_item else { return };
+
+        if !item.is_table() {
+            *item = Item::Table(toml_edit::Table::new());
+            if let Some(t) = item.as_table_mut() {
+                t.set_implicit(true);
+            }
+        }
+
+        let Some(tbl) = item.as_table_mut() else {
+            return;
+        };
+        current = tbl;
+    }
+
+    let last = segments[segments.len() - 1];
+    current[last] = value;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use tempfile::tempdir;
+
+    /// Verifies model and effort are written at top-level when no profile is set.
+    #[tokio::test]
+    async fn set_default_model_and_effort_top_level_when_no_profile() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        persist_overrides(
+            codex_home,
+            None,
+            &[
+                (&[CONFIG_KEY_MODEL], "gpt-5"),
+                (&[CONFIG_KEY_EFFORT], "high"),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"model = "gpt-5"
+model_reasoning_effort = "high"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies values are written under the active profile when `profile` is set.
+    #[tokio::test]
+    async fn set_defaults_update_profile_when_profile_set() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed config with a profile selection but without profiles table
+        let seed = "profile = \"o3\"\n";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        persist_overrides(
+            codex_home,
+            None,
+            &[
+                (&[CONFIG_KEY_MODEL], "o3"),
+                (&[CONFIG_KEY_EFFORT], "minimal"),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"profile = "o3"
+
+[profiles.o3]
+model = "o3"
+model_reasoning_effort = "minimal"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies profile names with dots/spaces are preserved via explicit segments.
+    #[tokio::test]
+    async fn set_defaults_update_profile_with_dot_and_space() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed config with a profile name that contains a dot and a space
+        let seed = "profile = \"my.team name\"\n";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        persist_overrides(
+            codex_home,
+            None,
+            &[
+                (&[CONFIG_KEY_MODEL], "o3"),
+                (&[CONFIG_KEY_EFFORT], "minimal"),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"profile = "my.team name"
+
+[profiles."my.team name"]
+model = "o3"
+model_reasoning_effort = "minimal"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies explicit profile override writes under that profile even without active profile.
+    #[tokio::test]
+    async fn set_defaults_update_when_profile_override_supplied() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // No profile key in config.toml
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), "")
+            .await
+            .expect("seed write");
+
+        // Persist with an explicit profile override
+        persist_overrides(
+            codex_home,
+            Some("o3"),
+            &[(&[CONFIG_KEY_MODEL], "o3"), (&[CONFIG_KEY_EFFORT], "high")],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"[profiles.o3]
+model = "o3"
+model_reasoning_effort = "high"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies nested tables are created as needed when applying overrides.
+    #[tokio::test]
+    async fn persist_overrides_creates_nested_tables() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        persist_overrides(
+            codex_home,
+            None,
+            &[
+                (&["a", "b", "c"], "v"),
+                (&["x"], "y"),
+                (&["profiles", "p1", CONFIG_KEY_MODEL], "gpt-5"),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"x = "y"
+
+[a.b]
+c = "v"
+
+[profiles.p1]
+model = "gpt-5"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies a scalar key becomes a table when nested keys are written.
+    #[tokio::test]
+    async fn persist_overrides_replaces_scalar_with_table() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+        let seed = "foo = \"bar\"\n";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        persist_overrides(codex_home, None, &[(&["foo", "bar", "baz"], "ok")])
+            .await
+            .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"[foo.bar]
+baz = "ok"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies comments and spacing are preserved when writing under active profile.
+    #[tokio::test]
+    async fn set_defaults_preserve_comments() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed a config with comments and spacing we expect to preserve
+        let seed = r#"# Global comment
+# Another line
+
+profile = "o3"
+
+# Profile settings
+[profiles.o3]
+# keep me
+existing = "keep"
+"#;
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        // Apply defaults; since profile is set, it should write under [profiles.o3]
+        persist_overrides(
+            codex_home,
+            None,
+            &[(&[CONFIG_KEY_MODEL], "o3"), (&[CONFIG_KEY_EFFORT], "high")],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"# Global comment
+# Another line
+
+profile = "o3"
+
+# Profile settings
+[profiles.o3]
+# keep me
+existing = "keep"
+model = "o3"
+model_reasoning_effort = "high"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies comments and spacing are preserved when writing at top level.
+    #[tokio::test]
+    async fn set_defaults_preserve_global_comments() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed a config WITHOUT a profile, containing comments and spacing
+        let seed = r#"# Top-level comments
+# should be preserved
+
+existing = "keep"
+"#;
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        // Since there is no profile, the defaults should be written at top-level
+        persist_overrides(
+            codex_home,
+            None,
+            &[
+                (&[CONFIG_KEY_MODEL], "gpt-5"),
+                (&[CONFIG_KEY_EFFORT], "minimal"),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"# Top-level comments
+# should be preserved
+
+existing = "keep"
+model = "gpt-5"
+model_reasoning_effort = "minimal"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies errors on invalid TOML propagate and file is not clobbered.
+    #[tokio::test]
+    async fn persist_overrides_errors_on_parse_failure() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Write an intentionally invalid TOML file
+        let invalid = "invalid = [unclosed";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), invalid)
+            .await
+            .expect("seed write");
+
+        // Attempting to persist should return an error and must not clobber the file.
+        let res = persist_overrides(codex_home, None, &[(&["x"], "y")]).await;
+        assert!(res.is_err(), "expected parse error to propagate");
+
+        // File should be unchanged
+        let contents = read_config(codex_home).await;
+        assert_eq!(contents, invalid);
+    }
+
+    /// Verifies changing model only preserves existing effort at top-level.
+    #[tokio::test]
+    async fn changing_only_model_preserves_existing_effort_top_level() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed with an effort value only
+        let seed = "model_reasoning_effort = \"minimal\"\n";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        // Change only the model
+        persist_overrides(codex_home, None, &[(&[CONFIG_KEY_MODEL], "o3")])
+            .await
+            .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"model_reasoning_effort = "minimal"
+model = "o3"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies changing effort only preserves existing model at top-level.
+    #[tokio::test]
+    async fn changing_only_effort_preserves_existing_model_top_level() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed with a model value only
+        let seed = "model = \"gpt-5\"\n";
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        // Change only the effort
+        persist_overrides(codex_home, None, &[(&[CONFIG_KEY_EFFORT], "high")])
+            .await
+            .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"model = "gpt-5"
+model_reasoning_effort = "high"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies changing model only preserves existing effort in active profile.
+    #[tokio::test]
+    async fn changing_only_model_preserves_effort_in_active_profile() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // Seed with an active profile and an existing effort under that profile
+        let seed = r#"profile = "p1"
+
+[profiles.p1]
+model_reasoning_effort = "low"
+"#;
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        persist_overrides(codex_home, None, &[(&[CONFIG_KEY_MODEL], "o4-mini")])
+            .await
+            .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"profile = "p1"
+
+[profiles.p1]
+model_reasoning_effort = "low"
+model = "o4-mini"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies changing effort only preserves existing model in a profile override.
+    #[tokio::test]
+    async fn changing_only_effort_preserves_model_in_profile_override() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        // No active profile key; we'll target an explicit override
+        let seed = r#"[profiles.team]
+model = "gpt-5"
+"#;
+        tokio::fs::write(codex_home.join(CONFIG_TOML_FILE), seed)
+            .await
+            .expect("seed write");
+
+        persist_overrides(
+            codex_home,
+            Some("team"),
+            &[(&[CONFIG_KEY_EFFORT], "minimal")],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"[profiles.team]
+model = "gpt-5"
+model_reasoning_effort = "minimal"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies `persist_non_null_overrides` skips `None` entries and writes only present values at top-level.
+    #[tokio::test]
+    async fn persist_non_null_skips_none_top_level() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        persist_non_null_overrides(
+            codex_home,
+            None,
+            &[
+                (&[CONFIG_KEY_MODEL], Some("gpt-5")),
+                (&[CONFIG_KEY_EFFORT], None),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = "model = \"gpt-5\"\n";
+        assert_eq!(contents, expected);
+    }
+
+    /// Verifies no-op behavior when all provided overrides are `None` (no file created/modified).
+    #[tokio::test]
+    async fn persist_non_null_noop_when_all_none() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        persist_non_null_overrides(
+            codex_home,
+            None,
+            &[(&["a"], None), (&["profiles", "p", "x"], None)],
+        )
+        .await
+        .expect("persist");
+
+        // Should not create config.toml on a pure no-op
+        assert!(!codex_home.join(CONFIG_TOML_FILE).exists());
+    }
+
+    /// Verifies entries are written under the specified profile and `None` entries are skipped.
+    #[tokio::test]
+    async fn persist_non_null_respects_profile_override() {
+        let tmpdir = tempdir().expect("tmp");
+        let codex_home = tmpdir.path();
+
+        persist_non_null_overrides(
+            codex_home,
+            Some("team"),
+            &[
+                (&[CONFIG_KEY_MODEL], Some("o3")),
+                (&[CONFIG_KEY_EFFORT], None),
+            ],
+        )
+        .await
+        .expect("persist");
+
+        let contents = read_config(codex_home).await;
+        let expected = r#"[profiles.team]
+model = "o3"
+"#;
+        assert_eq!(contents, expected);
+    }
+
+    // Test helper moved to bottom per review guidance.
+    async fn read_config(codex_home: &Path) -> String {
+        let p = codex_home.join(CONFIG_TOML_FILE);
+        tokio::fs::read_to_string(p).await.unwrap_or_default()
+    }
+}

codex-rs/core/src/lib.rs

@@ -16,6 +16,7 @@ mod codex_conversation;
 pub mod token_data;
 pub use codex_conversation::CodexConversation;
 pub mod config;
+pub mod config_edit;
 pub mod config_profile;
 pub mod config_types;
 mod conversation_history;

codex-rs/mcp-server/src/message_processor.rs

@@ -238,7 +238,7 @@ impl MessageProcessor {
                 name: "codex-mcp-server".to_string(),
                 version: env!("CARGO_PKG_VERSION").to_string(),
                 title: Some("Codex".to_string()),
-                user_agent: get_codex_user_agent(),
+                user_agent: Some(get_codex_user_agent()),
             },
         };
 

codex-rs/mcp-types/src/lib.rs

@@ -496,7 +496,8 @@ pub struct McpServerInfo {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub title: Option<String>,
     pub version: String,
-    pub user_agent: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub user_agent: Option<String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, TS)]

codex-rs/tui/src/lib.rs

@@ -269,17 +269,21 @@ async fn run_ratatui_app(
             format!("{current_version} -> {latest_version}.").into(),
         ]));
 
-        let knows_update_command = managed_by_npm
-            || (cfg!(target_os = "macos")
-                && (exe.starts_with("/opt/homebrew") || exe.starts_with("/usr/local")));
-
-        if knows_update_command {
+        if managed_by_npm {
+            let npm_cmd = "npm install -g @openai/codex@latest";
             lines.push(Line::from(vec![
                 "Run ".into(),
-                "codex update".cyan(),
-                " (or ".into(),
-                "codex upgrade".cyan(),
-                ") to update automatically.".into(),
+                npm_cmd.cyan(),
+                " to update.".into(),
+            ]));
+        } else if cfg!(target_os = "macos")
+            && (exe.starts_with("/opt/homebrew") || exe.starts_with("/usr/local"))
+        {
+            let brew_cmd = "brew upgrade codex";
+            lines.push(Line::from(vec![
+                "Run ".into(),
+                brew_cmd.cyan(),
+                " to update.".into(),
             ]));
         } else {
             lines.push(Line::from(vec![

codex-rs/tui/src/updates.rs

@@ -109,7 +109,6 @@ fn parse_version(v: &str) -> Option<(u64, u64, u64)> {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use pretty_assertions::assert_eq;
 
     #[test]
     fn prerelease_version_is_not_considered_newer() {