{ "id": "codex-cli", "name": "Codex CLI", "vendor": "OpenAI", "tagline": "Use Codex from your terminal and scripts — OpenAI's agentic coding CLI.", "subtitle": "terminal reference", "docsHome": "https://developers.openai.com/codex", "version": "0.144.1", "lastVerified": "2026-07-11", "stale": false, "accent": "#5fb88f", "headerNote": "Things move fast — the source of truth is [developers.openai.com/codex](https://developers.openai.com/codex), and inside a session `/status` shows the active model, approval policy, and writable roots of *your* build.", "footerNote": "The docs label commands Experimental, Beta, and Stable; run `codex features` to see which optional capabilities your build has on.", "tagVocabulary": [ { "tag": "exp", "label": "experimental", "desc": "marked experimental in the docs — may change without notice." }, { "tag": "win", "label": "windows", "desc": "only when running natively on Windows." }, { "tag": "dep", "label": "deprecated", "desc": "kept for compatibility; prefer the replacement." } ], "sections": [ { "id": "launch", "title": "Launch", "showTagLegend": true, "sources": [ "https://developers.openai.com/codex/cli/reference.md", "https://developers.openai.com/codex/non-interactive-mode.md" ], "groups": [ { "title": "Sessions", "rows": [ { "cmd": "codex", "desc": "Launch the interactive terminal UI. On launch Codex recommends *Auto* in version-controlled folders, `read-only` elsewhere." }, { "cmd": "codex \"prompt\"", "desc": "Start the TUI with an opening instruction pre-filled." }, { "cmd": "codex resume [--last | --all]", "desc": "Continue an interactive session by ID, or the most recent. `--last` scopes to the current directory unless `--all`." }, { "cmd": "codex fork [--last]", "desc": "Fork a previous session into a new task; no flag opens the session picker. Original transcript preserved." }, { "cmd": "codex archive | unarchive ", "desc": "Hide a session from the picker without deleting the transcript / restore it. IDs take precedence over names." }, { "cmd": "codex delete [--force]", "desc": "Permanently delete a saved session. `--force` only works with a UUID; named sessions always confirm.", "danger": true }, { "cmd": "codex login | logout", "desc": "ChatGPT OAuth by default; also API key or piped access token. `codex login status` exits 0 when credentials are present." }, { "cmd": "codex update", "desc": "Check for and apply a self-update when the installed release supports it." }, { "cmd": "codex doctor", "desc": "Diagnostic report: installation, config, auth, runtime, Git, terminal, app-server, thread inventory." } ] }, { "title": "Scripting (codex exec)", "rows": [ { "cmd": "codex exec \"task\"", "desc": "Non-interactive run (alias `codex e`). Progress streams to stderr; only the final message prints to stdout. Read-only sandbox by default." }, { "cmd": "npm test 2>&1 | codex exec \"task\"", "desc": "Prompt-plus-stdin: the argument is the instruction, piped content is context." }, { "cmd": "codex exec -", "desc": "Read the entire prompt from stdin — for prompts assembled by scripts." }, { "cmd": "codex exec resume --last [--all]", "desc": "Continue a non-interactive session; `--all` searches beyond the current directory. Also takes a session ID." }, { "cmd": "codex review --uncommitted | --base | --commit ", "desc": "Non-interactive code review. Targets conflict with each other and with a custom prompt; `--title` only with `--commit`." }, { "cmd": "codex apply ", "desc": "Apply the latest diff from a Codex cloud task to the local repo (alias `codex a`). Non-zero exit if `git apply` fails." }, { "cmd": "codex cloud [exec | list]", "desc": "Browse cloud tasks (picker), submit one directly, or list recent tasks — `--json` for automation.", "tags": ["exp"] } ] }, { "title": "Setup & plumbing", "rows": [ { "cmd": "codex mcp", "desc": "Manage MCP server entries in `~/.codex/config.toml`. `codex mcp login ` runs an OAuth flow for HTTP servers." }, { "cmd": "codex plugin [marketplace]", "desc": "Install, list, and remove plugins; manage marketplace sources (GitHub shorthand, Git URLs, local roots). `--json` throughout." }, { "cmd": "codex features [enable | disable ]", "desc": "List feature flags or persist a toggle in `config.toml`." }, { "cmd": "codex completion bash|zsh|fish|powershell", "desc": "Generate a shell completion script, e.g. `eval \"$(codex completion zsh)\"`." }, { "cmd": "codex sandbox macos|linux|windows [cmd]", "desc": "Run any command under the same sandbox policies Codex uses internally. Also available as `codex debug`." }, { "cmd": "codex execpolicy check --rules ", "desc": "Test how `.rules` files judge a command before saving them. `--pretty` formats the JSON.", "tags": ["exp"] }, { "cmd": "codex mcp-server", "desc": "Run Codex itself as an MCP server over stdio, so another agent can drive it." }, { "cmd": "codex app", "desc": "Open the session in the ChatGPT desktop app (macOS opens the workspace path; Windows prints it)." }, { "cmd": "codex app-server [--listen ws://IP:PORT]", "desc": "Local app server for protocol clients — stdio, WebSocket, or Unix socket transports.", "tags": ["exp"] }, { "cmd": "codex remote-control [start | stop | pair]", "desc": "Remote-control daemon for managed clients and SSH workflows; `pair` prints a short-lived pairing code.", "tags": ["exp"] } ] } ] }, { "id": "flags", "title": "CLI flags", "lede": "Global flags apply to `codex` and propagate to most subcommands. `-c key=value` overrides any config value for one invocation.", "sources": [ "https://developers.openai.com/codex/cli/reference.md", "https://developers.openai.com/codex/codex-manual.md", "https://developers.openai.com/codex/non-interactive-mode.md" ], "groups": [ { "title": "Global", "rows": [ { "cmd": "--model, -m ", "desc": "Override the configured model (for example `gpt-5.4`)." }, { "cmd": "--sandbox, -s read-only|workspace-write|danger-full-access", "desc": "Sandbox policy for model-generated shell commands." }, { "cmd": "--ask-for-approval, -a untrusted|on-request|never", "desc": "When Codex pauses for human approval before running a command." }, { "cmd": "--cd, -C ", "desc": "Set the agent's working directory before it starts." }, { "cmd": "--add-dir ", "desc": "Grant extra directories write access alongside the workspace. Repeatable." }, { "cmd": "--config, -c key=value", "desc": "One-off config override; values parse as TOML when possible." }, { "cmd": "--profile, -p ", "desc": "Layer `~/.codex/.config.toml` on top of the base user config." }, { "cmd": "--image, -i ", "desc": "Attach image files to the initial prompt." }, { "cmd": "--search", "desc": "Live web search (`web_search = \"live\"`) instead of the default cached index." }, { "cmd": "--oss | --local-provider lmstudio|ollama", "desc": "Use a local open-source model provider; `--local-provider` picks which one for this run." }, { "cmd": "--enable / --disable ", "desc": "Force a feature flag on or off (translates to `-c features.`). Repeatable." }, { "cmd": "--remote ws://host:port | unix://[PATH]", "desc": "Connect the TUI to an app server. Works with `codex`, `resume`, `fork`, `archive`, `delete`, `unarchive`." }, { "cmd": "--remote-auth-token-env ", "desc": "Bearer token for `--remote`; only sent over `wss://` or local-only `ws://` URLs." }, { "cmd": "--strict-config", "desc": "Error when `config.toml` contains fields this Codex version doesn't recognize." }, { "cmd": "--no-alt-screen", "desc": "Disable the TUI alternate screen for this run (overrides `tui.alternate_screen`)." }, { "cmd": "--dangerously-bypass-approvals-and-sandbox, --yolo", "desc": "No approvals, no sandbox. Only inside an externally hardened environment.", "danger": true }, { "cmd": "--dangerously-bypass-hook-trust", "desc": "Run enabled hooks without persisted trust — only for automation that already vets hook sources.", "danger": true } ] }, { "title": "codex exec (scripting)", "rows": [ { "cmd": "--json", "desc": "stdout becomes a JSONL event stream: `thread.started`, `turn.completed`, `item.*`, `error`, …" }, { "cmd": "--output-last-message, -o ", "desc": "Also write the final message to a file — pair with `--json` in CI." }, { "cmd": "--output-schema ", "desc": "Force the final response to conform to a JSON Schema. For pipelines that need stable fields." }, { "cmd": "--ephemeral", "desc": "Don't persist session rollout files to disk." }, { "cmd": "--skip-git-repo-check", "desc": "Run outside a Git repository. Codex requires one by default to prevent destructive changes." }, { "cmd": "--ignore-user-config | --ignore-rules", "desc": "Skip `$CODEX_HOME/config.toml` / skip user and project `.rules` files for controlled automation." }, { "cmd": "--full-auto", "desc": "Compatibility alias that warns; use `--sandbox workspace-write` in new scripts.", "tags": ["dep"] }, { "cmd": "CODEX_API_KEY= codex exec …", "desc": "API key for a single non-interactive run. Set inline, never job-wide where untrusted code runs." } ] } ] }, { "id": "slash", "title": "Slash commands", "navLabel": "Slash commands", "lede": "Type `/` in the composer to open the popup. While a task runs, type a slash command and press Tab to queue it for the next turn.", "sources": ["https://developers.openai.com/codex/cli/slash-commands.md"], "groups": [ { "title": "Session & tasks", "rows": [ { "cmd": "/clear", "desc": "Clear the terminal and start a fresh task together. (Ctrl+L clears only the view.)" }, { "cmd": "/new", "desc": "New conversation in the same CLI session, without clearing the terminal first." }, { "cmd": "/resume", "desc": "Reload a saved conversation from the session picker; original history intact." }, { "cmd": "/fork", "desc": "Clone the current task into a new task ID to explore an alternative. (`codex fork` forks a *saved* session.)" }, { "cmd": "/side | /btw", "desc": "Ephemeral side conversation with its own transcript; the parent task's status stays visible. Unavailable inside another side chat." }, { "cmd": "/rename [name]", "desc": "Name the saved task without changing its transcript." }, { "cmd": "/compact", "desc": "Summarize the conversation to free context, keeping key points." }, { "cmd": "/copy", "desc": "Copy the latest *completed* output — also Ctrl+O." }, { "cmd": "/diff", "desc": "Show the Git diff, including files Git isn't tracking yet." }, { "cmd": "/archive", "desc": "Archive the current session and exit; restore later with `codex unarchive`." }, { "cmd": "/delete", "desc": "Permanently delete the current session and its descendant sessions, then exit.", "danger": true }, { "cmd": "/app", "desc": "Continue this session in the ChatGPT desktop app (macOS/Windows)." }, { "cmd": "/quit | /exit", "desc": "Exit immediately. Save or commit important work first." } ] }, { "title": "Model & steering", "rows": [ { "cmd": "/model", "desc": "Choose the active model and, when available, reasoning effort." }, { "cmd": "/fast", "desc": "Toggle the model's Fast service tier and persist the choice. Hidden if the catalog has none." }, { "cmd": "/personality", "desc": "Communication style: `friendly`, `pragmatic`, or `none`." }, { "cmd": "/plan [prompt]", "desc": "Switch to plan mode, optionally seeding the first planning request. Unavailable mid-task." }, { "cmd": "/goal [objective | edit | pause | resume | clear]", "desc": "Persistent target Codex tracks across the task. Max 4,000 chars — point at a file for more." }, { "cmd": "/permissions", "desc": "Switch approval preset (for example *Auto* ↔ *Read Only*), including named custom profiles." }, { "cmd": "/approve", "desc": "Retry a recent action that the automatic reviewer denied — once." }, { "cmd": "/review", "desc": "Review the working tree: behavior changes and missing tests. Uses `review_model` if set." }, { "cmd": "/status", "desc": "Active model, approval policy, writable roots, token usage — plus remote address when connected remotely." }, { "cmd": "/usage [daily | weekly | cumulative]", "desc": "Account token activity, or redeem an earned rate-limit reset." } ] }, { "title": "Context & extensions", "rows": [ { "cmd": "/mention ", "desc": "Attach a file so follow-up turns reference it directly." }, { "cmd": "/ide", "desc": "Pull open files and the current selection from your IDE into the next prompt." }, { "cmd": "/skills", "desc": "Browse and apply skills; you can also mention one inline with `$skill-name`." }, { "cmd": "/mcp [verbose]", "desc": "List configured MCP servers and tools; `verbose` adds server diagnostics." }, { "cmd": "/apps", "desc": "Browse apps (connectors) and insert one into the prompt as `$app-slug`." }, { "cmd": "/plugins", "desc": "Plugin browser: installed and discoverable plugins. Space toggles an installed plugin." }, { "cmd": "/hooks", "desc": "Inspect, trust, or disable lifecycle hooks. New or changed hooks are skipped until trusted." }, { "cmd": "/agent | /subagents", "desc": "Switch the active agent thread to inspect or continue a subagent's work." }, { "cmd": "/memories", "desc": "Toggle memory injection and generation without leaving the TUI." }, { "cmd": "/init", "desc": "Generate an `AGENTS.md` scaffold in the current directory." }, { "cmd": "/import", "desc": "Migrate Claude Code setup, project files, and recent chats into Codex. Local TUI sessions only." } ] }, { "title": "TUI & misc", "rows": [ { "cmd": "/statusline", "desc": "Pick and reorder footer items (model, context, limits, git, tokens, session); persists to `tui.status_line`." }, { "cmd": "/title", "desc": "Configure terminal window/tab title items; persists to `tui.terminal_title`." }, { "cmd": "/theme", "desc": "Syntax-highlighting theme picker; persists to `tui.theme`. Custom `.tmTheme` files go in `$CODEX_HOME/themes`." }, { "cmd": "/keymap", "desc": "Remap TUI shortcuts; writes to `tui.keymap`. Names like `ctrl-a`, `shift-enter`, `page-down`." }, { "cmd": "/vim", "desc": "Toggle composer Vim mode. Default it with `tui.vim_mode_default = true`." }, { "cmd": "/raw [on|off]", "desc": "Raw scrollback for cleaner terminal selection — also Alt+R; persist with `tui.raw_output_mode`." }, { "cmd": "/ps", "desc": "Background terminals with up to three recent output lines each." }, { "cmd": "/stop", "desc": "Stop all background terminals for this session. `/clean` is an alias." }, { "cmd": "/experimental", "desc": "Toggle experimental features (Network proxy, Prevent sleep, …); some need a restart." }, { "cmd": "/debug-config", "desc": "Config layer order, on/off state, and policy sources — for debugging precedence." }, { "cmd": "/setup-default-sandbox", "desc": "Replace the degraded restricted-token sandbox with the elevated one.", "tags": ["win"] }, { "cmd": "/sandbox-add-read-dir ", "desc": "Grant sandbox read access to an absolute directory outside the readable roots.", "tags": ["win"] }, { "cmd": "/feedback", "desc": "Send logs and diagnostics to the Codex maintainers." }, { "cmd": "/logout", "desc": "Clear local credentials." } ] } ] }, { "id": "keys", "title": "Keyboard & composer", "navLabel": "Keyboard", "sources": [ "https://developers.openai.com/codex/cli/reference.md", "https://developers.openai.com/codex/cli-customization.md" ], "groups": [ { "rows": [ { "cmd": "@", "desc": "Search for a workspace file and add its path to the prompt." }, { "cmd": "!", "desc": "Prefix a line to run a shell command under the current approval and sandbox settings." }, { "cmd": "$", "desc": "Mention a skill (`$skill-name`) or an app (`$app-slug`) inline." }, { "cmd": "Tab", "desc": "While Codex works: queue a follow-up prompt, slash command, or shell command for the next turn." }, { "cmd": "Enter", "desc": "While Codex works: inject new instructions into the *current* turn." }, { "cmd": "Up / Down", "desc": "Restore draft history." }, { "cmd": "Ctrl+R", "desc": "Search prompt history; Enter uses a match, Esc cancels." }, { "cmd": "Esc Esc", "desc": "On an empty composer: edit the previous user message and fork the conversation from that point." }, { "cmd": "Ctrl+O", "desc": "Copy the latest completed output (same as `/copy`)." }, { "cmd": "Ctrl+G", "desc": "Open the composer in the editor from `VISUAL` (or `EDITOR`); save and close to return the text." }, { "cmd": "Ctrl+L", "desc": "Clear the terminal view, keeping the current task. Disabled while a task runs." }, { "cmd": "Alt+R", "desc": "Toggle raw scrollback mode (default binding for `/raw`)." }, { "cmd": "Ctrl+C", "desc": "Close the session (same as `/exit`)." } ] } ] }, { "id": "sandbox", "title": "Sandbox & approvals", "navLabel": "Sandbox", "lede": "Two layers that work together: the sandbox is what commands *can* do; the approval policy is when Codex must stop and ask first.", "sources": [ "https://developers.openai.com/codex/sandboxing.md", "https://developers.openai.com/codex/agent-approvals-security.md" ], "groups": [ { "title": "Sandbox modes (--sandbox / sandbox_mode)", "rows": [ { "cmd": "read-only", "desc": "Inspect files only; edits and commands need approval." }, { "cmd": "workspace-write", "desc": "Read, edit, and run routine commands inside the workspace. The default low-friction mode for local work." }, { "cmd": "danger-full-access", "desc": "No filesystem or network boundaries. Only when the outer environment provides the isolation.", "danger": true } ] }, { "title": "Approval policies (--ask-for-approval / approval_policy)", "rows": [ { "cmd": "untrusted", "desc": "Only known-safe read operations run automatically; anything that can mutate state asks first." }, { "cmd": "on-request", "desc": "Work inside the sandbox freely; ask when going beyond the boundary." }, { "cmd": "never", "desc": "No approval prompts; Codex does its best within the sandbox you set." }, { "cmd": "approvals_reviewer = \"user\" | \"auto_review\"", "desc": "Who reviews eligible approval requests: you (default), or a reviewer agent that fails closed on parse errors and timeouts." }, { "cmd": "approval_policy = { granular = { … } }", "desc": "Keep some prompt categories interactive and auto-reject the rest: sandbox, rules, MCP, `request_permissions`, skill scripts." } ] }, { "title": "Common combinations", "rows": [ { "cmd": "--sandbox workspace-write --ask-for-approval on-request", "desc": "The *Auto* preset (also the default in version-controlled folders): edit and run in the workspace, ask to go outside or use the network." }, { "cmd": "--sandbox read-only --ask-for-approval on-request", "desc": "Safe browsing: read and answer; ask before any edit, command, or network access." }, { "cmd": "--sandbox read-only --ask-for-approval never", "desc": "Read-only non-interactive — the CI default posture." }, { "cmd": "--sandbox workspace-write --ask-for-approval untrusted", "desc": "Edit automatically but ask before running untrusted commands." }, { "cmd": "--yolo", "desc": "No sandbox, no approvals — not recommended outside a hardened container.", "danger": true } ] }, { "title": "Boundaries", "rows": [ { "cmd": ".git · .agents · .codex", "desc": "Protected read-only inside writable roots, recursively — even in `workspace-write`." }, { "cmd": "workspace = cwd + /tmp", "desc": "The workspace includes the current directory and temp directories; `/status` lists the writable roots." }, { "cmd": "[sandbox_workspace_write] network_access = true", "desc": "Network is *off* by default in `workspace-write`; this turns it on." }, { "cmd": "[features.network_proxy] domains = { \"api.openai.com\" = \"allow\" }", "desc": "Constrain enabled network access to a destination policy. `deny` beats `allow`; `*.host` excludes the apex, `**.host` includes it." }, { "cmd": "web_search = \"cached\" | \"indexed\" | \"live\" | \"disabled\"", "desc": "Web search without giving commands the network. Cached (default) serves an OpenAI-maintained index; `--search` = live." }, { "cmd": "sudo apt install bubblewrap", "desc": "Linux/WSL2 prerequisite — the sandbox uses `bwrap` + `seccomp`. macOS uses Seatbelt; native Windows has its own sandbox." } ] } ] }, { "id": "config", "title": "Config & environment", "navLabel": "Config", "lede": "Precedence, highest first: CLI flags and `-c` overrides → project `.codex/config.toml` (trusted projects, closest wins) → `--profile` file → `~/.codex/config.toml` → `/etc/codex/config.toml`.", "sources": [ "https://developers.openai.com/codex/config-file/config-basic.md", "https://developers.openai.com/codex/config-file/environment-variables.md" ], "groups": [ { "title": "config.toml keys people actually change", "rows": [ { "cmd": "model = \"gpt-5.6\"", "desc": "Default model for the CLI and IDE extension." }, { "cmd": "approval_policy = \"on-request\"", "desc": "When Codex pauses to ask before running generated commands." }, { "cmd": "sandbox_mode = \"workspace-write\"", "desc": "Filesystem and network access while executing commands." }, { "cmd": "model_reasoning_effort = \"high\"", "desc": "Reasoning effort where the model supports it." }, { "cmd": "personality = \"friendly\"", "desc": "Default communication style (`pragmatic`, `none`); override per session with `/personality`." }, { "cmd": "[features]", "desc": "Optional capabilities: `memories`, `multi_agent`, `hooks`, `fast_mode`, `unified_exec`, … Enable from the CLI with `codex --enable `." }, { "cmd": "[tui.keymap.global]", "desc": "Custom shortcut bindings; composer/chat contexts override global. Empty list unbinds." }, { "cmd": "[shell_environment_policy] include_only = [\"PATH\", \"HOME\"]", "desc": "Which environment variables Codex forwards to spawned commands." }, { "cmd": "log_dir = \"/path\"", "desc": "Where local logs go; setting it also enables the opt-in plaintext `codex-tui.log`." }, { "cmd": "[windows] sandbox = \"elevated\"", "desc": "Native Windows sandbox mode; `unelevated` only without admin permissions.", "tags": ["win"] } ] }, { "title": "Environment variables", "rows": [ { "cmd": "CODEX_HOME", "desc": "Root for Codex state — config, auth, logs, sessions, skills. Default `~/.codex`; must exist if set." }, { "cmd": "CODEX_API_KEY", "desc": "API key for a single `codex exec` run — only supported there." }, { "cmd": "CODEX_ACCESS_TOKEN", "desc": "ChatGPT/Codex access token for trusted automation; persist with `codex login --with-access-token`." }, { "cmd": "CODEX_CA_CERTIFICATE", "desc": "PEM CA bundle for corporate TLS interception; beats `SSL_CERT_FILE`." }, { "cmd": "RUST_LOG=debug", "desc": "Rust log filtering (`error` … `trace`, or targeted filters like `codex_core=debug`)." }, { "cmd": "CODEX_NON_INTERACTIVE=1", "desc": "Skip installer prompts in the standalone install scripts — for scripted installs." }, { "cmd": "CODEX_INSTALL_DIR", "desc": "Where the visible `codex` command lands (default `~/.local/bin` on macOS/Linux)." } ] } ] }, { "id": "mcp", "title": "MCP", "lede": "The ChatGPT desktop app, Codex CLI, and IDE extension share MCP configuration — set a server up once in `config.toml`.", "sources": ["https://developers.openai.com/codex/extend/mcp.md"], "groups": [ { "rows": [ { "cmd": "[mcp_servers.]", "desc": "One table per server in `~/.codex/config.toml`, or project-scoped `.codex/config.toml` (trusted projects)." }, { "cmd": "command / args / env / cwd", "desc": "STDIO server: launched as a local process. `env_vars` allowlists which variables are forwarded." }, { "cmd": "url / bearer_token_env_var / http_headers", "desc": "Streamable HTTP server. `auth = \"oauth\"` (default) uses stored MCP OAuth credentials; `\"chatgpt\"` rides the ChatGPT session." }, { "cmd": "codex mcp login ", "desc": "Run the OAuth flow for an HTTP server from the shell." }, { "cmd": "enabled_tools / disabled_tools", "desc": "Tool allow list, then deny list applied after it." }, { "cmd": "default_tools_approval_mode = auto|prompt|writes|approve", "desc": "Approval behavior for the server's tools; `writes` prompts for tools not marked read-only. Per-tool: `tools..approval_mode`." }, { "cmd": "required = true", "desc": "Startup fails if this enabled server can't initialize — `codex exec` exits with an error instead of continuing without it." }, { "cmd": "startup_timeout_sec = 10 · tool_timeout_sec = 60", "desc": "Server start and per-tool timeouts (defaults shown)." }, { "cmd": "mcp_oauth_callback_port / mcp_oauth_callback_url", "desc": "Fixed OAuth callback port or base URL when the provider needs one; Codex appends a server-specific callback ID." }, { "cmd": "enabled = false", "desc": "Disable a server without deleting its config." } ] } ] }, { "id": "guidance", "title": "AGENTS.md, skills & rules", "navLabel": "Guidance", "sources": [ "https://developers.openai.com/codex/agent-configuration/agents-md.md", "https://developers.openai.com/codex/build-skills.md", "https://developers.openai.com/codex/agent-configuration/rules.md" ], "groups": [ { "title": "AGENTS.md (read before any work)", "rows": [ { "cmd": "~/.codex/AGENTS.md", "desc": "Global guidance for every repository. `AGENTS.override.md` beside it wins when present." }, { "cmd": "/AGENTS.md … /AGENTS.md", "desc": "Project scope: walks root → cwd, at most one file per directory, concatenated root-down so closer files override." }, { "cmd": "project_doc_max_bytes = 32768", "desc": "Combined size cap (default 32 KiB) — raise it or split guidance across nested directories." }, { "cmd": "project_doc_fallback_filenames = [\"TEAM_GUIDE.md\"]", "desc": "Treat existing files as instruction files without renaming them." } ] }, { "title": "Skills", "rows": [ { "cmd": ".agents/skills//SKILL.md", "desc": "Repo skills — scanned from cwd up to the repo root. `name` + `description` required; description drives implicit matching." }, { "cmd": "~/.agents/skills · /etc/codex/skills", "desc": "User-wide and machine-wide (admin) skill locations. System skills ship with Codex." }, { "cmd": "$skill-name | /skills", "desc": "Explicit invocation — mention with `$` or pick from the browser. Codex also matches skills implicitly by description." }, { "cmd": "$skill-creator · $skill-installer ", "desc": "Draft a new skill interactively / install curated skills (e.g. `$skill-installer linear`)." }, { "cmd": "[[skills.config]] enabled = false", "desc": "Disable a skill by path without deleting it. Restart Codex after editing." }, { "cmd": "agents/openai.yaml", "desc": "Optional skill metadata: display name, icons, tool dependencies, `allow_implicit_invocation: false` to require explicit `$` calls." } ] }, { "title": "Rules (commands outside the sandbox)", "rows": [ { "cmd": "~/.codex/rules/*.rules", "desc": "Starlark files scanned at startup from every active config layer. Project rules load only in trusted projects.", "tags": ["exp"] }, { "cmd": "prefix_rule(pattern=[\"gh\",\"pr\",\"view\"], decision=\"prompt\")", "desc": "Match a command prefix; decide `allow`, `prompt`, or `forbidden`. Most restrictive matching rule wins." }, { "cmd": "match / not_match", "desc": "Inline unit tests validated when rules load — catch mistakes before a rule takes effect." }, { "cmd": "bash -lc \"a && b\"", "desc": "Simple chains are split and each command is judged separately, so `rm -rf /` can't ride along with `git add`. Complex scripts are judged whole." }, { "cmd": "codex execpolicy check --pretty --rules -- ", "desc": "Dry-run the decision for a command, with matching rules and justifications." } ] } ] }, { "id": "agents", "title": "Subagents", "lede": "Ask directly — \"spawn one agent per point, wait for all, summarize\" — or let project and skill instructions request delegation.", "sources": ["https://developers.openai.com/codex/agent-configuration/subagents.md"], "groups": [ { "rows": [ { "cmd": "default · worker · explorer", "desc": "Built-in agents: general-purpose fallback, execution-focused implementer, read-heavy explorer. A custom agent with the same name wins." }, { "cmd": "~/.codex/agents/.toml · .codex/agents/", "desc": "Custom agents — one TOML file each, loaded as config layers for spawned sessions." }, { "cmd": "name / description / developer_instructions", "desc": "Required fields. Optional `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, `skills.config` inherit from the parent session." }, { "cmd": "agents.max_threads = 6", "desc": "Concurrent open agent thread cap (default shown)." }, { "cmd": "agents.max_depth = 1", "desc": "Nesting: children can't spawn deeper descendants by default. Raising it multiplies token usage and latency.", "danger": true }, { "cmd": "/agent", "desc": "Switch the active thread to inspect or steer a running subagent; or just ask Codex to steer, stop, or close it." }, { "cmd": "Sandbox inheritance", "desc": "Subagents inherit the parent turn's sandbox policy and permission mode; a custom agent file can pin its own (e.g. read-only)." } ] } ] }, { "id": "hooks", "title": "Hooks", "lede": "Deterministic scripts on lifecycle events, configured in `hooks.json` or inline `[hooks]` in `config.toml`. Non-managed hooks must be reviewed and trusted in `/hooks` before they run.", "sources": ["https://developers.openai.com/codex/hooks.md"], "groups": [ { "rows": [ { "cmd": "~/.codex/hooks.json · /.codex/hooks.json", "desc": "The usual locations (plus inline `[hooks]` in either `config.toml`). All matching hooks from every layer run; project hooks need a trusted project." }, { "cmd": "SessionStart · SubagentStart", "desc": "Thread-scope events — e.g. load session notes on `startup|resume` matchers." }, { "cmd": "PreToolUse · PermissionRequest · PostToolUse", "desc": "Around tool calls and approval requests, filtered by matcher (e.g. `Bash`)." }, { "cmd": "UserPromptSubmit", "desc": "Intercept the prompt before the model sees it — e.g. scan for pasted API keys." }, { "cmd": "PreCompact · PostCompact", "desc": "Around conversation compaction." }, { "cmd": "Stop · SubagentStop", "desc": "Turn boundaries — e.g. run a validation check when a turn ends." }, { "cmd": "event → matcher → handlers", "desc": "Matching command hooks launch concurrently; one hook can't block another from starting." }, { "cmd": "Trust by hash", "desc": "Trust is recorded against the hook's definition hash — new or changed hooks are skipped until re-trusted in `/hooks`." } ] } ] } ] }