From d47b85d9fe04c4e459d7e9d2644a18773380b0de Mon Sep 17 00:00:00 2001 From: Sayan Sisodiya Date: Thu, 8 Jan 2026 16:10:28 -0800 Subject: [PATCH] wip; add jsonschema for config.toml --- codex-rs/Cargo.lock | 2 + codex-rs/core/Cargo.toml | 1 + codex-rs/core/src/auth/storage.rs | 3 +- codex-rs/core/src/config/mod.rs | 12 +- codex-rs/core/src/config/profile.rs | 4 +- codex-rs/core/src/config/schema.rs | 158 +++ codex-rs/core/src/config/types.rs | 33 +- codex-rs/core/src/features.rs | 3 +- codex-rs/core/src/model_provider_info.rs | 5 +- codex-rs/rmcp-client/Cargo.toml | 1 + codex-rs/rmcp-client/src/oauth.rs | 3 +- docs/config.md | 4 + docs/config.schema.json | 1374 ++++++++++++++++++++++ 13 files changed, 1577 insertions(+), 26 deletions(-) create mode 100644 codex-rs/core/src/config/schema.rs create mode 100644 docs/config.schema.json diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lock index 29be64f9a9..38ff6df18a 100644 --- a/codex-rs/Cargo.lock +++ b/codex-rs/Cargo.lock @@ -1320,6 +1320,7 @@ dependencies = [ "regex", "regex-lite", "reqwest", + "schemars 0.8.22", "seccompiler", "serde", "serde_json", @@ -1699,6 +1700,7 @@ dependencies = [ "pretty_assertions", "reqwest", "rmcp", + "schemars 0.8.22", "serde", "serde_json", "serial_test", diff --git a/codex-rs/core/Cargo.toml b/codex-rs/core/Cargo.toml index d3ee08c03b..860ecce35b 100644 --- a/codex-rs/core/Cargo.toml +++ b/codex-rs/core/Cargo.toml @@ -58,6 +58,7 @@ reqwest = { workspace = true, features = ["json", "stream"] } serde = { workspace = true, features = ["derive"] } serde_json = { workspace = true } serde_yaml = { workspace = true } +schemars = { workspace = true } sha1 = { workspace = true } sha2 = { workspace = true } shlex = { workspace = true } diff --git a/codex-rs/core/src/auth/storage.rs b/codex-rs/core/src/auth/storage.rs index a238eb9c38..48b67aca05 100644 --- a/codex-rs/core/src/auth/storage.rs +++ b/codex-rs/core/src/auth/storage.rs @@ -1,5 +1,6 @@ use chrono::DateTime; use chrono::Utc; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; use sha2::Digest; @@ -21,7 +22,7 @@ use codex_keyring_store::DefaultKeyringStore; use codex_keyring_store::KeyringStore; /// Determine where Codex should store CLI auth credentials. -#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "lowercase")] pub enum AuthCredentialsStoreMode { #[default] diff --git a/codex-rs/core/src/config/mod.rs b/codex-rs/core/src/config/mod.rs index 7b483f944f..b374ab537e 100644 --- a/codex-rs/core/src/config/mod.rs +++ b/codex-rs/core/src/config/mod.rs @@ -43,6 +43,7 @@ use codex_rmcp_client::OAuthCredentialsStoreMode; use codex_utils_absolute_path::AbsolutePathBuf; use codex_utils_absolute_path::AbsolutePathBufGuard; use dirs::home_dir; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; use similar::DiffableStr; @@ -61,6 +62,7 @@ use toml_edit::DocumentMut; mod constraint; pub mod edit; pub mod profile; +pub mod schema; pub mod service; pub mod types; pub use constraint::Constrained; @@ -682,7 +684,7 @@ pub fn set_default_oss_provider(codex_home: &Path, provider: &str) -> std::io::R } /// Base config deserialized from ~/.codex/config.toml. -#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)] pub struct ConfigToml { /// Optional override of model selection. pub model: Option, @@ -741,6 +743,7 @@ pub struct ConfigToml { /// Definition for MCP servers that Codex can reach out to for tool calls. #[serde(default)] + #[schemars(schema_with = "crate::config::schema::mcp_servers_schema")] pub mcp_servers: HashMap, /// Preferred backend for storing MCP OAuth credentials. @@ -808,6 +811,7 @@ pub struct ConfigToml { /// Centralized feature flags (new). Prefer this over individual toggles. #[serde(default)] + #[schemars(schema_with = "crate::config::schema::features_schema")] pub features: Option, /// Settings for ghost snapshots (used for undo). @@ -881,7 +885,7 @@ impl From for UserSavedConfig { } } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema)] pub struct ProjectConfig { pub trust_level: Option, } @@ -896,7 +900,7 @@ impl ProjectConfig { } } -#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)] pub struct ToolsToml { #[serde(default, alias = "web_search_request")] pub web_search: Option, @@ -915,7 +919,7 @@ impl From for Tools { } } -#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)] +#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, JsonSchema)] pub struct GhostSnapshotToml { /// Exclude untracked files larger than this many bytes from ghost snapshots. #[serde(alias = "ignore_untracked_files_over_bytes")] diff --git a/codex-rs/core/src/config/profile.rs b/codex-rs/core/src/config/profile.rs index e1c45c1f16..8d01c425e8 100644 --- a/codex-rs/core/src/config/profile.rs +++ b/codex-rs/core/src/config/profile.rs @@ -1,4 +1,5 @@ use codex_utils_absolute_path::AbsolutePathBuf; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; @@ -10,7 +11,7 @@ use codex_protocol::openai_models::ReasoningEffort; /// Collection of common configuration options that a user can define as a unit /// in `config.toml`. -#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] +#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)] pub struct ConfigProfile { pub model: Option, /// The key in the `model_providers` map identifying the @@ -32,6 +33,7 @@ pub struct ConfigProfile { pub analytics: Option, /// Optional feature toggles scoped to this profile. #[serde(default)] + #[schemars(schema_with = "crate::config::schema::features_schema")] pub features: Option, pub oss_provider: Option, } diff --git a/codex-rs/core/src/config/schema.rs b/codex-rs/core/src/config/schema.rs new file mode 100644 index 0000000000..d89f010be4 --- /dev/null +++ b/codex-rs/core/src/config/schema.rs @@ -0,0 +1,158 @@ +#[cfg(test)] +use crate::config::ConfigToml; +use crate::features::FEATURES; +use schemars::JsonSchema; +use schemars::r#gen::SchemaGenerator; +#[cfg(test)] +use schemars::r#gen::SchemaSettings; +use schemars::schema::InstanceType; +use schemars::schema::ObjectValidation; +#[cfg(test)] +use schemars::schema::RootSchema; +use schemars::schema::Schema; +use schemars::schema::SchemaObject; +use schemars::schema::SubschemaValidation; +use serde::Deserialize; +use serde::Serialize; +use std::collections::HashMap; +#[cfg(test)] +use std::path::Path; + +#[cfg(test)] +pub(crate) fn config_schema() -> RootSchema { + SchemaSettings::draft07() + .with(|settings| { + settings.option_add_null_type = false; + }) + .into_generator() + .into_root_schema_for::() +} + +#[cfg(test)] +pub(crate) fn write_config_schema(out_path: &Path) -> anyhow::Result<()> { + let schema = config_schema(); + let json = serde_json::to_vec_pretty(&schema)?; + std::fs::write(out_path, json)?; + Ok(()) +} + +pub(crate) fn features_schema(schema_gen: &mut SchemaGenerator) -> Schema { + let mut object = SchemaObject { + instance_type: Some(InstanceType::Object.into()), + ..Default::default() + }; + + let mut validation = ObjectValidation::default(); + for feature in FEATURES { + validation + .properties + .insert(feature.key.to_string(), schema_gen.subschema_for::()); + } + validation.additional_properties = Some(Box::new(schema_gen.subschema_for::())); + object.object = Some(Box::new(validation)); + + Schema::Object(object) +} + +pub(crate) fn mcp_servers_schema(schema_gen: &mut SchemaGenerator) -> Schema { + let mut object = SchemaObject { + instance_type: Some(InstanceType::Object.into()), + ..Default::default() + }; + + let validation = ObjectValidation { + additional_properties: Some(Box::new(mcp_server_schema(schema_gen))), + ..Default::default() + }; + object.object = Some(Box::new(validation)); + + Schema::Object(object) +} + +fn mcp_server_schema(schema_gen: &mut SchemaGenerator) -> Schema { + let server = SchemaObject { + subschemas: Some(Box::new(SubschemaValidation { + one_of: Some(vec![ + schema_gen.subschema_for::(), + schema_gen.subschema_for::(), + ]), + ..Default::default() + })), + ..Default::default() + }; + Schema::Object(server) +} + +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] +struct McpServerStdioSchema { + command: String, + #[serde(default)] + args: Option>, + #[serde(default)] + env: Option>, + #[serde(default)] + env_vars: Option>, + #[serde(default)] + cwd: Option, + #[serde(default)] + enabled: Option, + #[serde(default)] + startup_timeout_sec: Option, + #[serde(default)] + startup_timeout_ms: Option, + #[serde(default)] + tool_timeout_sec: Option, + #[serde(default)] + enabled_tools: Option>, + #[serde(default)] + disabled_tools: Option>, +} + +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] +struct McpServerStreamableHttpSchema { + url: String, + #[serde(default)] + bearer_token_env_var: Option, + #[serde(default)] + http_headers: Option>, + #[serde(default)] + env_http_headers: Option>, + #[serde(default)] + enabled: Option, + #[serde(default)] + startup_timeout_sec: Option, + #[serde(default)] + startup_timeout_ms: Option, + #[serde(default)] + tool_timeout_sec: Option, + #[serde(default)] + enabled_tools: Option>, + #[serde(default)] + disabled_tools: Option>, +} + +#[cfg(test)] +mod tests { + use super::*; + use pretty_assertions::assert_eq; + + #[test] + fn config_schema_matches_fixture() { + let schema = config_schema(); + let schema_value = serde_json::to_value(schema).expect("serialize config schema"); + let fixture_path = codex_utils_cargo_bin::find_resource!("../../docs/config.schema.json") + .expect("resolve config schema fixture path"); + let fixture = std::fs::read_to_string(fixture_path).expect("read config schema fixture"); + let fixture_value: serde_json::Value = + serde_json::from_str(&fixture).expect("parse config schema fixture"); + assert_eq!(fixture_value, schema_value); + } + + #[test] + #[ignore] + fn write_config_schema_fixture() { + let fixture_path = codex_utils_cargo_bin::find_resource!("../../docs/config.schema.json") + .expect("resolve config schema fixture path"); + write_config_schema(&fixture_path).expect("write config schema fixture"); + } +} diff --git a/codex-rs/core/src/config/types.rs b/codex-rs/core/src/config/types.rs index 2b41c3c52f..36f140ed92 100644 --- a/codex-rs/core/src/config/types.rs +++ b/codex-rs/core/src/config/types.rs @@ -11,6 +11,7 @@ use std::path::PathBuf; use std::time::Duration; use wildmatch::WildMatchPattern; +use schemars::JsonSchema; use serde::Deserialize; use serde::Deserializer; use serde::Serialize; @@ -164,7 +165,7 @@ const fn default_enabled() -> bool { true } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)] #[serde(untagged, deny_unknown_fields, rename_all = "snake_case")] pub enum McpServerTransportConfig { /// https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio @@ -222,7 +223,7 @@ mod option_duration_secs { } } -#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, JsonSchema)] pub enum UriBasedFileOpener { #[serde(rename = "vscode")] VsCode, @@ -254,7 +255,7 @@ impl UriBasedFileOpener { } /// Settings that govern if and what will be written to `~/.codex/history.jsonl`. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct History { /// If true, history entries will not be written to disk. pub persistence: HistoryPersistence, @@ -264,7 +265,7 @@ pub struct History { pub max_bytes: Option, } -#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Copy, Clone, PartialEq, Default, JsonSchema)] #[serde(rename_all = "kebab-case")] pub enum HistoryPersistence { /// Save all history entries to disk. @@ -277,7 +278,7 @@ pub enum HistoryPersistence { // ===== Analytics configuration ===== /// Analytics settings loaded from config.toml. Fields are optional so we can apply defaults. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct AnalyticsConfigToml { /// When `false`, disables analytics across Codex product surfaces in this profile. pub enabled: Option, @@ -291,7 +292,7 @@ pub struct FeedbackConfigToml { // ===== OTEL configuration ===== -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)] #[serde(rename_all = "kebab-case")] pub enum OtelHttpProtocol { /// Binary payload @@ -300,7 +301,7 @@ pub enum OtelHttpProtocol { Json, } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] #[serde(rename_all = "kebab-case")] pub struct OtelTlsConfig { pub ca_certificate: Option, @@ -309,7 +310,7 @@ pub struct OtelTlsConfig { } /// Which OTEL exporter to use. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, JsonSchema)] #[serde(rename_all = "kebab-case")] pub enum OtelExporterKind { None, @@ -332,7 +333,7 @@ pub enum OtelExporterKind { } /// OTEL settings loaded from config.toml. Fields are optional so we can apply defaults. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct OtelConfigToml { /// Log user prompt in traces pub log_user_prompt: Option, @@ -369,7 +370,7 @@ impl Default for OtelConfig { } } -#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize)] +#[derive(Serialize, Debug, Clone, PartialEq, Eq, Deserialize, JsonSchema)] #[serde(untagged)] pub enum Notifications { Enabled(bool), @@ -387,7 +388,7 @@ impl Default for Notifications { /// Terminals generally encode both mouse wheels and trackpads as the same "scroll up/down" mouse /// button events, without a magnitude. This setting controls whether Codex uses a heuristic to /// infer wheel vs trackpad per stream, or forces a specific behavior. -#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema)] #[serde(rename_all = "snake_case")] pub enum ScrollInputMode { /// Infer wheel vs trackpad behavior per scroll stream. @@ -405,7 +406,7 @@ impl Default for ScrollInputMode { } /// Collection of settings that are specific to the TUI. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct Tui { /// Enable desktop notifications from the TUI when the terminal is unfocused. /// Defaults to `true`. @@ -544,7 +545,7 @@ const fn default_true() -> bool { /// Settings for notices we display to users via the tui and app-server clients /// (primarily the Codex IDE extension). NOTE: these are different from /// notifications - notices are warnings, NUX screens, acknowledgements, etc. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct Notice { /// Tracks whether the user has acknowledged the full access warning prompt. pub hide_full_access_warning: Option, @@ -567,7 +568,7 @@ impl Notice { pub(crate) const TABLE_KEY: &'static str = "notice"; } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct SandboxWorkspaceWrite { #[serde(default)] pub writable_roots: Vec, @@ -590,7 +591,7 @@ impl From for codex_app_server_protocol::SandboxSettings } } -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] #[serde(rename_all = "kebab-case")] pub enum ShellEnvironmentPolicyInherit { /// "Core" environment variables for the platform. On UNIX, this would @@ -607,7 +608,7 @@ pub enum ShellEnvironmentPolicyInherit { /// Policy for building the `env` when spawning a process via either the /// `shell` or `local_shell` tool. -#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default)] +#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Default, JsonSchema)] pub struct ShellEnvironmentPolicyToml { pub inherit: Option, diff --git a/codex-rs/core/src/features.rs b/codex-rs/core/src/features.rs index 8c1c597ee7..bff8338511 100644 --- a/codex-rs/core/src/features.rs +++ b/codex-rs/core/src/features.rs @@ -8,6 +8,7 @@ use crate::config::ConfigToml; use crate::config::profile::ConfigProfile; use codex_otel::OtelManager; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; use std::collections::BTreeMap; @@ -292,7 +293,7 @@ pub fn is_known_feature_key(key: &str) -> bool { } /// Deserializable features table for TOML. -#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)] +#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, JsonSchema)] pub struct FeaturesToml { #[serde(flatten)] pub entries: BTreeMap, diff --git a/codex-rs/core/src/model_provider_info.rs b/codex-rs/core/src/model_provider_info.rs index 9617392237..8f2501dec3 100644 --- a/codex-rs/core/src/model_provider_info.rs +++ b/codex-rs/core/src/model_provider_info.rs @@ -12,6 +12,7 @@ use codex_app_server_protocol::AuthMode; use http::HeaderMap; use http::header::HeaderName; use http::header::HeaderValue; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; use std::collections::HashMap; @@ -36,7 +37,7 @@ const OPENAI_PROVIDER_NAME: &str = "OpenAI"; /// *Responses* API. The two protocols use different request/response shapes /// and *cannot* be auto-detected at runtime, therefore each provider entry /// must declare which one it expects. -#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "lowercase")] pub enum WireApi { /// The Responses API exposed by OpenAI at `/v1/responses`. @@ -48,7 +49,7 @@ pub enum WireApi { } /// Serializable representation of a provider definition. -#[derive(Debug, Clone, Deserialize, Serialize, PartialEq)] +#[derive(Debug, Clone, Deserialize, Serialize, PartialEq, JsonSchema)] pub struct ModelProviderInfo { /// Friendly display name. pub name: String, diff --git a/codex-rs/rmcp-client/Cargo.toml b/codex-rs/rmcp-client/Cargo.toml index efcea2d805..8aa7512faf 100644 --- a/codex-rs/rmcp-client/Cargo.toml +++ b/codex-rs/rmcp-client/Cargo.toml @@ -36,6 +36,7 @@ rmcp = { workspace = true, default-features = false, features = [ "transport-streamable-http-client-reqwest", "transport-streamable-http-server", ] } +schemars = { workspace = true } serde = { workspace = true, features = ["derive"] } serde_json = { workspace = true } sha2 = { workspace = true } diff --git a/codex-rs/rmcp-client/src/oauth.rs b/codex-rs/rmcp-client/src/oauth.rs index f8eafaf23e..a3a256374b 100644 --- a/codex-rs/rmcp-client/src/oauth.rs +++ b/codex-rs/rmcp-client/src/oauth.rs @@ -26,6 +26,7 @@ use oauth2::Scope; use oauth2::TokenResponse; use oauth2::basic::BasicTokenType; use rmcp::transport::auth::OAuthTokenResponse; +use schemars::JsonSchema; use serde::Deserialize; use serde::Serialize; use serde_json::Value; @@ -63,7 +64,7 @@ pub struct StoredOAuthTokens { } /// Determine where Codex should store and read MCP credentials. -#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Default, Copy, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "lowercase")] pub enum OAuthCredentialsStoreMode { /// `Keyring` when available; otherwise, `File`. diff --git a/docs/config.md b/docs/config.md index 2b64253d30..934f3954f2 100644 --- a/docs/config.md +++ b/docs/config.md @@ -17,3 +17,7 @@ Codex can connect to MCP servers configured in `~/.codex/config.toml`. See the c Codex can run a notification hook when the agent finishes a turn. See the configuration reference for the latest notification settings: - https://developers.openai.com/codex/config-reference + +## JSON Schema + +The generated JSON Schema for `config.toml` lives at `docs/config.schema.json`. diff --git a/docs/config.schema.json b/docs/config.schema.json new file mode 100644 index 0000000000..7dadfd4c9f --- /dev/null +++ b/docs/config.schema.json @@ -0,0 +1,1374 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "ConfigToml", + "description": "Base config deserialized from ~/.codex/config.toml.", + "type": "object", + "properties": { + "analytics": { + "description": "When `false`, disables analytics across Codex product surfaces in this machine. Defaults to `true`.", + "allOf": [ + { + "$ref": "#/definitions/AnalyticsConfigToml" + } + ] + }, + "approval_policy": { + "description": "Default approval policy for executing commands.", + "allOf": [ + { + "$ref": "#/definitions/AskForApproval" + } + ] + }, + "chatgpt_base_url": { + "description": "Base URL for requests to ChatGPT (as opposed to the OpenAI API).", + "type": "string" + }, + "check_for_update_on_startup": { + "description": "When `true`, checks for Codex updates on startup and surfaces update prompts. Set to `false` only if your Codex updates are centrally managed. Defaults to `true`.", + "type": "boolean" + }, + "cli_auth_credentials_store": { + "description": "Preferred backend for storing CLI auth credentials. file (default): Use a file in the Codex home directory. keyring: Use an OS-specific keyring service. auto: Use the keyring if available, otherwise use a file.", + "default": null, + "allOf": [ + { + "$ref": "#/definitions/AuthCredentialsStoreMode" + } + ] + }, + "compact_prompt": { + "description": "Compact prompt used for history compaction.", + "type": "string" + }, + "developer_instructions": { + "description": "Developer instructions inserted as a `developer` role message.", + "default": null, + "type": "string" + }, + "disable_paste_burst": { + "description": "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.", + "type": "boolean" + }, + "experimental_compact_prompt_file": { + "$ref": "#/definitions/AbsolutePathBuf" + }, + "experimental_instructions_file": { + "description": "Legacy, now use features", + "allOf": [ + { + "$ref": "#/definitions/AbsolutePathBuf" + } + ] + }, + "experimental_use_freeform_apply_patch": { + "type": "boolean" + }, + "experimental_use_unified_exec_tool": { + "type": "boolean" + }, + "features": { + "description": "Centralized feature flags (new). Prefer this over individual toggles.", + "default": null, + "type": "object", + "properties": { + "apply_patch_freeform": { + "type": "boolean" + }, + "elevated_windows_sandbox": { + "type": "boolean" + }, + "enable_request_compression": { + "type": "boolean" + }, + "exec_policy": { + "type": "boolean" + }, + "experimental_windows_sandbox": { + "type": "boolean" + }, + "powershell_utf8": { + "type": "boolean" + }, + "remote_compaction": { + "type": "boolean" + }, + "remote_models": { + "type": "boolean" + }, + "shell_snapshot": { + "type": "boolean" + }, + "shell_tool": { + "type": "boolean" + }, + "tui2": { + "type": "boolean" + }, + "undo": { + "type": "boolean" + }, + "unified_exec": { + "type": "boolean" + }, + "web_search_cached": { + "type": "boolean" + }, + "web_search_request": { + "type": "boolean" + } + }, + "additionalProperties": { + "type": "boolean" + } + }, + "file_opener": { + "description": "Optional URI-based file opener. If set, citations to files in the model output will be hyperlinked using the specified URI scheme.", + "allOf": [ + { + "$ref": "#/definitions/UriBasedFileOpener" + } + ] + }, + "forced_chatgpt_workspace_id": { + "description": "When set, restricts ChatGPT login to a specific workspace identifier.", + "default": null, + "type": "string" + }, + "forced_login_method": { + "description": "When set, restricts the login mechanism users may use.", + "default": null, + "allOf": [ + { + "$ref": "#/definitions/ForcedLoginMethod" + } + ] + }, + "ghost_snapshot": { + "description": "Settings for ghost snapshots (used for undo).", + "default": null, + "allOf": [ + { + "$ref": "#/definitions/GhostSnapshotToml" + } + ] + }, + "hide_agent_reasoning": { + "description": "When set to `true`, `AgentReasoning` events will be hidden from the UI/output. Defaults to `false`.", + "type": "boolean" + }, + "history": { + "description": "Settings that govern if and what will be written to `~/.codex/history.jsonl`.", + "default": null, + "allOf": [ + { + "$ref": "#/definitions/History" + } + ] + }, + "instructions": { + "description": "System instructions.", + "type": "string" + }, + "mcp_oauth_credentials_store": { + "description": "Preferred backend for storing MCP OAuth credentials. keyring: Use an OS-specific keyring service. https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/oauth.rs#L2 file: Use a file in the Codex home directory. auto (default): Use the OS-specific keyring service if available, otherwise use a file.", + "default": null, + "allOf": [ + { + "$ref": "#/definitions/OAuthCredentialsStoreMode" + } + ] + }, + "mcp_servers": { + "description": "Definition for MCP servers that Codex can reach out to for tool calls.", + "default": {}, + "type": "object", + "additionalProperties": { + "oneOf": [ + { + "$ref": "#/definitions/McpServerStdioSchema" + }, + { + "$ref": "#/definitions/McpServerStreamableHttpSchema" + } + ] + } + }, + "model": { + "description": "Optional override of model selection.", + "type": "string" + }, + "model_auto_compact_token_limit": { + "description": "Token usage threshold triggering auto-compaction of conversation history.", + "type": "integer", + "format": "int64" + }, + "model_context_window": { + "description": "Size of the context window for the model, in tokens.", + "type": "integer", + "format": "int64" + }, + "model_provider": { + "description": "Provider to use from the model_providers map.", + "type": "string" + }, + "model_providers": { + "description": "User-defined provider entries that extend/override the built-in list.", + "default": {}, + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ModelProviderInfo" + } + }, + "model_reasoning_effort": { + "$ref": "#/definitions/ReasoningEffort" + }, + "model_reasoning_summary": { + "$ref": "#/definitions/ReasoningSummary" + }, + "model_supports_reasoning_summaries": { + "description": "Override to force-enable reasoning summaries for the configured model.", + "type": "boolean" + }, + "model_verbosity": { + "description": "Optional verbosity control for GPT-5 models (Responses API `text.verbosity`).", + "allOf": [ + { + "$ref": "#/definitions/Verbosity" + } + ] + }, + "notice": { + "description": "Collection of in-product notices (different from notifications) See [`crate::config::types::Notices`] for more details", + "allOf": [ + { + "$ref": "#/definitions/Notice" + } + ] + }, + "notify": { + "description": "Optional external command to spawn for end-user notifications.", + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "oss_provider": { + "description": "Preferred OSS provider for local models, e.g. \"lmstudio\" or \"ollama\".", + "type": "string" + }, + "otel": { + "description": "OTEL configuration.", + "allOf": [ + { + "$ref": "#/definitions/OtelConfigToml" + } + ] + }, + "profile": { + "description": "Profile to use from the `profiles` map.", + "type": "string" + }, + "profiles": { + "description": "Named profiles to facilitate switching between different configurations.", + "default": {}, + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ConfigProfile" + } + }, + "project_doc_fallback_filenames": { + "description": "Ordered list of fallback filenames to look for when AGENTS.md is missing.", + "type": "array", + "items": { + "type": "string" + } + }, + "project_doc_max_bytes": { + "description": "Maximum number of bytes to include from an AGENTS.md project doc file.", + "type": "integer", + "format": "uint", + "minimum": 0.0 + }, + "project_root_markers": { + "description": "Markers used to detect the project root when searching parent directories for `.codex` folders. Defaults to [\".git\"] when unset.", + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "projects": { + "type": "object", + "additionalProperties": { + "$ref": "#/definitions/ProjectConfig" + } + }, + "review_model": { + "description": "Review model override used by the `/review` feature.", + "type": "string" + }, + "sandbox_mode": { + "description": "Sandbox mode to use.", + "allOf": [ + { + "$ref": "#/definitions/SandboxMode" + } + ] + }, + "sandbox_workspace_write": { + "description": "Sandbox configuration to apply if `sandbox` is `WorkspaceWrite`.", + "allOf": [ + { + "$ref": "#/definitions/SandboxWorkspaceWrite" + } + ] + }, + "shell_environment_policy": { + "default": { + "exclude": null, + "experimental_use_profile": null, + "ignore_default_excludes": null, + "include_only": null, + "inherit": null, + "set": null + }, + "allOf": [ + { + "$ref": "#/definitions/ShellEnvironmentPolicyToml" + } + ] + }, + "show_raw_agent_reasoning": { + "description": "When set to `true`, `AgentReasoningRawContentEvent` events will be shown in the UI/output. Defaults to `false`.", + "type": "boolean" + }, + "tool_output_token_limit": { + "description": "Token budget applied when storing tool/function outputs in the context manager.", + "type": "integer", + "format": "uint", + "minimum": 0.0 + }, + "tools": { + "description": "Nested tools section for feature toggles", + "allOf": [ + { + "$ref": "#/definitions/ToolsToml" + } + ] + }, + "tui": { + "description": "Collection of settings that are specific to the TUI.", + "allOf": [ + { + "$ref": "#/definitions/Tui" + } + ] + }, + "windows_wsl_setup_acknowledged": { + "description": "Tracks whether the Windows onboarding screen has been acknowledged.", + "type": "boolean" + } + }, + "definitions": { + "AbsolutePathBuf": { + "description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.", + "type": "string" + }, + "AnalyticsConfigToml": { + "description": "Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.", + "type": "object", + "properties": { + "enabled": { + "description": "When `false`, disables analytics across Codex product surfaces in this profile.", + "type": "boolean" + } + } + }, + "AskForApproval": { + "description": "Determines the conditions under which the user is consulted to approve running the command proposed by Codex.", + "oneOf": [ + { + "description": "Under this policy, only \"known safe\" commands—as determined by `is_safe_command()`—that **only read files** are auto‑approved. Everything else will ask the user to approve.", + "type": "string", + "enum": [ + "untrusted" + ] + }, + { + "description": "*All* commands are auto‑approved, but they are expected to run inside a sandbox where network access is disabled and writes are confined to a specific set of paths. If the command fails, it will be escalated to the user to approve execution without a sandbox.", + "type": "string", + "enum": [ + "on-failure" + ] + }, + { + "description": "The model decides when to ask the user for approval.", + "type": "string", + "enum": [ + "on-request" + ] + }, + { + "description": "Never ask the user to approve commands. Failures are immediately returned to the model, and never escalated to the user for approval.", + "type": "string", + "enum": [ + "never" + ] + } + ] + }, + "AuthCredentialsStoreMode": { + "description": "Determine where Codex should store CLI auth credentials.", + "oneOf": [ + { + "description": "Persist credentials in CODEX_HOME/auth.json.", + "type": "string", + "enum": [ + "file" + ] + }, + { + "description": "Persist credentials in the keyring. Fail if unavailable.", + "type": "string", + "enum": [ + "keyring" + ] + }, + { + "description": "Use keyring when available; otherwise, fall back to a file in CODEX_HOME.", + "type": "string", + "enum": [ + "auto" + ] + } + ] + }, + "ConfigProfile": { + "description": "Collection of common configuration options that a user can define as a unit in `config.toml`.", + "type": "object", + "properties": { + "analytics": { + "$ref": "#/definitions/AnalyticsConfigToml" + }, + "approval_policy": { + "$ref": "#/definitions/AskForApproval" + }, + "chatgpt_base_url": { + "type": "string" + }, + "experimental_compact_prompt_file": { + "$ref": "#/definitions/AbsolutePathBuf" + }, + "experimental_instructions_file": { + "$ref": "#/definitions/AbsolutePathBuf" + }, + "experimental_use_freeform_apply_patch": { + "type": "boolean" + }, + "experimental_use_unified_exec_tool": { + "type": "boolean" + }, + "features": { + "description": "Optional feature toggles scoped to this profile.", + "default": null, + "type": "object", + "properties": { + "apply_patch_freeform": { + "type": "boolean" + }, + "elevated_windows_sandbox": { + "type": "boolean" + }, + "enable_request_compression": { + "type": "boolean" + }, + "exec_policy": { + "type": "boolean" + }, + "experimental_windows_sandbox": { + "type": "boolean" + }, + "powershell_utf8": { + "type": "boolean" + }, + "remote_compaction": { + "type": "boolean" + }, + "remote_models": { + "type": "boolean" + }, + "shell_snapshot": { + "type": "boolean" + }, + "shell_tool": { + "type": "boolean" + }, + "tui2": { + "type": "boolean" + }, + "undo": { + "type": "boolean" + }, + "unified_exec": { + "type": "boolean" + }, + "web_search_cached": { + "type": "boolean" + }, + "web_search_request": { + "type": "boolean" + } + }, + "additionalProperties": { + "type": "boolean" + } + }, + "include_apply_patch_tool": { + "type": "boolean" + }, + "model": { + "type": "string" + }, + "model_provider": { + "description": "The key in the `model_providers` map identifying the [`ModelProviderInfo`] to use.", + "type": "string" + }, + "model_reasoning_effort": { + "$ref": "#/definitions/ReasoningEffort" + }, + "model_reasoning_summary": { + "$ref": "#/definitions/ReasoningSummary" + }, + "model_verbosity": { + "$ref": "#/definitions/Verbosity" + }, + "oss_provider": { + "type": "string" + }, + "sandbox_mode": { + "$ref": "#/definitions/SandboxMode" + }, + "tools_view_image": { + "type": "boolean" + }, + "tools_web_search": { + "type": "boolean" + } + } + }, + "ForcedLoginMethod": { + "type": "string", + "enum": [ + "chatgpt", + "api" + ] + }, + "GhostSnapshotToml": { + "type": "object", + "properties": { + "disable_warnings": { + "description": "Disable all ghost snapshot warning events.", + "type": "boolean" + }, + "ignore_large_untracked_dirs": { + "description": "Ignore untracked directories that contain this many files or more. (Still emits a warning unless warnings are disabled.)", + "type": "integer", + "format": "int64" + }, + "ignore_large_untracked_files": { + "description": "Exclude untracked files larger than this many bytes from ghost snapshots.", + "type": "integer", + "format": "int64" + } + } + }, + "History": { + "description": "Settings that govern if and what will be written to `~/.codex/history.jsonl`.", + "type": "object", + "required": [ + "persistence" + ], + "properties": { + "max_bytes": { + "description": "If set, the maximum size of the history file in bytes. The oldest entries are dropped once the file exceeds this limit.", + "type": "integer", + "format": "uint", + "minimum": 0.0 + }, + "persistence": { + "description": "If true, history entries will not be written to disk.", + "allOf": [ + { + "$ref": "#/definitions/HistoryPersistence" + } + ] + } + } + }, + "HistoryPersistence": { + "oneOf": [ + { + "description": "Save all history entries to disk.", + "type": "string", + "enum": [ + "save-all" + ] + }, + { + "description": "Do not write history to disk.", + "type": "string", + "enum": [ + "none" + ] + } + ] + }, + "McpServerStdioSchema": { + "type": "object", + "required": [ + "command" + ], + "properties": { + "args": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "command": { + "type": "string" + }, + "cwd": { + "default": null, + "type": "string" + }, + "disabled_tools": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "enabled": { + "default": null, + "type": "boolean" + }, + "enabled_tools": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "env": { + "default": null, + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "env_vars": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "startup_timeout_ms": { + "default": null, + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "startup_timeout_sec": { + "default": null, + "type": "number", + "format": "double" + }, + "tool_timeout_sec": { + "default": null, + "type": "number", + "format": "double" + } + } + }, + "McpServerStreamableHttpSchema": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "bearer_token_env_var": { + "default": null, + "type": "string" + }, + "disabled_tools": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "enabled": { + "default": null, + "type": "boolean" + }, + "enabled_tools": { + "default": null, + "type": "array", + "items": { + "type": "string" + } + }, + "env_http_headers": { + "default": null, + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "http_headers": { + "default": null, + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "startup_timeout_ms": { + "default": null, + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "startup_timeout_sec": { + "default": null, + "type": "number", + "format": "double" + }, + "tool_timeout_sec": { + "default": null, + "type": "number", + "format": "double" + }, + "url": { + "type": "string" + } + } + }, + "ModelProviderInfo": { + "description": "Serializable representation of a provider definition.", + "type": "object", + "required": [ + "name" + ], + "properties": { + "base_url": { + "description": "Base URL for the provider's OpenAI-compatible API.", + "type": "string" + }, + "env_http_headers": { + "description": "Optional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and _environment variable_ whose value should be used. If the environment variable is not set, or the value is empty, the header will not be included in the request.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "env_key": { + "description": "Environment variable that stores the user's API key for this provider.", + "type": "string" + }, + "env_key_instructions": { + "description": "Optional instructions to help the user get a valid value for the variable and set it.", + "type": "string" + }, + "experimental_bearer_token": { + "description": "Value to use with `Authorization: Bearer ` header. Use of this config is discouraged in favor of `env_key` for security reasons, but this may be necessary when using this programmatically.", + "type": "string" + }, + "http_headers": { + "description": "Additional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and value.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "name": { + "description": "Friendly display name.", + "type": "string" + }, + "query_params": { + "description": "Optional query parameters to append to the base URL.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "request_max_retries": { + "description": "Maximum number of times to retry a failed HTTP request to this provider.", + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "requires_openai_auth": { + "description": "Does this provider require an OpenAI API Key or ChatGPT login token? If true, user is presented with login screen on first run, and login preference and token/key are stored in auth.json. If false (which is the default), login screen is skipped, and API key (if needed) comes from the \"env_key\" environment variable.", + "default": false, + "type": "boolean" + }, + "stream_idle_timeout_ms": { + "description": "Idle timeout (in milliseconds) to wait for activity on a streaming response before treating the connection as lost.", + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "stream_max_retries": { + "description": "Number of times to retry reconnecting a dropped streaming response before failing.", + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "wire_api": { + "description": "Which wire protocol this provider expects.", + "default": "chat", + "allOf": [ + { + "$ref": "#/definitions/WireApi" + } + ] + } + } + }, + "Notice": { + "description": "Settings for notices we display to users via the tui and app-server clients (primarily the Codex IDE extension). NOTE: these are different from notifications - notices are warnings, NUX screens, acknowledgements, etc.", + "type": "object", + "properties": { + "hide_full_access_warning": { + "description": "Tracks whether the user has acknowledged the full access warning prompt.", + "type": "boolean" + }, + "hide_gpt-5.1-codex-max_migration_prompt": { + "description": "Tracks whether the user has seen the gpt-5.1-codex-max migration prompt", + "type": "boolean" + }, + "hide_gpt5_1_migration_prompt": { + "description": "Tracks whether the user has seen the model migration prompt", + "type": "boolean" + }, + "hide_rate_limit_model_nudge": { + "description": "Tracks whether the user opted out of the rate limit model switch reminder.", + "type": "boolean" + }, + "hide_world_writable_warning": { + "description": "Tracks whether the user has acknowledged the Windows world-writable directories warning.", + "type": "boolean" + }, + "model_migrations": { + "description": "Tracks acknowledged model migrations as old->new model slug mappings.", + "default": {}, + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "Notifications": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "OAuthCredentialsStoreMode": { + "description": "Determine where Codex should store and read MCP credentials.", + "oneOf": [ + { + "description": "`Keyring` when available; otherwise, `File`. Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.", + "type": "string", + "enum": [ + "auto" + ] + }, + { + "description": "CODEX_HOME/.credentials.json This file will be readable to Codex and other applications running as the same user.", + "type": "string", + "enum": [ + "file" + ] + }, + { + "description": "Keyring when available, otherwise fail.", + "type": "string", + "enum": [ + "keyring" + ] + } + ] + }, + "OtelConfigToml": { + "description": "OTEL settings loaded from config.toml. Fields are optional so we can apply defaults.", + "type": "object", + "properties": { + "environment": { + "description": "Mark traces with environment (dev, staging, prod, test). Defaults to dev.", + "type": "string" + }, + "exporter": { + "description": "Optional log exporter", + "allOf": [ + { + "$ref": "#/definitions/OtelExporterKind" + } + ] + }, + "log_user_prompt": { + "description": "Log user prompt in traces", + "type": "boolean" + }, + "trace_exporter": { + "description": "Optional trace exporter", + "allOf": [ + { + "$ref": "#/definitions/OtelExporterKind" + } + ] + } + } + }, + "OtelExporterKind": { + "description": "Which OTEL exporter to use.", + "oneOf": [ + { + "type": "string", + "enum": [ + "none", + "statsig" + ] + }, + { + "type": "object", + "required": [ + "otlp-http" + ], + "properties": { + "otlp-http": { + "type": "object", + "required": [ + "endpoint", + "protocol" + ], + "properties": { + "endpoint": { + "type": "string" + }, + "headers": { + "default": {}, + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "protocol": { + "$ref": "#/definitions/OtelHttpProtocol" + }, + "tls": { + "default": null, + "allOf": [ + { + "$ref": "#/definitions/OtelTlsConfig" + } + ] + } + } + } + }, + "additionalProperties": false + }, + { + "type": "object", + "required": [ + "otlp-grpc" + ], + "properties": { + "otlp-grpc": { + "type": "object", + "required": [ + "endpoint" + ], + "properties": { + "endpoint": { + "type": "string" + }, + "headers": { + "default": {}, + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "tls": { + "default": null, + "allOf": [ + { + "$ref": "#/definitions/OtelTlsConfig" + } + ] + } + } + } + }, + "additionalProperties": false + } + ] + }, + "OtelHttpProtocol": { + "oneOf": [ + { + "description": "Binary payload", + "type": "string", + "enum": [ + "binary" + ] + }, + { + "description": "JSON payload", + "type": "string", + "enum": [ + "json" + ] + } + ] + }, + "OtelTlsConfig": { + "type": "object", + "properties": { + "ca-certificate": { + "$ref": "#/definitions/AbsolutePathBuf" + }, + "client-certificate": { + "$ref": "#/definitions/AbsolutePathBuf" + }, + "client-private-key": { + "$ref": "#/definitions/AbsolutePathBuf" + } + } + }, + "ProjectConfig": { + "type": "object", + "properties": { + "trust_level": { + "$ref": "#/definitions/TrustLevel" + } + } + }, + "ReasoningEffort": { + "description": "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning", + "type": "string", + "enum": [ + "none", + "minimal", + "low", + "medium", + "high", + "xhigh" + ] + }, + "ReasoningSummary": { + "description": "A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries", + "oneOf": [ + { + "type": "string", + "enum": [ + "auto", + "concise", + "detailed" + ] + }, + { + "description": "Option to disable reasoning summaries.", + "type": "string", + "enum": [ + "none" + ] + } + ] + }, + "SandboxMode": { + "type": "string", + "enum": [ + "read-only", + "workspace-write", + "danger-full-access" + ] + }, + "SandboxWorkspaceWrite": { + "type": "object", + "properties": { + "exclude_slash_tmp": { + "default": false, + "type": "boolean" + }, + "exclude_tmpdir_env_var": { + "default": false, + "type": "boolean" + }, + "network_access": { + "default": false, + "type": "boolean" + }, + "writable_roots": { + "default": [], + "type": "array", + "items": { + "$ref": "#/definitions/AbsolutePathBuf" + } + } + } + }, + "ScrollInputMode": { + "description": "How TUI2 should interpret mouse scroll events.\n\nTerminals generally encode both mouse wheels and trackpads as the same \"scroll up/down\" mouse button events, without a magnitude. This setting controls whether Codex uses a heuristic to infer wheel vs trackpad per stream, or forces a specific behavior.", + "oneOf": [ + { + "description": "Infer wheel vs trackpad behavior per scroll stream.", + "type": "string", + "enum": [ + "auto" + ] + }, + { + "description": "Always treat scroll events as mouse-wheel input (fixed lines per tick).", + "type": "string", + "enum": [ + "wheel" + ] + }, + { + "description": "Always treat scroll events as trackpad input (fractional accumulation).", + "type": "string", + "enum": [ + "trackpad" + ] + } + ] + }, + "ShellEnvironmentPolicyInherit": { + "oneOf": [ + { + "description": "\"Core\" environment variables for the platform. On UNIX, this would include HOME, LOGNAME, PATH, SHELL, and USER, among others.", + "type": "string", + "enum": [ + "core" + ] + }, + { + "description": "Inherits the full environment from the parent process.", + "type": "string", + "enum": [ + "all" + ] + }, + { + "description": "Do not inherit any environment variables from the parent process.", + "type": "string", + "enum": [ + "none" + ] + } + ] + }, + "ShellEnvironmentPolicyToml": { + "description": "Policy for building the `env` when spawning a process via either the `shell` or `local_shell` tool.", + "type": "object", + "properties": { + "exclude": { + "description": "List of regular expressions.", + "type": "array", + "items": { + "type": "string" + } + }, + "experimental_use_profile": { + "type": "boolean" + }, + "ignore_default_excludes": { + "type": "boolean" + }, + "include_only": { + "description": "List of regular expressions.", + "type": "array", + "items": { + "type": "string" + } + }, + "inherit": { + "$ref": "#/definitions/ShellEnvironmentPolicyInherit" + }, + "set": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "ToolsToml": { + "type": "object", + "properties": { + "view_image": { + "description": "Enable the `view_image` tool that lets the agent attach local images.", + "default": null, + "type": "boolean" + }, + "web_search": { + "default": null, + "type": "boolean" + } + } + }, + "TrustLevel": { + "description": "Represents the trust level for a project directory. This determines the approval policy and sandbox mode applied.", + "type": "string", + "enum": [ + "trusted", + "untrusted" + ] + }, + "Tui": { + "description": "Collection of settings that are specific to the TUI.", + "type": "object", + "properties": { + "animations": { + "description": "Enable animations (welcome screen, shimmer effects, spinners). Defaults to `true`.", + "default": true, + "type": "boolean" + }, + "notifications": { + "description": "Enable desktop notifications from the TUI when the terminal is unfocused. Defaults to `true`.", + "default": true, + "allOf": [ + { + "$ref": "#/definitions/Notifications" + } + ] + }, + "scroll_events_per_tick": { + "description": "Override the *wheel* event density used to normalize TUI2 scrolling.\n\nTerminals generally deliver both mouse wheels and trackpads as discrete `scroll up/down` mouse events with direction but no magnitude. Unfortunately, the *number* of raw events per physical wheel notch varies by terminal (commonly 1, 3, or 9+). TUI2 uses this value to normalize that raw event density into consistent \"wheel tick\" behavior.\n\nWheel math (conceptually):\n\n- A single event contributes `1 / scroll_events_per_tick` tick-equivalents. - Wheel-like streams then scale that by `scroll_wheel_lines` so one physical notch scrolls a fixed number of lines.\n\nTrackpad math is intentionally *not* fully tied to this value: in trackpad-like mode, TUI2 uses `min(scroll_events_per_tick, 3)` as the divisor so terminals with dense wheel ticks (e.g. 9 events per notch) do not make trackpads feel artificially slow.\n\nDefaults are derived per terminal from [`crate::terminal::TerminalInfo`] when TUI2 starts. See `codex-rs/tui2/docs/scroll_input_model.md` for the probe data and rationale.", + "type": "integer", + "format": "uint16", + "minimum": 0.0 + }, + "scroll_invert": { + "description": "Invert mouse scroll direction in TUI2.\n\nThis flips the scroll sign after terminal detection. It is applied consistently to both wheel and trackpad input.", + "default": false, + "type": "boolean" + }, + "scroll_mode": { + "description": "Select how TUI2 interprets mouse scroll input.\n\n- `auto` (default): infer wheel vs trackpad per scroll stream. - `wheel`: always use wheel behavior (fixed lines per wheel notch). - `trackpad`: always use trackpad behavior (fractional accumulation; wheel may feel slow).", + "default": "auto", + "allOf": [ + { + "$ref": "#/definitions/ScrollInputMode" + } + ] + }, + "scroll_trackpad_accel_events": { + "description": "Trackpad acceleration: approximate number of events required to gain +1x speed in TUI2.\n\nThis keeps small swipes precise while allowing large/faster swipes to cover more content. Defaults are chosen to address terminals where trackpad event density is comparatively low.\n\nConcretely, TUI2 computes an acceleration multiplier for trackpad-like streams:\n\n- `multiplier = clamp(1 + abs(events) / scroll_trackpad_accel_events, 1..scroll_trackpad_accel_max)`\n\nThe multiplier is applied to the stream’s computed line delta (including any carried fractional remainder).", + "type": "integer", + "format": "uint16", + "minimum": 0.0 + }, + "scroll_trackpad_accel_max": { + "description": "Trackpad acceleration: maximum multiplier applied to trackpad-like streams.\n\nSet to 1 to effectively disable trackpad acceleration.\n\nSee [`Tui::scroll_trackpad_accel_events`] for the exact multiplier formula.", + "type": "integer", + "format": "uint16", + "minimum": 0.0 + }, + "scroll_trackpad_lines": { + "description": "Override baseline trackpad scroll sensitivity in TUI2.\n\nTrackpads do not have discrete notches, but terminals still emit discrete `scroll up/down` events. In trackpad-like mode, TUI2 accumulates fractional scroll and only applies whole lines to the viewport.\n\nTrackpad per-event contribution is:\n\n- `scroll_trackpad_lines / min(scroll_events_per_tick, 3)`\n\n(plus optional bounded acceleration; see `scroll_trackpad_accel_*`). The `min(..., 3)` divisor is deliberate: `scroll_events_per_tick` is calibrated from *wheel* behavior and can be much larger than trackpad event density, which would otherwise make trackpads feel too slow in dense-wheel terminals.\n\nDefaults to 1, meaning one tick-equivalent maps to one transcript line.", + "type": "integer", + "format": "uint16", + "minimum": 0.0 + }, + "scroll_wheel_like_max_duration_ms": { + "description": "Auto-mode fallback: maximum duration (ms) that a very small stream is still treated as wheel-like.\n\nThis is only used when `scroll_events_per_tick` is effectively 1 (one event per wheel notch). In that case, we cannot observe a \"tick completion time\", so TUI2 treats a short-lived, small stream (<= 2 events) as wheel-like to preserve classic wheel behavior.", + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "scroll_wheel_lines": { + "description": "Override how many transcript lines one physical *wheel notch* should scroll in TUI2.\n\nThis is the \"classic feel\" knob. Defaults to 3.\n\nWheel-like per-event contribution is `scroll_wheel_lines / scroll_events_per_tick`. For example, in a terminal that emits 9 events per notch, the default `3 / 9` yields 1/3 of a line per event and totals 3 lines once the full notch burst arrives.\n\nSee `codex-rs/tui2/docs/scroll_input_model.md` for details on the stream model and the wheel/trackpad heuristic.", + "type": "integer", + "format": "uint16", + "minimum": 0.0 + }, + "scroll_wheel_tick_detect_max_ms": { + "description": "Auto-mode threshold: maximum time (ms) for the first tick-worth of events to arrive.\n\nIn `scroll_mode = \"auto\"`, TUI2 starts a stream as trackpad-like (to avoid overshoot) and promotes it to wheel-like if `scroll_events_per_tick` events arrive \"quickly enough\". This threshold controls what \"quickly enough\" means.\n\nMost users should leave this unset; it is primarily for terminals that emit wheel ticks batched over longer time spans.", + "type": "integer", + "format": "uint64", + "minimum": 0.0 + }, + "show_tooltips": { + "description": "Show startup tooltips in the TUI welcome screen. Defaults to `true`.", + "default": true, + "type": "boolean" + } + } + }, + "UriBasedFileOpener": { + "oneOf": [ + { + "type": "string", + "enum": [ + "vscode", + "vscode-insiders", + "windsurf", + "cursor" + ] + }, + { + "description": "Option to disable the URI-based file opener.", + "type": "string", + "enum": [ + "none" + ] + } + ] + }, + "Verbosity": { + "description": "Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.", + "type": "string", + "enum": [ + "low", + "medium", + "high" + ] + }, + "WireApi": { + "description": "Wire protocol that the provider speaks. Most third-party services only implement the classic OpenAI Chat Completions JSON schema, whereas OpenAI itself (and a handful of others) additionally expose the more modern *Responses* API. The two protocols use different request/response shapes and *cannot* be auto-detected at runtime, therefore each provider entry must declare which one it expects.", + "oneOf": [ + { + "description": "The Responses API exposed by OpenAI at `/v1/responses`.", + "type": "string", + "enum": [ + "responses" + ] + }, + { + "description": "Regular Chat Completions compatible with `/v1/chat/completions`.", + "type": "string", + "enum": [ + "chat" + ] + } + ] + } + } +} \ No newline at end of file