Skip to content

shell-tool-settings

Generated from plugins/shell-tool-settings/README.md.

Opt-in settings plugin that exposes the agent/session config key shell_tool_mode in the session settings UI.

The plugin contributes a single select setting (shell_tool_mode, default auto) and has no behavior of its own: the shell tools in codex-tools consume the key from the merged agent/session configuration. It is not referenced by the default configuration — load it explicitly when you want the setting.

What the setting does

Value Shell tool surface
auto (default) exec_command + write_stdin (unified exec) — for every model, matching current upstream Codex
exec_command exec_command + write_stdin (explicit)
shell_command Legacy string-command tool (removed upstream 2026-08-20; kept as an opt-in escape hatch)
shell Legacy array tool (removed upstream 2026-05-13; kept as an opt-in escape hatch)

Usage

Enable per agent by loading the plugin and setting the key in the agent definition:

{
  "plugins": [
    "path:${env:BUILTIN_PLUGINS}/codex-tools",
    "path:${env:BUILTIN_PLUGINS}/shell-tool-settings"
  ],
  "agents": {
    "my-agent": {
      "provider": "openai",
      "model": "gpt-6.1-sol",
      "shell_tool_mode": "shell_command"
    }
  }
}

Or set it per session in the session settings (terminal /set shell_tool_mode shell_command, or the chips in the mobile/desktop session settings). The value is stored as a session override and takes effect on the next request in that session — no restart. Resetting the override returns the session to the agent default.

Tests

pytest plugins/shell-tool-settings/tests -q