{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"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"
},
"AgentRoleToml": {
"additionalProperties": false,
"properties": {
"config_file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Path to a role-specific config layer. Relative paths are resolved relative to the `config.toml` that defines them."
},
"description": {
"description": "Human-facing role documentation used in spawn tool guidance. Required unless supplied by the referenced agent role file.",
"type": "string"
},
"nickname_candidates": {
"description": "Candidate nicknames for agents spawned with this role.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"AgentsToml": {
"additionalProperties": {
"$ref": "#/definitions/AgentRoleToml"
},
"properties": {
"default_subagent_model": {
"description": "Default model for spawned subagents when the spawn call does not select one.",
"type": "string"
},
"default_subagent_reasoning_effort": {
"allOf": [
{
"$ref": "#/definitions/ReasoningEffort"
}
],
"description": "Default reasoning effort for spawned subagents when the spawn call does not select one."
},
"enabled": {
"description": "Whether multi-agent tools are enabled. Defaults to true. An enabled `features.multi_agent_v2` setting takes precedence.",
"type": "boolean"
},
"interrupt_message": {
"description": "Whether to record a model-visible message when an agent turn is interrupted. Defaults to true.",
"type": "boolean"
},
"max_concurrent_threads_per_session": {
"description": "Maximum number of spawned agent threads that can be open concurrently per session. When unset, the selected multi-agent backend uses its default.",
"format": "uint",
"minimum": 1.0,
"type": "integer"
},
"max_depth": {
"description": "Maximum nesting depth for V1 agent threads. Ignored by V2.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"AltScreenMode": {
"description": "Controls whether the TUI uses the terminal's alternate screen buffer.\n\n- `auto` (default): Use alternate screen mode. - `always`: Always use alternate screen mode. - `never`: Never use alternate screen mode. Runs in inline mode, preserving scrollback.\n\nThe CLI flag `--no-alt-screen` can override this setting at runtime.",
"oneOf": [
{
"description": "Use alternate screen mode.",
"enum": [
"auto"
],
"type": "string"
},
{
"description": "Always use alternate screen mode.",
"enum": [
"always"
],
"type": "string"
},
{
"description": "Never use alternate screen (inline mode only).",
"enum": [
"never"
],
"type": "string"
}
]
},
"AnalyticsConfigToml": {
"additionalProperties": false,
"description": "Analytics settings loaded from config.toml. Fields are optional so we can apply defaults.",
"properties": {
"enabled": {
"description": "When `false`, disables analytics across Codex product surfaces in this profile.",
"type": "boolean"
}
},
"type": "object"
},
"AppConfig": {
"additionalProperties": false,
"description": "Config values for a single app/connector.",
"properties": {
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Reviewer for approval prompts from this app, overriding the thread default."
},
"default_tools_approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for tools in this app unless a tool override exists."
},
"default_tools_enabled": {
"description": "Whether tools are enabled by default for this app.",
"type": "boolean"
},
"destructive_enabled": {
"description": "Whether tools with `destructive_hint = true` are allowed for this app.",
"type": "boolean"
},
"enabled": {
"default": true,
"description": "When `false`, Codex does not surface this app.",
"type": "boolean"
},
"open_world_enabled": {
"description": "Whether tools with `open_world_hint = true` are allowed for this app.",
"type": "boolean"
},
"tools": {
"allOf": [
{
"$ref": "#/definitions/AppToolsConfig"
}
],
"description": "Per-tool settings for this app."
}
},
"type": "object"
},
"AppToolApproval": {
"enum": [
"auto",
"prompt",
"writes",
"approve"
],
"type": "string"
},
"AppToolConfig": {
"additionalProperties": false,
"description": "Per-tool settings for a single app tool.",
"properties": {
"approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for this tool."
},
"enabled": {
"description": "Whether this tool is enabled. `Some(true)` explicitly allows this tool.",
"type": "boolean"
}
},
"type": "object"
},
"AppToolsConfig": {
"additionalProperties": {
"$ref": "#/definitions/AppToolConfig"
},
"description": "Tool settings for a single app.",
"type": "object"
},
"ApprovalsReviewer": {
"description": "Configures who approval requests are routed to for review. Examples include sandbox escapes, blocked network access, MCP approval prompts, and ARC escalations. Defaults to `user`. `auto_review` uses a carefully prompted subagent to gather relevant context and apply a risk-based decision framework before approving or denying the request. The legacy value `guardian_subagent` is accepted for compatibility.",
"enum": [
"user",
"auto_review",
"guardian_subagent"
],
"type": "string"
},
"AppsConfigToml": {
"additionalProperties": {
"$ref": "#/definitions/AppConfig"
},
"description": "App/connector settings loaded from `config.toml`.",
"properties": {
"_default": {
"allOf": [
{
"$ref": "#/definitions/AppsDefaultConfig"
}
],
"description": "Default settings for all apps."
}
},
"type": "object"
},
"AppsDefaultConfig": {
"additionalProperties": false,
"description": "Default settings that apply to all apps.",
"properties": {
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Reviewer for approval prompts unless overridden by per-app settings."
},
"default_tools_approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for tools unless overridden by per-app or per-tool settings."
},
"destructive_enabled": {
"description": "Whether tools with `destructive_hint = true` are allowed by default.",
"type": "boolean"
},
"enabled": {
"default": true,
"description": "When `false`, apps are disabled unless overridden by per-app settings.",
"type": "boolean"
},
"open_world_enabled": {
"description": "Whether tools with `open_world_hint = true` are allowed by default.",
"type": "boolean"
}
},
"type": "object"
},
"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.",
"enum": [
"untrusted"
],
"type": "string"
},
{
"description": "The model decides when to ask the user for approval.",
"enum": [
"on-request"
],
"type": "string"
},
{
"additionalProperties": false,
"description": "Fine-grained controls for individual approval flows.\n\nWhen a field is `true`, commands in that category are allowed. When it is `false`, those requests are automatically rejected instead of shown to the user.",
"properties": {
"granular": {
"$ref": "#/definitions/GranularApprovalConfig"
}
},
"required": [
"granular"
],
"type": "object"
},
{
"description": "Never ask the user to approve commands. Failures are immediately returned to the model, and never escalated to the user for approval.",
"enum": [
"never"
],
"type": "string"
}
]
},
"AuthCredentialsStoreMode": {
"description": "Determine where Codex should store CLI auth credentials.",
"oneOf": [
{
"description": "Persist credentials in CODEX_HOME/auth.json.",
"enum": [
"file"
],
"type": "string"
},
{
"description": "Persist credentials in the keyring. Fail if unavailable.",
"enum": [
"keyring"
],
"type": "string"
},
{
"description": "Use keyring when available; otherwise, fall back to a file in CODEX_HOME.",
"enum": [
"auto"
],
"type": "string"
},
{
"description": "Store credentials in memory only for the current process.",
"enum": [
"ephemeral"
],
"type": "string"
}
]
},
"AutoCompactTokenLimitScope": {
"description": "Selects which part of the active context is charged against `model_auto_compact_token_limit`.",
"oneOf": [
{
"description": "Count the full active context against the limit.",
"enum": [
"total"
],
"type": "string"
},
{
"description": "Count sampled output and later growth after the carried window prefix.",
"enum": [
"body_after_prefix"
],
"type": "string"
}
]
},
"AutoReviewToml": {
"properties": {
"policy": {
"description": "Additional policy instructions inserted into the guardian prompt.",
"type": "string"
}
},
"type": "object"
},
"BundledSkillsConfig": {
"additionalProperties": false,
"properties": {
"enabled": {
"default": true,
"type": "boolean"
}
},
"type": "object"
},
"CodeModeConfigToml": {
"additionalProperties": false,
"properties": {
"direct_only_tool_namespaces": {
"description": "Exact tool namespaces to expose only as direct model tools. These tools bypass deferral, remain top-level in code-mode-only sessions, and are omitted from the nested code-mode tool surface.",
"items": {
"type": "string"
},
"type": "array"
},
"enabled": {
"type": "boolean"
},
"excluded_tool_namespaces": {
"description": "Exact tool namespaces to omit from the code-mode nested tool surface.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"ConfigProfile": {
"additionalProperties": false,
"description": "Collection of common configuration options that a user can define as a unit in `config.toml`.",
"properties": {
"analytics": {
"$ref": "#/definitions/AnalyticsConfigToml"
},
"approval_policy": {
"$ref": "#/definitions/AskForApproval"
},
"approvals_reviewer": {
"$ref": "#/definitions/ApprovalsReviewer"
},
"chatgpt_base_url": {
"type": "string"
},
"experimental_compact_prompt_file": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"features": {
"additionalProperties": false,
"default": null,
"description": "Optional feature toggles scoped to this profile.",
"properties": {
"apply_patch_freeform": {
"type": "boolean"
},
"apply_patch_streaming_events": {
"type": "boolean"
},
"apps": {
"type": "boolean"
},
"apps_mcp_path_override": {
"anyOf": [
{
"type": "boolean"
},
{
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"path": {
"type": "string"
}
},
"type": "object"
}
]
},
"auth_elicitation": {
"type": "boolean"
},
"browser_use": {
"type": "boolean"
},
"browser_use_external": {
"type": "boolean"
},
"browser_use_full_cdp_access": {
"type": "boolean"
},
"chronicle": {
"type": "boolean"
},
"code_mode": {
"$ref": "#/definitions/FeatureToml_for_CodeModeConfigToml"
},
"code_mode_buffered_exec": {
"type": "boolean"
},
"code_mode_host": {
"type": "boolean"
},
"code_mode_only": {
"type": "boolean"
},
"codex_git_commit": {
"type": "boolean"
},
"codex_hooks": {
"type": "boolean"
},
"collab": {
"type": "boolean"
},
"collaboration_modes": {
"type": "boolean"
},
"computer_use": {
"type": "boolean"
},
"concurrent_reasoning_summaries": {
"type": "boolean"
},
"connectors": {
"type": "boolean"
},
"current_time_reminder": {
"$ref": "#/definitions/FeatureToml_for_CurrentTimeReminderConfigToml"
},
"default_mode_request_user_input": {
"type": "boolean"
},
"deferred_executor": {
"type": "boolean"
},
"elevated_windows_sandbox": {
"type": "boolean"
},
"enable_experimental_windows_sandbox": {
"type": "boolean"
},
"enable_fanout": {
"type": "boolean"
},
"enable_mcp_apps": {
"type": "boolean"
},
"enable_request_compression": {
"type": "boolean"
},
"exec_permission_approvals": {
"type": "boolean"
},
"executor_capability_discovery": {
"type": "boolean"
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"experimental_windows_sandbox": {
"type": "boolean"
},
"external_agent_memory_import": {
"type": "boolean"
},
"external_migration": {
"type": "boolean"
},
"fast_mode": {
"type": "boolean"
},
"goals": {
"type": "boolean"
},
"guardian_approval": {
"type": "boolean"
},
"hooks": {
"type": "boolean"
},
"image_detail_original": {
"type": "boolean"
},
"image_generation": {
"type": "boolean"
},
"imagegenext": {
"type": "boolean"
},
"in_app_browser": {
"type": "boolean"
},
"item_ids": {
"type": "boolean"
},
"js_repl": {
"type": "boolean"
},
"js_repl_tools_only": {
"type": "boolean"
},
"local_thread_store_compression": {
"type": "boolean"
},
"memories": {
"type": "boolean"
},
"memory_tool": {
"type": "boolean"
},
"mentions_v2": {
"type": "boolean"
},
"multi_agent": {
"type": "boolean"
},
"multi_agent_mode": {
"type": "boolean"
},
"multi_agent_v2": {
"$ref": "#/definitions/FeatureToml_for_MultiAgentV2ConfigToml"
},
"network_proxy": {
"$ref": "#/definitions/FeatureToml_for_NetworkProxyConfigToml"
},
"non_prefixed_mcp_tool_names": {
"type": "boolean"
},
"personality": {
"type": "boolean"
},
"plugin_hooks": {
"type": "boolean"
},
"plugin_sharing": {
"type": "boolean"
},
"plugins": {
"type": "boolean"
},
"prevent_idle_sleep": {
"type": "boolean"
},
"realtime_conversation": {
"type": "boolean"
},
"remote_compaction_v2": {
"type": "boolean"
},
"remote_control": {
"type": "boolean"
},
"remote_models": {
"type": "boolean"
},
"remote_plugin": {
"type": "boolean"
},
"request_permissions": {
"type": "boolean"
},
"request_permissions_tool": {
"type": "boolean"
},
"request_rule": {
"type": "boolean"
},
"resize_all_images": {
"type": "boolean"
},
"respect_system_proxy": {
"type": "boolean"
},
"responses_websockets": {
"type": "boolean"
},
"responses_websockets_v2": {
"type": "boolean"
},
"rollout_budget": {
"$ref": "#/definitions/FeatureToml_for_RolloutBudgetConfigToml"
},
"runtime_metrics": {
"type": "boolean"
},
"search_tool": {
"type": "boolean"
},
"secret_auth_storage": {
"type": "boolean"
},
"shell_snapshot": {
"type": "boolean"
},
"shell_tool": {
"type": "boolean"
},
"shell_zsh_fork": {
"type": "boolean"
},
"skill_env_var_dependency_prompt": {
"type": "boolean"
},
"skill_mcp_dependency_install": {
"type": "boolean"
},
"skill_search": {
"type": "boolean"
},
"sqlite": {
"type": "boolean"
},
"standalone_web_search": {
"type": "boolean"
},
"steer": {
"type": "boolean"
},
"telepathy": {
"type": "boolean"
},
"terminal_resize_reflow": {
"type": "boolean"
},
"terminal_visualization_instructions": {
"type": "boolean"
},
"token_budget": {
"$ref": "#/definitions/FeatureToml_for_TokenBudgetConfigToml"
},
"tool_call_mcp_elicitation": {
"type": "boolean"
},
"tool_search": {
"type": "boolean"
},
"tool_search_always_defer_mcp_tools": {
"type": "boolean"
},
"tool_suggest": {
"type": "boolean"
},
"tui_app_server": {
"type": "boolean"
},
"unavailable_dummy_tools": {
"type": "boolean"
},
"undo": {
"type": "boolean"
},
"unified_exec": {
"type": "boolean"
},
"unified_exec_zsh_fork": {
"type": "boolean"
},
"use_agent_identity": {
"type": "boolean"
},
"use_legacy_landlock": {
"type": "boolean"
},
"use_linux_sandbox_bwrap": {
"type": "boolean"
},
"web_search": {
"type": "boolean"
},
"web_search_cached": {
"type": "boolean"
},
"web_search_request": {
"type": "boolean"
},
"workspace_dependencies": {
"type": "boolean"
},
"workspace_owner_usage_nudge": {
"type": "boolean"
}
},
"type": "object"
},
"include_apps_instructions": {
"type": "boolean"
},
"include_collaboration_mode_instructions": {
"type": "boolean"
},
"include_environment_context": {
"type": "boolean"
},
"include_permissions_instructions": {
"type": "boolean"
},
"model": {
"type": "string"
},
"model_catalog_json": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a JSON model catalog (applied on startup only)."
},
"model_instructions_file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a file containing model instructions."
},
"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"
},
"personality": {
"$ref": "#/definitions/Personality"
},
"plan_mode_reasoning_effort": {
"$ref": "#/definitions/ReasoningEffort"
},
"sandbox_mode": {
"$ref": "#/definitions/SandboxMode"
},
"service_tier": {
"description": "Optional explicit service tier request id for new turns (for example `default`, `priority`, or `flex`; legacy `fast` also works).",
"type": "string"
},
"tools": {
"$ref": "#/definitions/ToolsToml"
},
"tui": {
"allOf": [
{
"$ref": "#/definitions/ProfileTui"
}
],
"default": null,
"description": "TUI settings scoped to this profile."
},
"web_search": {
"$ref": "#/definitions/WebSearchMode"
},
"windows": {
"allOf": [
{
"$ref": "#/definitions/WindowsToml"
}
],
"default": null
}
},
"type": "object"
},
"CurrentTimeReminderConfigToml": {
"additionalProperties": false,
"properties": {
"clock_source": {
"$ref": "#/definitions/CurrentTimeSource"
},
"delivery_mode": {
"$ref": "#/definitions/CurrentTimeReminderDeliveryMode"
},
"enabled": {
"type": "boolean"
},
"reminder_interval_seconds": {
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"sleep_tool": {
"description": "Expose the input-interruptible `clock.sleep` tool.",
"type": "boolean"
}
},
"type": "object"
},
"CurrentTimeReminderDeliveryMode": {
"description": "Which inference boundaries may receive current-time reminders.",
"oneOf": [
{
"description": "Allow a reminder before any inference request once the interval is due.",
"enum": [
"any_inference"
],
"type": "string"
},
{
"description": "Allow reminders after user input or tool output; new context windows still force one.",
"enum": [
"after_user_or_tool_output"
],
"type": "string"
}
]
},
"CurrentTimeSource": {
"enum": [
"system",
"external"
],
"type": "string"
},
"DebugConfigLockToml": {
"additionalProperties": false,
"properties": {
"allow_codex_version_mismatch": {
"description": "Allow replaying a lock generated by a different Codex version.",
"type": "boolean"
},
"export_dir": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Directory where Codex writes effective session config lock files."
},
"load_path": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Lockfile to replay as the authoritative effective config."
},
"save_fields_resolved_from_model_catalog": {
"description": "Save fields resolved from the model catalog/session configuration.",
"type": "boolean"
}
},
"type": "object"
},
"DebugToml": {
"additionalProperties": false,
"properties": {
"config_lockfile": {
"$ref": "#/definitions/DebugConfigLockToml"
}
},
"type": "object"
},
"ExperimentalRequestUserInput": {
"additionalProperties": false,
"properties": {
"enabled": {
"default": true,
"type": "boolean"
}
},
"type": "object"
},
"ExternalConfigMigrationPrompts": {
"additionalProperties": false,
"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.",
"properties": {
"home": {
"description": "Tracks whether home-level external config migration prompts are hidden.",
"type": "boolean"
},
"home_last_prompted_at": {
"description": "Tracks the last time the home-level external config migration prompt was shown.",
"format": "int64",
"type": "integer"
},
"project_last_prompted_at": {
"additionalProperties": {
"format": "int64",
"type": "integer"
},
"default": {},
"description": "Tracks the last time a project-level external config migration prompt was shown.",
"type": "object"
},
"projects": {
"additionalProperties": {
"type": "boolean"
},
"default": {},
"description": "Tracks which project paths have opted out of external config migration prompts.",
"type": "object"
}
},
"type": "object"
},
"FeatureToml_for_CodeModeConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/CodeModeConfigToml"
}
]
},
"FeatureToml_for_CurrentTimeReminderConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/CurrentTimeReminderConfigToml"
}
]
},
"FeatureToml_for_MultiAgentV2ConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/MultiAgentV2ConfigToml"
}
]
},
"FeatureToml_for_NetworkProxyConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/NetworkProxyConfigToml"
}
]
},
"FeatureToml_for_RolloutBudgetConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/RolloutBudgetConfigToml"
}
]
},
"FeatureToml_for_TokenBudgetConfigToml": {
"anyOf": [
{
"type": "boolean"
},
{
"$ref": "#/definitions/TokenBudgetConfigToml"
}
]
},
"FeedbackConfigToml": {
"additionalProperties": false,
"properties": {
"enabled": {
"description": "When `false`, disables the feedback flow across Codex product surfaces.",
"type": "boolean"
}
},
"type": "object"
},
"FileSystemAccessMode": {
"description": "Access mode for a filesystem entry.\n\nWhen two equally specific entries target the same path, we compare these by conflict precedence rather than by capability breadth: `deny` beats `write`, and `write` beats `read`.",
"oneOf": [
{
"enum": [
"read",
"write"
],
"type": "string"
},
{
"description": "`none` is a legacy input alias retained temporarily for compatibility.",
"enum": [
"deny"
],
"type": "string"
}
]
},
"FilesystemPermissionToml": {
"anyOf": [
{
"$ref": "#/definitions/FileSystemAccessMode"
},
{
"additionalProperties": {
"$ref": "#/definitions/FileSystemAccessMode"
},
"type": "object"
}
]
},
"FilesystemPermissionsToml": {
"properties": {
"glob_scan_max_depth": {
"description": "Optional maximum depth for expanding unreadable glob patterns on platforms that snapshot glob matches before sandbox startup.",
"format": "uint",
"minimum": 1.0,
"type": "integer"
}
},
"type": "object"
},
"ForcedChatgptWorkspaceIds": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "Backward-compatible shape for ChatGPT workspace login restrictions in config.toml."
},
"ForcedLoginMethod": {
"enum": [
"chatgpt",
"api"
],
"type": "string"
},
"GhostSnapshotToml": {
"additionalProperties": false,
"properties": {
"disable_warnings": {
"description": "Legacy no-op setting retained for compatibility.",
"type": "boolean"
},
"ignore_large_untracked_dirs": {
"description": "Legacy no-op setting retained for compatibility.",
"format": "int64",
"type": "integer"
},
"ignore_large_untracked_files": {
"description": "Legacy no-op setting retained for compatibility.",
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"GranularApprovalConfig": {
"properties": {
"mcp_elicitations": {
"description": "Whether to allow MCP elicitation prompts.",
"type": "boolean"
},
"request_permissions": {
"default": false,
"description": "Whether to allow prompts triggered by the `request_permissions` tool.",
"type": "boolean"
},
"rules": {
"description": "Whether to allow prompts triggered by execpolicy `prompt` rules.",
"type": "boolean"
},
"sandbox_approval": {
"description": "Whether to allow shell command approval requests, including inline `with_additional_permissions` and `require_escalated` requests.",
"type": "boolean"
},
"skill_approval": {
"default": false,
"description": "Whether to allow approval prompts triggered by skill script execution.",
"type": "boolean"
}
},
"required": [
"mcp_elicitations",
"rules",
"sandbox_approval"
],
"type": "object"
},
"History": {
"additionalProperties": false,
"description": "Settings that govern if and what will be written to `~/.codex/history.jsonl`.",
"properties": {
"max_bytes": {
"default": null,
"description": "If set, the maximum size of the history file in bytes. The oldest entries are dropped once the file exceeds this limit.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"persistence": {
"allOf": [
{
"$ref": "#/definitions/HistoryPersistence"
}
],
"default": "save-all",
"description": "If true, history entries will not be written to disk."
}
},
"type": "object"
},
"HistoryPersistence": {
"oneOf": [
{
"description": "Save all history entries to disk.",
"enum": [
"save-all"
],
"type": "string"
},
{
"description": "Do not write history to disk.",
"enum": [
"none"
],
"type": "string"
}
]
},
"HookHandlerConfig": {
"oneOf": [
{
"properties": {
"additionalContextLimit": {
"description": "Approximate token threshold for spilling this hook's `additionalContext` to disk. Unset uses 2,500 tokens; `0` disables spilling for this hook. The threshold is evaluated against the original context; a spilled preview also includes recovery metadata.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"async": {
"default": false,
"type": "boolean"
},
"command": {
"type": "string"
},
"commandWindows": {
"default": null,
"type": "string"
},
"statusMessage": {
"default": null,
"type": "string"
},
"timeout": {
"default": null,
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"type": {
"enum": [
"command"
],
"type": "string"
}
},
"required": [
"command",
"type"
],
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"prompt"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"agent"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
}
]
},
"HookStateToml": {
"properties": {
"enabled": {
"type": "boolean"
},
"trusted_hash": {
"type": "string"
}
},
"type": "object"
},
"HooksToml": {
"properties": {
"PermissionRequest": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PostCompact": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PostToolUse": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PreCompact": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"PreToolUse": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SessionEnd": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SessionStart": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"Stop": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SubagentStart": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"SubagentStop": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"UserPromptSubmit": {
"default": [],
"items": {
"$ref": "#/definitions/MatcherGroup"
},
"type": "array"
},
"state": {
"additionalProperties": {
"$ref": "#/definitions/HookStateToml"
},
"type": "object"
}
},
"type": "object"
},
"KeybindingsSpec": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "One action binding value in config.\n\nThis accepts either:\n\n1. A single key spec string (`\"ctrl-a\"`). 2. A list of key spec strings (`[\"ctrl-a\", \"alt-a\"]`).\n\nAn empty list explicitly unbinds the action in that scope. Because an explicit empty list is still a configured value, runtime resolution must not fall through to global or built-in defaults for that action."
},
"LegacyAppPathString": {
"type": "string"
},
"MarketplaceConfig": {
"additionalProperties": false,
"properties": {
"last_revision": {
"default": null,
"description": "Git revision Codex last successfully activated for this marketplace.",
"type": "string"
},
"last_updated": {
"default": null,
"description": "Last time Codex successfully added or refreshed this marketplace.",
"type": "string"
},
"ref": {
"default": null,
"description": "Git ref to check out when `source_type` is `git`.",
"type": "string"
},
"source": {
"default": null,
"description": "Source location used when the marketplace was added.",
"type": "string"
},
"source_type": {
"allOf": [
{
"$ref": "#/definitions/MarketplaceSourceType"
}
],
"default": null,
"description": "Source kind used to install this marketplace."
},
"sparse_paths": {
"default": null,
"description": "Sparse checkout paths used when `source_type` is `git`.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"MarketplaceSourceType": {
"enum": [
"git",
"local"
],
"type": "string"
},
"MatcherGroup": {
"properties": {
"hooks": {
"default": [],
"items": {
"$ref": "#/definitions/HookHandlerConfig"
},
"type": "array"
},
"matcher": {
"default": null,
"type": "string"
}
},
"type": "object"
},
"McpServerAuth": {
"description": "Authentication flow Codex attempts after resolving an HTTP MCP server's configured bearer token and authorization headers, which always take precedence. ChatGPT authentication falls back to stored OAuth credentials when its session provider is unavailable; both modes ultimately fall back to an unauthenticated connection.",
"oneOf": [
{
"description": "Use stored MCP OAuth credentials when available. Starting an OAuth login is a separate operation.",
"enum": [
"oauth"
],
"type": "string"
},
{
"description": "Use the current ChatGPT session for servers on the trusted first-party ChatGPT origin. If no ChatGPT session provider is available, startup can still fall back to stored OAuth credentials.",
"enum": [
"chatgpt"
],
"type": "string"
}
]
},
"McpServerEnvVar": {
"anyOf": [
{
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"source": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
]
},
"McpServerOAuthConfig": {
"additionalProperties": false,
"description": "OAuth client settings used when Codex launches an MCP OAuth flow.",
"properties": {
"client_id": {
"description": "Explicit OAuth client identifier to present during authorization and token exchange.",
"type": "string"
}
},
"type": "object"
},
"McpServerToolConfig": {
"additionalProperties": false,
"description": "Per-tool approval settings for a single MCP server tool.",
"properties": {
"approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for this tool."
}
},
"type": "object"
},
"MemoriesToml": {
"additionalProperties": false,
"description": "Memories settings loaded from config.toml.",
"properties": {
"consolidation_model": {
"description": "Model used for memory consolidation.",
"type": "string"
},
"dedicated_tools": {
"description": "When `true`, expose dedicated memory tools through the extension tool surface.",
"type": "boolean"
},
"disable_on_external_context": {
"description": "When `true`, external context sources mark the thread `memory_mode` as `\"polluted\"`.",
"type": "boolean"
},
"extract_model": {
"description": "Model used for thread summarisation.",
"type": "string"
},
"generate_memories": {
"description": "When `false`, newly created threads are stored with `memory_mode = \"disabled\"` in the state DB.",
"type": "boolean"
},
"max_raw_memories_for_consolidation": {
"description": "Maximum number of recent raw memories retained for global consolidation.",
"format": "uint",
"maximum": 4096.0,
"minimum": 1.0,
"type": "integer"
},
"max_rollout_age_days": {
"description": "Maximum age of the threads used for memories.",
"format": "int64",
"type": "integer"
},
"max_rollouts_per_startup": {
"description": "Maximum number of rollout candidates processed per pass.",
"format": "uint",
"maximum": 128.0,
"minimum": 1.0,
"type": "integer"
},
"max_unused_days": {
"description": "Maximum number of days since a memory was last used before it becomes ineligible for phase 2 selection.",
"format": "int64",
"type": "integer"
},
"min_rate_limit_remaining_percent": {
"description": "Minimum remaining percentage required in Codex rate-limit windows before memory startup runs.",
"format": "int64",
"maximum": 100.0,
"minimum": 0.0,
"type": "integer"
},
"min_rollout_idle_hours": {
"description": "Minimum idle time between last thread activity and memory creation (hours). > 12h recommended.",
"format": "int64",
"type": "integer"
},
"use_memories": {
"description": "When `false`, skip injecting memory usage instructions into developer prompts.",
"type": "boolean"
}
},
"type": "object"
},
"ModelAvailabilityNuxConfig": {
"additionalProperties": {
"format": "uint32",
"minimum": 0.0,
"type": "integer"
},
"type": "object"
},
"ModelProviderAuthInfo": {
"additionalProperties": false,
"description": "Configuration for obtaining a provider bearer token from a command.",
"properties": {
"args": {
"default": [],
"description": "Command arguments.",
"items": {
"type": "string"
},
"type": "array"
},
"command": {
"description": "Command to execute. Bare names are resolved via `PATH`; paths are resolved against `cwd`.",
"type": "string"
},
"cwd": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Working directory used when running the token command."
},
"refresh_interval_ms": {
"default": 300000,
"description": "Maximum age for the cached token before rerunning the command. Set to `0` to disable proactive refresh and only rerun after a 401 retry path.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"timeout_ms": {
"default": 5000,
"description": "Maximum time to wait for the token command to exit successfully.",
"format": "uint64",
"minimum": 1.0,
"type": "integer"
}
},
"required": [
"command"
],
"type": "object"
},
"ModelProviderAwsAuthInfo": {
"additionalProperties": false,
"description": "AWS SigV4 auth configuration for a model provider.",
"properties": {
"profile": {
"description": "AWS profile name to use. When unset, the AWS SDK default chain decides.",
"type": "string"
},
"region": {
"description": "AWS region to use for provider-specific endpoints.",
"type": "string"
}
},
"type": "object"
},
"ModelProviderInfo": {
"additionalProperties": false,
"description": "Serializable representation of a provider definition.",
"properties": {
"auth": {
"allOf": [
{
"$ref": "#/definitions/ModelProviderAuthInfo"
}
],
"description": "Command-backed bearer-token configuration for this provider."
},
"aws": {
"allOf": [
{
"$ref": "#/definitions/ModelProviderAwsAuthInfo"
}
],
"description": "AWS SigV4 auth configuration for this provider."
},
"base_url": {
"description": "Base URL for the provider's OpenAI-compatible API.",
"type": "string"
},
"env_http_headers": {
"additionalProperties": {
"type": "string"
},
"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"
},
"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 <token>` 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": {
"additionalProperties": {
"type": "string"
},
"description": "Additional HTTP headers to include in requests to this provider where the (key, value) pairs are the header name and value.",
"type": "object"
},
"name": {
"default": "",
"description": "Friendly display name.",
"type": "string"
},
"query_params": {
"additionalProperties": {
"type": "string"
},
"description": "Optional query parameters to append to the base URL.",
"type": "object"
},
"request_max_retries": {
"description": "Maximum number of times to retry a failed HTTP request to this provider.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"requires_openai_auth": {
"default": false,
"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.",
"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.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"stream_max_retries": {
"description": "Number of times to retry reconnecting a dropped streaming response before failing.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"supports_websockets": {
"default": false,
"description": "Whether this provider supports the Responses API WebSocket transport.",
"type": "boolean"
},
"websocket_connect_timeout_ms": {
"description": "Maximum time (in milliseconds) to wait for a websocket connection attempt before treating it as failed.",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"wire_api": {
"allOf": [
{
"$ref": "#/definitions/WireApi"
}
],
"default": "responses",
"description": "Which wire protocol this provider expects."
}
},
"type": "object"
},
"MultiAgentV2ConfigToml": {
"additionalProperties": false,
"properties": {
"default_wait_timeout_ms": {
"format": "int64",
"maximum": 3600000.0,
"minimum": 0.0,
"type": "integer"
},
"enabled": {
"type": "boolean"
},
"expose_spawn_agent_model_overrides": {
"description": "Exposes `model` and `reasoning_effort` on the multi-agent v2 spawn tool and adds corresponding guidance to root and subagent usage hints.",
"type": "boolean"
},
"hide_spawn_agent_metadata": {
"type": "boolean"
},
"max_concurrent_threads_per_session": {
"format": "uint",
"minimum": 1.0,
"type": "integer"
},
"max_wait_timeout_ms": {
"format": "int64",
"maximum": 3600000.0,
"minimum": 0.0,
"type": "integer"
},
"min_wait_timeout_ms": {
"format": "int64",
"maximum": 3600000.0,
"minimum": 0.0,
"type": "integer"
},
"multi_agent_mode_hint_text": {
"type": "string"
},
"non_code_mode_only": {
"type": "boolean"
},
"root_agent_usage_hint_text": {
"type": "string"
},
"subagent_usage_hint_text": {
"type": "string"
},
"tool_namespace": {
"maxLength": 64,
"minLength": 1,
"pattern": "^[a-zA-Z0-9_-]+$",
"type": "string"
},
"usage_hint_enabled": {
"description": "Deprecated compatibility field. Its value is ignored.",
"type": "boolean"
},
"usage_hint_text": {
"type": "string"
}
},
"type": "object"
},
"NetworkDomainPermissionToml": {
"enum": [
"allow",
"deny"
],
"type": "string"
},
"NetworkDomainPermissionsToml": {
"type": "object"
},
"NetworkMitmActionToml": {
"properties": {
"inject_request_headers": {
"default": [],
"items": {
"$ref": "#/definitions/NetworkMitmInjectedHeaderToml"
},
"type": "array"
},
"strip_request_headers": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"NetworkMitmHookToml": {
"additionalProperties": false,
"properties": {
"action": {
"items": {
"type": "string"
},
"type": "array"
},
"body": true,
"headers": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"default": {},
"type": "object"
},
"host": {
"type": "string"
},
"methods": {
"items": {
"type": "string"
},
"type": "array"
},
"path_prefixes": {
"items": {
"type": "string"
},
"type": "array"
},
"query": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"default": {},
"type": "object"
}
},
"required": [
"action",
"host",
"methods",
"path_prefixes"
],
"type": "object"
},
"NetworkMitmInjectedHeaderToml": {
"properties": {
"name": {
"default": "",
"type": "string"
},
"prefix": {
"default": null,
"type": "string"
},
"secret_env_var": {
"default": null,
"type": "string"
},
"secret_file": {
"default": null,
"type": "string"
}
},
"type": "object"
},
"NetworkMitmToml": {
"additionalProperties": false,
"properties": {
"actions": {
"additionalProperties": {
"$ref": "#/definitions/NetworkMitmActionToml"
},
"type": "object"
},
"hooks": {
"additionalProperties": {
"$ref": "#/definitions/NetworkMitmHookToml"
},
"type": "object"
}
},
"type": "object"
},
"NetworkModeSchema": {
"enum": [
"limited",
"full"
],
"type": "string"
},
"NetworkProxyConfigToml": {
"additionalProperties": false,
"properties": {
"allow_local_binding": {
"type": "boolean"
},
"allow_upstream_proxy": {
"type": "boolean"
},
"dangerously_allow_all_unix_sockets": {
"type": "boolean"
},
"dangerously_allow_non_loopback_proxy": {
"type": "boolean"
},
"domains": {
"additionalProperties": {
"$ref": "#/definitions/NetworkProxyDomainPermissionToml"
},
"type": "object"
},
"enable_socks5": {
"type": "boolean"
},
"enable_socks5_udp": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"mode": {
"$ref": "#/definitions/NetworkProxyModeToml"
},
"proxy_url": {
"type": "string"
},
"socks_url": {
"type": "string"
},
"unix_sockets": {
"additionalProperties": {
"$ref": "#/definitions/NetworkProxyUnixSocketPermissionToml"
},
"type": "object"
}
},
"type": "object"
},
"NetworkProxyDomainPermissionToml": {
"enum": [
"allow",
"deny"
],
"type": "string"
},
"NetworkProxyModeToml": {
"enum": [
"limited",
"full"
],
"type": "string"
},
"NetworkProxyUnixSocketPermissionToml": {
"enum": [
"allow",
"deny"
],
"type": "string"
},
"NetworkToml": {
"additionalProperties": false,
"properties": {
"allow_local_binding": {
"type": "boolean"
},
"allow_upstream_proxy": {
"type": "boolean"
},
"dangerously_allow_all_unix_sockets": {
"type": "boolean"
},
"dangerously_allow_non_loopback_proxy": {
"type": "boolean"
},
"domains": {
"$ref": "#/definitions/NetworkDomainPermissionsToml"
},
"enable_socks5": {
"type": "boolean"
},
"enable_socks5_udp": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"mitm": {
"$ref": "#/definitions/NetworkMitmToml"
},
"mode": {
"$ref": "#/definitions/NetworkModeSchema"
},
"proxy_url": {
"type": "string"
},
"socks_url": {
"type": "string"
},
"unix_sockets": {
"$ref": "#/definitions/NetworkUnixSocketPermissionsToml"
}
},
"type": "object"
},
"NetworkUnixSocketPermissionToml": {
"enum": [
"allow",
"deny"
],
"type": "string"
},
"NetworkUnixSocketPermissionsToml": {
"type": "object"
},
"Notice": {
"additionalProperties": false,
"properties": {
"external_config_migration_prompts": {
"allOf": [
{
"$ref": "#/definitions/ExternalConfigMigrationPrompts"
}
],
"default": {
"home": null,
"home_last_prompted_at": null,
"project_last_prompted_at": {},
"projects": {}
},
"description": "Tracks scopes where external config migration prompts should be suppressed."
},
"fast_default_opt_out": {
"description": "Tracks whether the user opted out of Codex-managed fast defaults.",
"type": "boolean"
},
"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": {
"additionalProperties": {
"type": "string"
},
"default": {},
"description": "Tracks acknowledged model migrations as old->new model slug mappings.",
"type": "object"
}
},
"type": "object"
},
"NotificationCondition": {
"oneOf": [
{
"description": "Emit TUI notifications only while the terminal is unfocused.",
"enum": [
"unfocused"
],
"type": "string"
},
{
"description": "Emit TUI notifications regardless of terminal focus.",
"enum": [
"always"
],
"type": "string"
}
]
},
"NotificationMethod": {
"enum": [
"auto",
"osc9",
"bel"
],
"type": "string"
},
"Notifications": {
"anyOf": [
{
"type": "boolean"
},
{
"items": {
"type": "string"
},
"type": "array"
}
]
},
"OAuthCredentialsStoreMode": {
"description": "Determine where Codex should store and read MCP credentials.",
"oneOf": [
{
"description": "Prefer `Keyring` and use `File` when keyring storage is unavailable. Once an MCP client loads credentials from one store, that client keeps the resolved store for its lifetime so refreshes cannot switch to a possibly stale credential source. Credentials stored in the keyring will only be readable by Codex unless the user explicitly grants access via OS-level keyring access.",
"enum": [
"auto"
],
"type": "string"
},
{
"description": "CODEX_HOME/.credentials.json This file will be readable to Codex and other applications running as the same user.",
"enum": [
"file"
],
"type": "string"
},
{
"description": "Keyring when available, otherwise fail.",
"enum": [
"keyring"
],
"type": "string"
}
]
},
"OrchestratorFeatureToml": {
"additionalProperties": false,
"description": "Settings for a feature owned by the orchestrator.",
"properties": {
"enabled": {
"type": "boolean"
}
},
"type": "object"
},
"OrchestratorToml": {
"additionalProperties": false,
"description": "Orchestrator-owned feature settings.",
"properties": {
"mcp": {
"$ref": "#/definitions/OrchestratorFeatureToml"
},
"skills": {
"$ref": "#/definitions/OrchestratorFeatureToml"
}
},
"type": "object"
},
"OtelConfigToml": {
"additionalProperties": false,
"description": "OTEL settings loaded from config.toml. Fields are optional so we can apply defaults.",
"properties": {
"environment": {
"description": "Mark traces with environment (dev, staging, prod, test). Defaults to dev.",
"type": "string"
},
"exporter": {
"allOf": [
{
"$ref": "#/definitions/OtelExporterKind"
}
],
"description": "Optional log exporter"
},
"log_user_prompt": {
"description": "Log user prompt in traces",
"type": "boolean"
},
"metrics_exporter": {
"allOf": [
{
"$ref": "#/definitions/OtelExporterKind"
}
],
"description": "Optional metrics exporter"
},
"span_attributes": {
"additionalProperties": {
"type": "string"
},
"description": "Attributes to add to every exported trace span.",
"type": "object"
},
"trace_exporter": {
"allOf": [
{
"$ref": "#/definitions/OtelExporterKind"
}
],
"description": "Optional trace exporter"
},
"tracestate": {
"additionalProperties": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"description": "Semicolon-separated `key:value` fields to upsert into W3C tracestate members.",
"type": "object"
}
},
"type": "object"
},
"OtelExporterKind": {
"description": "Which OTEL exporter to use.",
"oneOf": [
{
"enum": [
"none",
"statsig"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"otlp-http": {
"additionalProperties": false,
"properties": {
"endpoint": {
"type": "string"
},
"headers": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"protocol": {
"$ref": "#/definitions/OtelHttpProtocol"
},
"tls": {
"allOf": [
{
"$ref": "#/definitions/OtelTlsConfig"
}
],
"default": null
}
},
"required": [
"endpoint",
"protocol"
],
"type": "object"
}
},
"required": [
"otlp-http"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"otlp-grpc": {
"additionalProperties": false,
"properties": {
"endpoint": {
"type": "string"
},
"headers": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"tls": {
"allOf": [
{
"$ref": "#/definitions/OtelTlsConfig"
}
],
"default": null
}
},
"required": [
"endpoint"
],
"type": "object"
}
},
"required": [
"otlp-grpc"
],
"type": "object"
}
]
},
"OtelHttpProtocol": {
"oneOf": [
{
"description": "Binary payload",
"enum": [
"binary"
],
"type": "string"
},
{
"description": "JSON payload",
"enum": [
"json"
],
"type": "string"
}
]
},
"OtelTlsConfig": {
"additionalProperties": false,
"properties": {
"ca-certificate": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"client-certificate": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"client-private-key": {
"$ref": "#/definitions/AbsolutePathBuf"
}
},
"type": "object"
},
"PermissionProfileToml": {
"additionalProperties": false,
"properties": {
"description": {
"type": "string"
},
"extends": {
"type": "string"
},
"filesystem": {
"$ref": "#/definitions/FilesystemPermissionsToml"
},
"network": {
"$ref": "#/definitions/NetworkToml"
},
"workspace_roots": {
"$ref": "#/definitions/WorkspaceRootsToml"
}
},
"type": "object"
},
"PermissionsToml": {
"type": "object"
},
"Personality": {
"enum": [
"none",
"friendly",
"pragmatic"
],
"type": "string"
},
"PluginConfig": {
"additionalProperties": false,
"properties": {
"enabled": {
"default": true,
"type": "boolean"
},
"mcp_servers": {
"additionalProperties": {
"$ref": "#/definitions/PluginMcpServerConfig"
},
"description": "Per-MCP-server policy overlays for MCP servers contributed by this plugin.",
"type": "object"
}
},
"type": "object"
},
"PluginMcpServerConfig": {
"additionalProperties": false,
"description": "Policy settings for a plugin-provided MCP server.\n\nThis intentionally excludes transport settings: plugin manifests own how the MCP server is launched, while user config owns enablement and tool policy.",
"properties": {
"default_tools_approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"description": "Approval mode for tools in this server unless a tool override exists."
},
"disabled_tools": {
"description": "Explicit deny-list of tools. These tools are removed after applying `enabled_tools`.",
"items": {
"type": "string"
},
"type": "array"
},
"enabled": {
"default": true,
"description": "When `false`, Codex skips initializing this plugin MCP server.",
"type": "boolean"
},
"enabled_tools": {
"description": "Explicit allow-list of tools exposed from this server.",
"items": {
"type": "string"
},
"type": "array"
},
"tools": {
"additionalProperties": {
"$ref": "#/definitions/McpServerToolConfig"
},
"description": "Per-tool approval settings keyed by tool name.",
"type": "object"
}
},
"type": "object"
},
"ProfileTui": {
"additionalProperties": false,
"description": "TUI settings supported inside a named profile.",
"properties": {
"session_picker_view": {
"allOf": [
{
"$ref": "#/definitions/SessionPickerViewMode"
}
],
"default": null,
"description": "Preferred layout for resume/fork session picker results."
}
},
"type": "object"
},
"ProjectConfig": {
"additionalProperties": false,
"properties": {
"trust_level": {
"$ref": "#/definitions/TrustLevel"
}
},
"type": "object"
},
"RawMcpServerConfig": {
"additionalProperties": false,
"description": "Raw MCP config shape used for deserialization and supported-field JSON Schema generation.\n\nFields that are accepted only to produce targeted validation errors should be skipped in the generated schema.\n\nKeep `TryFrom<RawMcpServerConfig> for McpServerConfig` exhaustively destructuring this struct so new TOML fields cannot be added here without updating the validation/mapping logic that produces [`McpServerConfig`].",
"properties": {
"args": {
"default": null,
"items": {
"type": "string"
},
"type": "array"
},
"auth": {
"allOf": [
{
"$ref": "#/definitions/McpServerAuth"
}
],
"default": null
},
"bearer_token_env_var": {
"type": "string"
},
"command": {
"type": "string"
},
"cwd": {
"allOf": [
{
"$ref": "#/definitions/LegacyAppPathString"
}
],
"default": null
},
"default_tools_approval_mode": {
"allOf": [
{
"$ref": "#/definitions/AppToolApproval"
}
],
"default": null
},
"disabled_tools": {
"default": null,
"items": {
"type": "string"
},
"type": "array"
},
"enabled": {
"default": null,
"type": "boolean"
},
"enabled_tools": {
"default": null,
"items": {
"type": "string"
},
"type": "array"
},
"env": {
"additionalProperties": {
"type": "string"
},
"default": null,
"type": "object"
},
"env_http_headers": {
"additionalProperties": {
"type": "string"
},
"default": null,
"type": "object"
},
"env_vars": {
"default": null,
"items": {
"$ref": "#/definitions/McpServerEnvVar"
},
"type": "array"
},
"environment_id": {
"default": null,
"type": "string"
},
"http_headers": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"name": {
"default": null,
"description": "Legacy display-name field accepted for backward compatibility.",
"type": "string"
},
"oauth": {
"allOf": [
{
"$ref": "#/definitions/McpServerOAuthConfig"
}
],
"default": null
},
"oauth_resource": {
"default": null,
"type": "string"
},
"required": {
"default": null,
"type": "boolean"
},
"scopes": {
"default": null,
"items": {
"type": "string"
},
"type": "array"
},
"startup_timeout_ms": {
"default": null,
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"startup_timeout_sec": {
"default": null,
"format": "double",
"type": "number"
},
"supports_parallel_tool_calls": {
"default": null,
"type": "boolean"
},
"tool_timeout_sec": {
"default": null,
"format": "double",
"type": "number"
},
"tools": {
"additionalProperties": {
"$ref": "#/definitions/McpServerToolConfig"
},
"default": null,
"type": "object"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"RealtimeAudioToml": {
"additionalProperties": false,
"properties": {
"microphone": {
"type": "string"
},
"speaker": {
"type": "string"
}
},
"type": "object"
},
"RealtimeConversationVersion": {
"enum": [
"v1",
"v2",
"v3"
],
"type": "string"
},
"RealtimeToml": {
"additionalProperties": false,
"properties": {
"transport": {
"$ref": "#/definitions/RealtimeTransport"
},
"type": {
"$ref": "#/definitions/RealtimeWsMode"
},
"version": {
"$ref": "#/definitions/RealtimeConversationVersion"
},
"voice": {
"$ref": "#/definitions/RealtimeVoice"
}
},
"type": "object"
},
"RealtimeTransport": {
"enum": [
"webrtc",
"websocket"
],
"type": "string"
},
"RealtimeVoice": {
"enum": [
"alloy",
"arbor",
"ash",
"ballad",
"breeze",
"cedar",
"coral",
"cove",
"echo",
"ember",
"juniper",
"maple",
"marin",
"sage",
"shimmer",
"sol",
"spruce",
"vale",
"verse"
],
"type": "string"
},
"RealtimeWsMode": {
"enum": [
"conversational",
"transcription"
],
"type": "string"
},
"ReasoningEffort": {
"description": "A non-empty reasoning effort value advertised by the model.",
"minLength": 1,
"type": "string"
},
"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": [
{
"enum": [
"auto",
"concise",
"detailed"
],
"type": "string"
},
{
"description": "Option to disable reasoning summaries.",
"enum": [
"none"
],
"type": "string"
}
]
},
"ResumeCwdMode": {
"description": "Working directory to use when resuming or forking a session.",
"oneOf": [
{
"description": "Use the directory where Codex was launched.",
"enum": [
"current"
],
"type": "string"
},
{
"description": "Use the latest working directory recorded in the selected session.",
"enum": [
"session"
],
"type": "string"
}
]
},
"RolloutBudgetConfigToml": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"limit_tokens": {
"format": "int64",
"minimum": 1.0,
"type": "integer"
},
"prefill_token_weight": {
"format": "double",
"minimum": 0.0,
"type": "number"
},
"reminder_at_remaining_tokens": {
"description": "Remaining weighted-token values that trigger reminders when crossed.",
"items": {
"format": "int64",
"type": "integer"
},
"type": "array"
},
"sampling_token_weight": {
"format": "double",
"minimum": 0.0,
"type": "number"
}
},
"type": "object"
},
"SandboxMode": {
"enum": [
"read-only",
"workspace-write",
"danger-full-access"
],
"type": "string"
},
"SandboxWorkspaceWrite": {
"additionalProperties": false,
"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": [],
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
}
},
"type": "object"
},
"SessionPickerViewMode": {
"description": "Preferred layout for the resume/fork session picker.",
"enum": [
"comfortable",
"dense"
],
"type": "string"
},
"ShellEnvironmentPolicyFilter": {
"description": "Assigns a shell environment variable pattern to the include-only or exclude set. Includes do not re-add variables removed by another exclude pattern.",
"enum": [
"include",
"exclude"
],
"type": "string"
},
"ShellEnvironmentPolicyInherit": {
"oneOf": [
{
"description": "\"Core\" environment variables for the platform. On UNIX, this would include HOME, LOGNAME, PATH, SHELL, and USER, among others.",
"enum": [
"core"
],
"type": "string"
},
{
"description": "Inherits the full environment from the parent process.",
"enum": [
"all"
],
"type": "string"
},
{
"description": "Do not inherit any environment variables from the parent process.",
"enum": [
"none"
],
"type": "string"
}
]
},
"ShellEnvironmentPolicyToml": {
"additionalProperties": false,
"allOf": [
{
"not": {
"required": [
"exclude",
"filters"
]
}
},
{
"not": {
"required": [
"filters",
"include_only"
]
}
}
],
"description": "Policy for building the `env` when spawning a process via shell-like tools.",
"properties": {
"exclude": {
"description": "Legacy list of regular expressions to exclude.",
"items": {
"type": "string"
},
"type": "array"
},
"experimental_use_profile": {
"type": "boolean"
},
"filters": {
"additionalProperties": {
"$ref": "#/definitions/ShellEnvironmentPolicyFilter"
},
"description": "Pattern actions used by the canonical table representation.\n\nOrdinary config keeps accepting the legacy arrays above during the migration. Requirements will accept only this keyed form, keeping array compatibility isolated so the legacy fields can be deprecated later. Pattern keys merge case-insensitively across config layers, matching how the resulting patterns match environment variable names.",
"type": "object"
},
"ignore_default_excludes": {
"type": "boolean"
},
"include_only": {
"description": "Legacy list of regular expressions to include.",
"items": {
"type": "string"
},
"type": "array"
},
"inherit": {
"$ref": "#/definitions/ShellEnvironmentPolicyInherit"
},
"set": {
"additionalProperties": {
"type": "string"
},
"type": "object"
}
},
"type": "object"
},
"SkillConfig": {
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"name": {
"description": "Name-based selector.",
"type": "string"
},
"path": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Path-based selector."
}
},
"required": [
"enabled"
],
"type": "object"
},
"SkillsConfig": {
"additionalProperties": false,
"properties": {
"bundled": {
"$ref": "#/definitions/BundledSkillsConfig"
},
"config": {
"items": {
"$ref": "#/definitions/SkillConfig"
},
"type": "array"
},
"include_instructions": {
"description": "Whether turns receive the automatic skills instructions block.",
"type": "boolean"
}
},
"type": "object"
},
"ThreadStoreToml": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"local"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
}
]
},
"TokenBudgetConfigToml": {
"additionalProperties": false,
"properties": {
"auto_compact_fallback_buffer_tokens": {
"description": "Additional tokens available after the compaction threshold for fallback note-taking.",
"format": "int64",
"minimum": 1.0,
"type": "integer"
},
"auto_compact_fallback_prompt": {
"description": "Developer message sampled before an automatic context-window rollover.",
"maxLength": 2000,
"type": "string"
},
"enabled": {
"type": "boolean"
},
"guidance_message": {
"description": "Guidance appended to the context-window metadata in a developer message.",
"maxLength": 2000,
"type": "string"
},
"reminder_message_template": {
"description": "Reminder template. `{n_remaining}` is replaced with the tokens remaining before auto-compaction.",
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"reminder_threshold_tokens": {
"description": "Number of tokens remaining before auto-compaction when the wrap-up reminder is emitted.",
"format": "int64",
"minimum": 1.0,
"type": "integer"
}
},
"type": "object"
},
"ToolSuggestConfig": {
"additionalProperties": false,
"properties": {
"disabled_tools": {
"default": [],
"items": {
"$ref": "#/definitions/ToolSuggestDisabledTool"
},
"type": "array"
},
"discoverables": {
"default": [],
"items": {
"$ref": "#/definitions/ToolSuggestDiscoverable"
},
"type": "array"
}
},
"type": "object"
},
"ToolSuggestDisabledTool": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"type": {
"$ref": "#/definitions/ToolSuggestDiscoverableType"
}
},
"required": [
"id",
"type"
],
"type": "object"
},
"ToolSuggestDiscoverable": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"type": {
"$ref": "#/definitions/ToolSuggestDiscoverableType"
}
},
"required": [
"id",
"type"
],
"type": "object"
},
"ToolSuggestDiscoverableType": {
"enum": [
"connector",
"plugin"
],
"type": "string"
},
"ToolsToml": {
"additionalProperties": false,
"properties": {
"experimental_request_user_input": {
"$ref": "#/definitions/ExperimentalRequestUserInput"
},
"web_search": {
"allOf": [
{
"$ref": "#/definitions/WebSearchToolConfig"
}
],
"default": null
}
},
"type": "object"
},
"TrustLevel": {
"description": "Represents the trust level for a project directory. This determines the approval policy and sandbox mode applied.",
"enum": [
"trusted",
"untrusted"
],
"type": "string"
},
"Tui": {
"additionalProperties": false,
"description": "Collection of settings that are specific to the TUI.",
"properties": {
"alternate_screen": {
"allOf": [
{
"$ref": "#/definitions/AltScreenMode"
}
],
"default": "auto",
"description": "Controls whether the TUI uses the terminal's alternate screen buffer.\n\n- `auto` (default): Use alternate screen. - `always`: Always use alternate screen. - `never`: Never use alternate screen (inline mode only, preserves scrollback)."
},
"animations": {
"default": true,
"description": "Enable animations (welcome screen, shimmer effects, spinners). Defaults to `true`.",
"type": "boolean"
},
"keymap": {
"allOf": [
{
"$ref": "#/definitions/TuiKeymap"
}
],
"default": {
"approval": {
"approve": null,
"approve_for_prefix": null,
"approve_for_session": null,
"cancel": null,
"decline": null,
"deny": null,
"open_fullscreen": null,
"open_thread": null
},
"chat": {
"decrease_reasoning_effort": null,
"edit_queued_message": null,
"increase_reasoning_effort": null,
"interrupt_turn": null
},
"composer": {
"history_search_next": null,
"history_search_previous": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
},
"editor": {
"delete_backward": null,
"delete_backward_word": null,
"delete_forward": null,
"delete_forward_word": null,
"insert_newline": null,
"kill_line_end": null,
"kill_line_start": null,
"kill_whole_line": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_left": null,
"move_word_right": null,
"yank": null
},
"global": {
"clear_terminal": null,
"copy": null,
"open_external_editor": null,
"open_transcript": null,
"queue": null,
"submit": null,
"toggle_fast_mode": null,
"toggle_raw_output": null,
"toggle_shortcuts": null,
"toggle_vim_mode": null
},
"list": {
"accept": null,
"cancel": null,
"jump_bottom": null,
"jump_top": null,
"move_down": null,
"move_left": null,
"move_right": null,
"move_up": null,
"page_down": null,
"page_up": null
},
"pager": {
"close": null,
"close_transcript": null,
"half_page_down": null,
"half_page_up": null,
"jump_bottom": null,
"jump_top": null,
"page_down": null,
"page_up": null,
"scroll_down": null,
"scroll_up": null
},
"vim_normal": {
"append_after_cursor": null,
"append_line_end": null,
"cancel_operator": null,
"change_to_line_end": null,
"delete_char": null,
"delete_to_line_end": null,
"enter_insert": null,
"insert_line_start": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_backward": null,
"move_word_end": null,
"move_word_forward": null,
"open_line_above": null,
"open_line_below": null,
"paste_after": null,
"start_change_operator": null,
"start_delete_operator": null,
"start_yank_operator": null,
"substitute_char": null,
"yank_line": null
},
"vim_operator": {
"cancel": null,
"delete_line": null,
"motion_down": null,
"motion_left": null,
"motion_line_end": null,
"motion_line_start": null,
"motion_right": null,
"motion_up": null,
"motion_word_backward": null,
"motion_word_end": null,
"motion_word_forward": null,
"select_around_text_object": null,
"select_inner_text_object": null,
"yank_line": null
},
"vim_text_object": {
"backtick": null,
"big_word": null,
"braces": null,
"brackets": null,
"cancel": null,
"double_quote": null,
"parentheses": null,
"single_quote": null,
"word": null
}
},
"description": "Keybinding overrides for the TUI.\n\nThis supports rebinding selected actions globally and by context. Context bindings take precedence over `global` bindings."
},
"model_availability_nux": {
"allOf": [
{
"$ref": "#/definitions/ModelAvailabilityNuxConfig"
}
],
"default": {},
"description": "Startup tooltip availability NUX state persisted by the TUI."
},
"notification_condition": {
"allOf": [
{
"$ref": "#/definitions/NotificationCondition"
}
],
"default": "unfocused",
"description": "Controls whether TUI notifications are delivered only when the terminal is unfocused or regardless of focus. Defaults to `unfocused`."
},
"notification_method": {
"allOf": [
{
"$ref": "#/definitions/NotificationMethod"
}
],
"default": "auto",
"description": "Notification method to use for terminal notifications. Defaults to `auto`."
},
"notifications": {
"allOf": [
{
"$ref": "#/definitions/Notifications"
}
],
"default": true,
"description": "Enable desktop notifications from the TUI. Defaults to `true`."
},
"pet": {
"default": null,
"description": "Pet id to preselect in the terminal pet picker.\n\nCustom pet ids resolve against CODEX_HOME/pets/<pet-id>/pet.json.",
"type": "string"
},
"pet_anchor": {
"allOf": [
{
"$ref": "#/definitions/TuiPetAnchor"
}
],
"default": "composer",
"description": "Where the terminal pet should anchor vertically.\n\nDefaults to `composer`, which follows the current TUI composer viewport."
},
"raw_output_mode": {
"default": false,
"description": "Start the TUI in raw scrollback mode for copy-friendly transcript output. Defaults to `false`.",
"type": "boolean"
},
"resume_cwd": {
"allOf": [
{
"$ref": "#/definitions/ResumeCwdMode"
}
],
"default": null,
"description": "Working directory to use when resuming or forking a session. When unset, prompt if the current and session directories differ."
},
"session_picker_view": {
"allOf": [
{
"$ref": "#/definitions/SessionPickerViewMode"
}
],
"default": null,
"description": "Preferred layout for resume/fork session picker results."
},
"show_tooltips": {
"default": true,
"description": "Show startup tooltips in the TUI welcome screen. Defaults to `true`.",
"type": "boolean"
},
"status_line": {
"default": null,
"description": "Ordered list of status line item identifiers.\n\nWhen set, the TUI renders the selected items as the status line. When unset, the TUI defaults to: `model-with-reasoning` and `current-dir`.",
"items": {
"type": "string"
},
"type": "array"
},
"status_line_use_colors": {
"default": true,
"description": "Color status line items with colors derived from the active syntax theme. Defaults to `true`.",
"type": "boolean"
},
"terminal_resize_reflow_max_rows": {
"default": null,
"description": "Trim terminal resize-reflow replay to the most recent rendered terminal rows when the transcript exceeds this cap. Omit to use Codex's terminal-specific default. Set to `0` to keep all rendered rows.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"terminal_title": {
"default": null,
"description": "Ordered list of terminal title item identifiers.\n\nWhen set, the TUI renders the selected items into the terminal window/tab title. When unset, the TUI defaults to: `activity` and `project`. The `activity` item spins while working and shows an action-required message when blocked on the user.",
"items": {
"type": "string"
},
"type": "array"
},
"theme": {
"default": null,
"description": "Syntax highlighting theme name (kebab-case).\n\nWhen set, overrides automatic light/dark theme detection. Use `/theme` in the TUI or see `$CODEX_HOME/themes` for custom themes.",
"type": "string"
},
"vim_mode_default": {
"default": false,
"description": "Start the composer in Vim mode (`Normal`) by default. Defaults to `false`.",
"type": "boolean"
}
},
"type": "object"
},
"TuiApprovalKeymap": {
"additionalProperties": false,
"description": "Approval overlay keybindings.",
"properties": {
"approve": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Approve the primary option."
},
"approve_for_prefix": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Approve with exec-policy prefix when that option exists."
},
"approve_for_session": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Approve for session when that option exists."
},
"cancel": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Cancel an elicitation request."
},
"decline": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Decline and provide corrective guidance."
},
"deny": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Deny without providing follow-up guidance."
},
"open_fullscreen": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open the full-screen approval details view."
},
"open_thread": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open the thread that requested approval when shown from another thread."
}
},
"type": "object"
},
"TuiChatKeymap": {
"additionalProperties": false,
"description": "Chat context keybindings.",
"properties": {
"decrease_reasoning_effort": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Decrease the active reasoning effort."
},
"edit_queued_message": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Edit the most recently queued message."
},
"increase_reasoning_effort": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Increase the active reasoning effort."
},
"interrupt_turn": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Interrupt the active turn."
}
},
"type": "object"
},
"TuiComposerKeymap": {
"additionalProperties": false,
"description": "Composer context keybindings. These override corresponding `global` actions.",
"properties": {
"history_search_next": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move to the next match in reverse history search."
},
"history_search_previous": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open reverse history search or move to the previous match."
},
"queue": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Queue the current composer draft while a task is running."
},
"submit": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Submit the current composer draft."
},
"toggle_shortcuts": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Toggle the composer shortcut overlay."
}
},
"type": "object"
},
"TuiEditorKeymap": {
"additionalProperties": false,
"description": "Editor context keybindings for text editing inside text areas.",
"properties": {
"delete_backward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete one grapheme to the left."
},
"delete_backward_word": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete the previous word."
},
"delete_forward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete one grapheme to the right."
},
"delete_forward_word": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete the next word."
},
"insert_newline": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Insert a newline in the editor."
},
"kill_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Kill text from cursor to line end."
},
"kill_line_start": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Kill text from cursor to line start."
},
"kill_whole_line": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Kill the current line."
},
"move_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor down one visual line."
},
"move_left": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor left by one grapheme."
},
"move_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to end of line."
},
"move_line_start": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to beginning of line."
},
"move_right": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor right by one grapheme."
},
"move_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor up one visual line."
},
"move_word_left": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to beginning of previous word."
},
"move_word_right": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to end of next word."
},
"yank": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Yank the kill buffer."
}
},
"type": "object"
},
"TuiGlobalKeymap": {
"additionalProperties": false,
"description": "Global keybindings. These are used when a context does not define an override.",
"properties": {
"clear_terminal": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Clear the terminal UI."
},
"copy": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Copy the last agent response to the clipboard."
},
"open_external_editor": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open the external editor for the current draft."
},
"open_transcript": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open the transcript overlay."
},
"queue": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Queue the current composer draft while a task is running."
},
"submit": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Submit the current composer draft."
},
"toggle_fast_mode": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Toggle Fast mode."
},
"toggle_raw_output": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Toggle raw scrollback mode for copy-friendly transcript selection."
},
"toggle_shortcuts": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Toggle the composer shortcut overlay."
},
"toggle_vim_mode": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Toggle Vim mode for the composer input."
}
},
"type": "object"
},
"TuiKeymap": {
"additionalProperties": false,
"description": "Raw keymap configuration from `[tui.keymap]`.\n\nEach context contains action-level overrides. Missing actions inherit from built-in defaults, and selected chat/composer actions can fall back through `global` during runtime resolution.\n\nThis type is intentionally a persistence shape, not the structure used by input handlers. Runtime consumers should resolve it into `RuntimeKeymap` first so precedence, empty-list unbinding, and duplicate-key validation are applied consistently.",
"properties": {
"approval": {
"allOf": [
{
"$ref": "#/definitions/TuiApprovalKeymap"
}
],
"default": {
"approve": null,
"approve_for_prefix": null,
"approve_for_session": null,
"cancel": null,
"decline": null,
"deny": null,
"open_fullscreen": null,
"open_thread": null
}
},
"chat": {
"allOf": [
{
"$ref": "#/definitions/TuiChatKeymap"
}
],
"default": {
"decrease_reasoning_effort": null,
"edit_queued_message": null,
"increase_reasoning_effort": null,
"interrupt_turn": null
}
},
"composer": {
"allOf": [
{
"$ref": "#/definitions/TuiComposerKeymap"
}
],
"default": {
"history_search_next": null,
"history_search_previous": null,
"queue": null,
"submit": null,
"toggle_shortcuts": null
}
},
"editor": {
"allOf": [
{
"$ref": "#/definitions/TuiEditorKeymap"
}
],
"default": {
"delete_backward": null,
"delete_backward_word": null,
"delete_forward": null,
"delete_forward_word": null,
"insert_newline": null,
"kill_line_end": null,
"kill_line_start": null,
"kill_whole_line": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_left": null,
"move_word_right": null,
"yank": null
}
},
"global": {
"allOf": [
{
"$ref": "#/definitions/TuiGlobalKeymap"
}
],
"default": {
"clear_terminal": null,
"copy": null,
"open_external_editor": null,
"open_transcript": null,
"queue": null,
"submit": null,
"toggle_fast_mode": null,
"toggle_raw_output": null,
"toggle_shortcuts": null,
"toggle_vim_mode": null
}
},
"list": {
"allOf": [
{
"$ref": "#/definitions/TuiListKeymap"
}
],
"default": {
"accept": null,
"cancel": null,
"jump_bottom": null,
"jump_top": null,
"move_down": null,
"move_left": null,
"move_right": null,
"move_up": null,
"page_down": null,
"page_up": null
}
},
"pager": {
"allOf": [
{
"$ref": "#/definitions/TuiPagerKeymap"
}
],
"default": {
"close": null,
"close_transcript": null,
"half_page_down": null,
"half_page_up": null,
"jump_bottom": null,
"jump_top": null,
"page_down": null,
"page_up": null,
"scroll_down": null,
"scroll_up": null
}
},
"vim_normal": {
"allOf": [
{
"$ref": "#/definitions/TuiVimNormalKeymap"
}
],
"default": {
"append_after_cursor": null,
"append_line_end": null,
"cancel_operator": null,
"change_to_line_end": null,
"delete_char": null,
"delete_to_line_end": null,
"enter_insert": null,
"insert_line_start": null,
"move_down": null,
"move_left": null,
"move_line_end": null,
"move_line_start": null,
"move_right": null,
"move_up": null,
"move_word_backward": null,
"move_word_end": null,
"move_word_forward": null,
"open_line_above": null,
"open_line_below": null,
"paste_after": null,
"start_change_operator": null,
"start_delete_operator": null,
"start_yank_operator": null,
"substitute_char": null,
"yank_line": null
}
},
"vim_operator": {
"allOf": [
{
"$ref": "#/definitions/TuiVimOperatorKeymap"
}
],
"default": {
"cancel": null,
"delete_line": null,
"motion_down": null,
"motion_left": null,
"motion_line_end": null,
"motion_line_start": null,
"motion_right": null,
"motion_up": null,
"motion_word_backward": null,
"motion_word_end": null,
"motion_word_forward": null,
"select_around_text_object": null,
"select_inner_text_object": null,
"yank_line": null
}
},
"vim_text_object": {
"allOf": [
{
"$ref": "#/definitions/TuiVimTextObjectKeymap"
}
],
"default": {
"backtick": null,
"big_word": null,
"braces": null,
"brackets": null,
"cancel": null,
"double_quote": null,
"parentheses": null,
"single_quote": null,
"word": null
}
}
},
"type": "object"
},
"TuiListKeymap": {
"additionalProperties": false,
"description": "List selection context keybindings for popup-style selectable lists.",
"properties": {
"accept": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Accept current selection."
},
"cancel": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Cancel and close selection view."
},
"jump_bottom": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Jump to the last list item."
},
"jump_top": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Jump to the first list item."
},
"move_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move list selection down."
},
"move_left": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move horizontally left in list pickers that support horizontal actions."
},
"move_right": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move horizontally right in list pickers that support horizontal actions."
},
"move_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move list selection up."
},
"page_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move list selection down by one page."
},
"page_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move list selection up by one page."
}
},
"type": "object"
},
"TuiPagerKeymap": {
"additionalProperties": false,
"description": "Pager context keybindings for transcript and static overlays.",
"properties": {
"close": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Close the pager overlay."
},
"close_transcript": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Close the transcript overlay via its dedicated toggle key."
},
"half_page_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll down by half a page."
},
"half_page_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll up by half a page."
},
"jump_bottom": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Jump to the end."
},
"jump_top": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Jump to the beginning."
},
"page_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll down by one page."
},
"page_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll up by one page."
},
"scroll_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll down by one row."
},
"scroll_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Scroll up by one row."
}
},
"type": "object"
},
"TuiPetAnchor": {
"oneOf": [
{
"description": "Anchor the pet to the bottom of the current TUI composer viewport.",
"enum": [
"composer"
],
"type": "string"
},
{
"description": "Anchor the pet to the physical bottom of the terminal screen.",
"enum": [
"screen-bottom"
],
"type": "string"
}
]
},
"TuiVimNormalKeymap": {
"additionalProperties": false,
"description": "Vim normal-mode keybindings for modal editing inside text areas.\n\nActions that use uppercase letters (like `A` for append-line-end) should be specified as `shift-a` in config; the runtime matcher handles cross-terminal shift-reporting differences automatically.",
"properties": {
"append_after_cursor": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Enter insert mode after cursor (`a`)."
},
"append_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Enter insert mode at end of line (`A`)."
},
"cancel_operator": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Cancel a pending operator and return to normal mode."
},
"change_to_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Change from cursor to end of line and enter insert mode (`C`)."
},
"delete_char": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete character under cursor (`x`)."
},
"delete_to_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete from cursor to end of line (`D`)."
},
"enter_insert": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Enter insert mode at cursor (`i`)."
},
"insert_line_start": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Enter insert mode at first non-blank of line (`I`)."
},
"move_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor down (`j`), or recall newer composer history at history boundaries."
},
"move_left": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor left (`h`)."
},
"move_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to end of line (`$`)."
},
"move_line_start": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to start of line (`0`)."
},
"move_right": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor right (`l`)."
},
"move_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor up (`k`), or recall older composer history at history boundaries."
},
"move_word_backward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to start of previous word (`b`)."
},
"move_word_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to end of current/next word (`e`)."
},
"move_word_forward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Move cursor to start of next word (`w`)."
},
"open_line_above": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open a new line above and enter insert mode (`O`)."
},
"open_line_below": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Open a new line below and enter insert mode (`o`)."
},
"paste_after": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Paste after cursor (`p`)."
},
"start_change_operator": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Begin change operator; next keys select a text object."
},
"start_delete_operator": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Begin delete operator; next key selects motion (`d`)."
},
"start_yank_operator": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Begin yank operator; next key selects motion (`y`)."
},
"substitute_char": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Delete character under cursor and enter insert mode (`s`)."
},
"yank_line": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Yank the entire line (`Y`)."
}
},
"type": "object"
},
"TuiVimOperatorKeymap": {
"additionalProperties": false,
"description": "Vim operator-pending keybindings for modal editing inside text areas.\n\nThis context is active only while waiting for a motion after `d` or `y`. Repeating the operator key (`dd`, `yy`) targets the entire line. Pressing `Esc` cancels the pending operator and returns to normal mode without modifying text.",
"properties": {
"cancel": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Cancel the pending operator and return to normal mode."
},
"delete_line": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Repeat delete operator to delete the whole line (`dd`)."
},
"motion_down": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: down one line (`j`)."
},
"motion_left": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: left (`h`)."
},
"motion_line_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: to end of line (`$`)."
},
"motion_line_start": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: to start of line (`0`)."
},
"motion_right": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: right (`l`)."
},
"motion_up": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: up one line (`k`)."
},
"motion_word_backward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: to start of previous word (`b`)."
},
"motion_word_end": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: to end of current/next word (`e`)."
},
"motion_word_forward": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Motion: to start of next word (`w`)."
},
"select_around_text_object": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Select an around text object after an operator."
},
"select_inner_text_object": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Select an inner text object after an operator."
},
"yank_line": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Repeat yank operator to yank the whole line (`yy`)."
}
},
"type": "object"
},
"TuiVimTextObjectKeymap": {
"additionalProperties": false,
"description": "Vim text-object keybindings for modal editing inside text areas.",
"properties": {
"backtick": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: backticks."
},
"big_word": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: whitespace-delimited WORD."
},
"braces": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: braces."
},
"brackets": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: brackets."
},
"cancel": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Cancel the pending text-object command."
},
"double_quote": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: double quotes."
},
"parentheses": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: parentheses."
},
"single_quote": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: single quotes."
},
"word": {
"allOf": [
{
"$ref": "#/definitions/KeybindingsSpec"
}
],
"description": "Text object: word."
}
},
"type": "object"
},
"UriBasedFileOpener": {
"oneOf": [
{
"enum": [
"vscode",
"vscode-insiders",
"windsurf",
"cursor"
],
"type": "string"
},
{
"description": "Option to disable the URI-based file opener.",
"enum": [
"none"
],
"type": "string"
}
]
},
"Verbosity": {
"description": "Controls output length/detail on GPT-5 models via the Responses API. Serialized with lowercase values to match the OpenAI API.",
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
"WebSearchContextSize": {
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
"WebSearchLocation": {
"additionalProperties": false,
"properties": {
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"region": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"type": "object"
},
"WebSearchMode": {
"enum": [
"disabled",
"cached",
"indexed",
"live"
],
"type": "string"
},
"WebSearchToolConfig": {
"additionalProperties": false,
"properties": {
"allowed_domains": {
"items": {
"type": "string"
},
"type": "array"
},
"context_size": {
"$ref": "#/definitions/WebSearchContextSize"
},
"location": {
"$ref": "#/definitions/WebSearchLocation"
}
},
"type": "object"
},
"WindowsSandboxModeToml": {
"enum": [
"elevated",
"unelevated"
],
"type": "string"
},
"WindowsToml": {
"additionalProperties": false,
"properties": {
"sandbox": {
"$ref": "#/definitions/WindowsSandboxModeToml"
},
"sandbox_private_desktop": {
"description": "Defaults to `true`. Set to `false` to launch the final sandboxed child process on `Winsta0\\\\Default` instead of a private desktop.",
"type": "boolean"
}
},
"type": "object"
},
"WireApi": {
"description": "Wire protocol that the provider speaks.",
"oneOf": [
{
"description": "The Responses API exposed by OpenAI at `/v1/responses`.",
"enum": [
"responses"
],
"type": "string"
}
]
},
"WorkspaceRootsToml": {
"type": "object"
}
},
"description": "Base config deserialized from ~/.codex/config.toml.",
"properties": {
"agents": {
"allOf": [
{
"$ref": "#/definitions/AgentsToml"
}
],
"description": "Agent-related settings (thread limits, etc.)."
},
"allow_login_shell": {
"description": "Whether the model may request a login shell for shell-based tools. Default to `true`\n\nIf `true`, the model may request a login shell (`login = true`), and omitting `login` defaults to using a login shell. If `false`, the model can never use a login shell: `login = true` requests are rejected, and omitting `login` defaults to a non-login shell.",
"type": "boolean"
},
"analytics": {
"allOf": [
{
"$ref": "#/definitions/AnalyticsConfigToml"
}
],
"description": "When `false`, disables analytics across Codex product surfaces in this machine. Defaults to `true`."
},
"approval_policy": {
"allOf": [
{
"$ref": "#/definitions/AskForApproval"
}
],
"description": "Default approval policy for executing commands."
},
"approvals_reviewer": {
"allOf": [
{
"$ref": "#/definitions/ApprovalsReviewer"
}
],
"description": "Configures who approval requests are routed to for review once they have been escalated. This does not disable separate safety checks such as ARC."
},
"apps": {
"allOf": [
{
"$ref": "#/definitions/AppsConfigToml"
}
],
"default": null,
"description": "Settings for app-specific controls."
},
"apps_mcp_product_sku": {
"description": "Optional product SKU forwarded on host-owned Codex Apps MCP requests.",
"type": "string"
},
"audio": {
"allOf": [
{
"$ref": "#/definitions/RealtimeAudioToml"
}
],
"default": null,
"description": "Machine-local realtime audio device preferences used by realtime voice."
},
"auto_review": {
"allOf": [
{
"$ref": "#/definitions/AutoReviewToml"
}
],
"default": null,
"description": "Optional policy instructions for the guardian auto-reviewer."
},
"background_terminal_max_timeout": {
"description": "Maximum poll window for background terminal output (`write_stdin`), in milliseconds. Default: `300000` (5 minutes).",
"format": "uint64",
"minimum": 0.0,
"type": "integer"
},
"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": {
"allOf": [
{
"$ref": "#/definitions/AuthCredentialsStoreMode"
}
],
"default": null,
"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."
},
"compact_prompt": {
"description": "Compact prompt used for history compaction.",
"type": "string"
},
"debug": {
"allOf": [
{
"$ref": "#/definitions/DebugToml"
}
],
"description": "Debugging and reproducibility settings."
},
"default_permissions": {
"description": "Default permissions profile to apply. Names starting with `:` refer to built-in profiles; other names are resolved from the `[permissions]` table.",
"type": "string"
},
"desktop": {
"additionalProperties": true,
"default": null,
"description": "Opaque desktop settings stored alongside the rest of config.toml.",
"type": "object"
},
"developer_instructions": {
"default": null,
"description": "Developer instructions inserted as a `developer` role message.",
"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_realtime_start_instructions": {
"description": "Experimental / do not use. Replaces the built-in realtime start instructions inserted into developer messages when realtime becomes active.",
"type": "string"
},
"experimental_realtime_webrtc_call_base_url": {
"description": "Experimental / do not use. Overrides only the WebRTC realtime call creation base URL. This is separate from `experimental_realtime_ws_base_url` because WebRTC call creation is HTTP, while sideband control is websocket.",
"type": "string"
},
"experimental_realtime_ws_backend_prompt": {
"description": "Experimental / do not use. Overrides only the realtime conversation websocket transport instructions (the `Op::RealtimeConversation` `/ws` session.update instructions) without changing normal prompts.",
"type": "string"
},
"experimental_realtime_ws_base_url": {
"description": "Experimental / do not use. Overrides only the realtime conversation websocket transport base URL (the `Op::RealtimeConversation` `/v1/realtime` connection) without changing normal provider HTTP requests.",
"type": "string"
},
"experimental_realtime_ws_model": {
"description": "Experimental / do not use. Selects the realtime websocket model/snapshot used for the `Op::RealtimeConversation` connection.",
"type": "string"
},
"experimental_realtime_ws_startup_context": {
"description": "Experimental / do not use. Replaces the synthesized realtime startup context appended to websocket session instructions. An empty string disables startup context injection entirely.",
"type": "string"
},
"experimental_thread_config_endpoint": {
"description": "Experimental / do not use. When set, app-server fetches thread-scoped config from a remote service at this endpoint.",
"type": "string"
},
"experimental_thread_store": {
"allOf": [
{
"$ref": "#/definitions/ThreadStoreToml"
}
],
"description": "Experimental / do not use. Selects the thread store implementation."
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"features": {
"additionalProperties": false,
"default": null,
"description": "Centralized feature flags (new). Prefer this over individual toggles.",
"properties": {
"apply_patch_freeform": {
"type": "boolean"
},
"apply_patch_streaming_events": {
"type": "boolean"
},
"apps": {
"type": "boolean"
},
"apps_mcp_path_override": {
"anyOf": [
{
"type": "boolean"
},
{
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"path": {
"type": "string"
}
},
"type": "object"
}
]
},
"auth_elicitation": {
"type": "boolean"
},
"browser_use": {
"type": "boolean"
},
"browser_use_external": {
"type": "boolean"
},
"browser_use_full_cdp_access": {
"type": "boolean"
},
"chronicle": {
"type": "boolean"
},
"code_mode": {
"$ref": "#/definitions/FeatureToml_for_CodeModeConfigToml"
},
"code_mode_buffered_exec": {
"type": "boolean"
},
"code_mode_host": {
"type": "boolean"
},
"code_mode_only": {
"type": "boolean"
},
"codex_git_commit": {
"type": "boolean"
},
"codex_hooks": {
"type": "boolean"
},
"collab": {
"type": "boolean"
},
"collaboration_modes": {
"type": "boolean"
},
"computer_use": {
"type": "boolean"
},
"concurrent_reasoning_summaries": {
"type": "boolean"
},
"connectors": {
"type": "boolean"
},
"current_time_reminder": {
"$ref": "#/definitions/FeatureToml_for_CurrentTimeReminderConfigToml"
},
"default_mode_request_user_input": {
"type": "boolean"
},
"deferred_executor": {
"type": "boolean"
},
"elevated_windows_sandbox": {
"type": "boolean"
},
"enable_experimental_windows_sandbox": {
"type": "boolean"
},
"enable_fanout": {
"type": "boolean"
},
"enable_mcp_apps": {
"type": "boolean"
},
"enable_request_compression": {
"type": "boolean"
},
"exec_permission_approvals": {
"type": "boolean"
},
"executor_capability_discovery": {
"type": "boolean"
},
"experimental_use_unified_exec_tool": {
"type": "boolean"
},
"experimental_windows_sandbox": {
"type": "boolean"
},
"external_agent_memory_import": {
"type": "boolean"
},
"external_migration": {
"type": "boolean"
},
"fast_mode": {
"type": "boolean"
},
"goals": {
"type": "boolean"
},
"guardian_approval": {
"type": "boolean"
},
"hooks": {
"type": "boolean"
},
"image_detail_original": {
"type": "boolean"
},
"image_generation": {
"type": "boolean"
},
"imagegenext": {
"type": "boolean"
},
"in_app_browser": {
"type": "boolean"
},
"item_ids": {
"type": "boolean"
},
"js_repl": {
"type": "boolean"
},
"js_repl_tools_only": {
"type": "boolean"
},
"local_thread_store_compression": {
"type": "boolean"
},
"memories": {
"type": "boolean"
},
"memory_tool": {
"type": "boolean"
},
"mentions_v2": {
"type": "boolean"
},
"multi_agent": {
"type": "boolean"
},
"multi_agent_mode": {
"type": "boolean"
},
"multi_agent_v2": {
"$ref": "#/definitions/FeatureToml_for_MultiAgentV2ConfigToml"
},
"network_proxy": {
"$ref": "#/definitions/FeatureToml_for_NetworkProxyConfigToml"
},
"non_prefixed_mcp_tool_names": {
"type": "boolean"
},
"personality": {
"type": "boolean"
},
"plugin_hooks": {
"type": "boolean"
},
"plugin_sharing": {
"type": "boolean"
},
"plugins": {
"type": "boolean"
},
"prevent_idle_sleep": {
"type": "boolean"
},
"realtime_conversation": {
"type": "boolean"
},
"remote_compaction_v2": {
"type": "boolean"
},
"remote_control": {
"type": "boolean"
},
"remote_models": {
"type": "boolean"
},
"remote_plugin": {
"type": "boolean"
},
"request_permissions": {
"type": "boolean"
},
"request_permissions_tool": {
"type": "boolean"
},
"request_rule": {
"type": "boolean"
},
"resize_all_images": {
"type": "boolean"
},
"respect_system_proxy": {
"type": "boolean"
},
"responses_websockets": {
"type": "boolean"
},
"responses_websockets_v2": {
"type": "boolean"
},
"rollout_budget": {
"$ref": "#/definitions/FeatureToml_for_RolloutBudgetConfigToml"
},
"runtime_metrics": {
"type": "boolean"
},
"search_tool": {
"type": "boolean"
},
"secret_auth_storage": {
"type": "boolean"
},
"shell_snapshot": {
"type": "boolean"
},
"shell_tool": {
"type": "boolean"
},
"shell_zsh_fork": {
"type": "boolean"
},
"skill_env_var_dependency_prompt": {
"type": "boolean"
},
"skill_mcp_dependency_install": {
"type": "boolean"
},
"skill_search": {
"type": "boolean"
},
"sqlite": {
"type": "boolean"
},
"standalone_web_search": {
"type": "boolean"
},
"steer": {
"type": "boolean"
},
"telepathy": {
"type": "boolean"
},
"terminal_resize_reflow": {
"type": "boolean"
},
"terminal_visualization_instructions": {
"type": "boolean"
},
"token_budget": {
"$ref": "#/definitions/FeatureToml_for_TokenBudgetConfigToml"
},
"tool_call_mcp_elicitation": {
"type": "boolean"
},
"tool_search": {
"type": "boolean"
},
"tool_search_always_defer_mcp_tools": {
"type": "boolean"
},
"tool_suggest": {
"type": "boolean"
},
"tui_app_server": {
"type": "boolean"
},
"unavailable_dummy_tools": {
"type": "boolean"
},
"undo": {
"type": "boolean"
},
"unified_exec": {
"type": "boolean"
},
"unified_exec_zsh_fork": {
"type": "boolean"
},
"use_agent_identity": {
"type": "boolean"
},
"use_legacy_landlock": {
"type": "boolean"
},
"use_linux_sandbox_bwrap": {
"type": "boolean"
},
"web_search": {
"type": "boolean"
},
"web_search_cached": {
"type": "boolean"
},
"web_search_request": {
"type": "boolean"
},
"workspace_dependencies": {
"type": "boolean"
},
"workspace_owner_usage_nudge": {
"type": "boolean"
}
},
"type": "object"
},
"feedback": {
"allOf": [
{
"$ref": "#/definitions/FeedbackConfigToml"
}
],
"description": "When `false`, disables feedback collection across Codex product surfaces. Defaults to `true`."
},
"file_opener": {
"allOf": [
{
"$ref": "#/definitions/UriBasedFileOpener"
}
],
"description": "Optional URI-based file opener. If set, citations to files in the model output will be hyperlinked using the specified URI scheme."
},
"forced_chatgpt_workspace_id": {
"allOf": [
{
"$ref": "#/definitions/ForcedChatgptWorkspaceIds"
}
],
"default": null,
"description": "When set, restricts ChatGPT login to one or more workspace identifiers."
},
"forced_login_method": {
"allOf": [
{
"$ref": "#/definitions/ForcedLoginMethod"
}
],
"default": null,
"description": "When set, restricts the login mechanism users may use."
},
"ghost_snapshot": {
"allOf": [
{
"$ref": "#/definitions/GhostSnapshotToml"
}
],
"default": null,
"description": "Compatibility-only settings retained so legacy `ghost_snapshot` config still loads."
},
"hide_agent_reasoning": {
"default": false,
"description": "When set to `true`, `AgentReasoning` events will be hidden from the UI/output. Defaults to `false`.",
"type": "boolean"
},
"history": {
"allOf": [
{
"$ref": "#/definitions/History"
}
],
"default": {
"max_bytes": null,
"persistence": "save-all"
},
"description": "Settings that govern if and what will be written to `~/.codex/history.jsonl`."
},
"hooks": {
"allOf": [
{
"$ref": "#/definitions/HooksToml"
}
],
"description": "Lifecycle hooks configured inline in TOML plus user-level overrides."
},
"include_apps_instructions": {
"description": "Whether to inject the `<apps_instructions>` developer block.",
"type": "boolean"
},
"include_collaboration_mode_instructions": {
"description": "Whether to inject the `<collaboration_mode>` developer block.",
"type": "boolean"
},
"include_environment_context": {
"description": "Whether to inject the `<environment_context>` user block.",
"type": "boolean"
},
"include_permissions_instructions": {
"description": "Whether to inject the `<permissions instructions>` developer block.",
"type": "boolean"
},
"instructions": {
"description": "System instructions.",
"type": "string"
},
"log_dir": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Directory where Codex writes log files. Setting this value explicitly also enables the TUI text log in this directory. Defaults to `$CODEX_HOME/log`."
},
"marketplaces": {
"additionalProperties": {
"$ref": "#/definitions/MarketplaceConfig"
},
"default": {},
"description": "User-level marketplace entries keyed by marketplace name.",
"type": "object"
},
"mcp_oauth_callback_port": {
"description": "Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex will bind to an ephemeral port chosen by the OS.",
"format": "uint16",
"minimum": 0.0,
"type": "integer"
},
"mcp_oauth_callback_url": {
"description": "Optional redirect URI to use during MCP OAuth login. When set, this URI is used in the OAuth authorization request instead of the local listener address. The local callback listener still binds to 127.0.0.1 (using `mcp_oauth_callback_port` when provided).",
"type": "string"
},
"mcp_oauth_credentials_store": {
"allOf": [
{
"$ref": "#/definitions/OAuthCredentialsStoreMode"
}
],
"default": null,
"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."
},
"mcp_servers": {
"additionalProperties": {
"$ref": "#/definitions/RawMcpServerConfig"
},
"default": {},
"description": "Definition for MCP servers that Codex can reach out to for tool calls.",
"type": "object"
},
"memories": {
"allOf": [
{
"$ref": "#/definitions/MemoriesToml"
}
],
"description": "Memories subsystem settings."
},
"model": {
"description": "Optional override of model selection.",
"type": "string"
},
"model_auto_compact_token_limit": {
"description": "Token usage threshold triggering auto-compaction of conversation history.",
"format": "int64",
"type": "integer"
},
"model_auto_compact_token_limit_scope": {
"allOf": [
{
"$ref": "#/definitions/AutoCompactTokenLimitScope"
}
],
"description": "Controls whether the auto-compaction limit applies to the full context or only to tokens after the carried prefix in the current compaction window."
},
"model_catalog_json": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a JSON model catalog (applied on startup only). Per-thread `config` overrides are accepted but do not reapply this (no-ops)."
},
"model_context_window": {
"description": "Size of the context window for the model, in tokens.",
"format": "int64",
"type": "integer"
},
"model_instructions_file": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Optional path to a file containing model instructions that will override the built-in instructions for the selected model. Users are STRONGLY DISCOURAGED from using this field, as deviating from the instructions sanctioned by Codex will likely degrade model performance."
},
"model_provider": {
"description": "Provider to use from the model_providers map.",
"type": "string"
},
"model_providers": {
"additionalProperties": {
"$ref": "#/definitions/ModelProviderInfo"
},
"default": {},
"description": "User-defined provider entries that extend the built-in list. Built-in IDs cannot be overridden.",
"type": "object"
},
"model_reasoning_effort": {
"$ref": "#/definitions/ReasoningEffort"
},
"model_reasoning_summary": {
"$ref": "#/definitions/ReasoningSummary"
},
"model_verbosity": {
"allOf": [
{
"$ref": "#/definitions/Verbosity"
}
],
"description": "Optional verbosity control for GPT-5 models (Responses API `text.verbosity`)."
},
"notice": {
"allOf": [
{
"$ref": "#/definitions/Notice"
}
],
"description": "Collection of in-product notices (different from notifications) See [`crate::types::Notice`] for more details"
},
"notify": {
"default": null,
"description": "Optional external command to spawn for end-user notifications.",
"items": {
"type": "string"
},
"type": "array"
},
"openai_base_url": {
"description": "Base URL override for the built-in `openai` model provider.",
"type": "string"
},
"orchestrator": {
"allOf": [
{
"$ref": "#/definitions/OrchestratorToml"
}
],
"description": "Orchestrator-owned feature settings."
},
"oss_provider": {
"description": "Preferred OSS provider for local models, e.g. \"lmstudio\" or \"ollama\".",
"type": "string"
},
"otel": {
"allOf": [
{
"$ref": "#/definitions/OtelConfigToml"
}
],
"description": "OTEL configuration."
},
"permissions": {
"allOf": [
{
"$ref": "#/definitions/PermissionsToml"
}
],
"default": null,
"description": "Named permissions profiles."
},
"personality": {
"allOf": [
{
"$ref": "#/definitions/Personality"
}
],
"description": "Optionally specify a personality for the model"
},
"plan_mode_reasoning_effort": {
"$ref": "#/definitions/ReasoningEffort"
},
"plugins": {
"additionalProperties": {
"$ref": "#/definitions/PluginConfig"
},
"default": {},
"description": "User-level plugin config entries keyed by plugin name.",
"type": "object"
},
"profile": {
"description": "Profile to use from the `profiles` map.",
"type": "string"
},
"profiles": {
"additionalProperties": {
"$ref": "#/definitions/ConfigProfile"
},
"default": {},
"description": "Named profiles to facilitate switching between different configurations.",
"type": "object"
},
"project_doc_fallback_filenames": {
"default": [],
"description": "Ordered list of fallback filenames to look for when AGENTS.md is missing.",
"items": {
"type": "string"
},
"type": "array"
},
"project_doc_max_bytes": {
"default": 32768,
"description": "Maximum number of bytes to include from an AGENTS.md project doc file.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"project_root_markers": {
"default": null,
"description": "Markers used to detect the project root when searching parent directories for `.codex` folders. Defaults to [\".git\"] when unset.",
"items": {
"type": "string"
},
"type": "array"
},
"projects": {
"additionalProperties": {
"$ref": "#/definitions/ProjectConfig"
},
"type": "object"
},
"realtime": {
"allOf": [
{
"$ref": "#/definitions/RealtimeToml"
}
],
"default": null,
"description": "Experimental / do not use. Realtime websocket session selection. `version` controls v1/v2 and `type` controls conversational/transcription."
},
"review_model": {
"description": "Review model override used by the `/review` feature.",
"type": "string"
},
"sandbox_mode": {
"allOf": [
{
"$ref": "#/definitions/SandboxMode"
}
],
"description": "Sandbox mode to use."
},
"sandbox_workspace_write": {
"allOf": [
{
"$ref": "#/definitions/SandboxWorkspaceWrite"
}
],
"description": "Sandbox configuration to apply if `sandbox` is `WorkspaceWrite`."
},
"service_tier": {
"description": "Optional explicit service tier request id for new turns (for example `default`, `priority`, or `flex`; legacy `fast` also works).",
"type": "string"
},
"shell_environment_policy": {
"allOf": [
{
"$ref": "#/definitions/ShellEnvironmentPolicyToml"
}
],
"default": {
"exclude": null,
"experimental_use_profile": null,
"filters": null,
"ignore_default_excludes": null,
"include_only": null,
"inherit": null,
"set": null
}
},
"show_raw_agent_reasoning": {
"description": "When set to `true`, `AgentReasoningRawContentEvent` events will be shown in the UI/output. Defaults to `false`.",
"type": "boolean"
},
"skills": {
"allOf": [
{
"$ref": "#/definitions/SkillsConfig"
}
],
"description": "User-level skill config entries keyed by SKILL.md path."
},
"sqlite_home": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Directory where Codex stores the SQLite state DB. Defaults to `$CODEX_SQLITE_HOME` when set. Otherwise uses `$CODEX_HOME`."
},
"suppress_unstable_features_warning": {
"description": "Suppress warnings about unstable (under development) features.",
"type": "boolean"
},
"tool_output_token_limit": {
"description": "Token budget applied when storing tool/function outputs in the context manager.",
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"tool_suggest": {
"allOf": [
{
"$ref": "#/definitions/ToolSuggestConfig"
}
],
"description": "Additional discoverable tools that can be suggested for installation."
},
"tools": {
"allOf": [
{
"$ref": "#/definitions/ToolsToml"
}
],
"description": "Nested tools section for feature toggles"
},
"tui": {
"allOf": [
{
"$ref": "#/definitions/Tui"
}
],
"description": "Collection of settings that are specific to the TUI."
},
"web_search": {
"allOf": [
{
"$ref": "#/definitions/WebSearchMode"
}
],
"description": "Controls the web search tool mode: disabled, cached, indexed, or live."
},
"windows": {
"allOf": [
{
"$ref": "#/definitions/WindowsToml"
}
],
"default": null,
"description": "Windows-specific configuration."
}
},
"title": "ConfigToml",
"type": "object"
}