Codex Slash Commands#

What it is#

Codex CLI exposes 30+ slash commands inside the interactive TUI session. Type / to open the command popup and navigate with arrow keys or type to filter. Press Tab to queue a slash command for the next turn while the agent is still running. Most commands take effect immediately; a few open sub-menus or require additional input.

Opening the popup#

Session management#

Session commands control the lifecycle of the current chat thread — starting fresh, resuming a previous run, forking off a branch, or compacting history to save tokens. They never trigger model calls themselves (except /compact, which uses the model to summarise).

Example: compact then continue#

/compact

Output (inline in TUI):

Compacted 42 turns → 1 summary message (saved ≈ 14,000 tokens).

Example: fork to try an alternative#

/fork

Output (inline in TUI):

Forked session th_01abc → th_01xyz. Now on th_01xyz.

Model and behaviour#

These commands let you change how the agent thinks within an active session — swap the model, dial reasoning effort up or down, request a plan-first workflow. Changes apply to the next turn; turns already in flight are unaffected.

Example: switch model mid-session#

/model gpt-5-pro

Output (inline in TUI):

Switched to gpt-5-pro for the next turn.

Example: plan-first mode for a tricky task#

/plan
Refactor src/auth/ to use JWT cookies instead of session tokens.

Output (inline in TUI):

Plan:
1. Add jwt dependency to pyproject.toml.
2. Introduce src/auth/jwt.py with encode/decode helpers.
3. Replace session lookups in src/auth/middleware.py.
4. Update tests/test_auth.py.
Proceed? [y/n/e]

Permissions and sandboxing#

The TUI offers fast inline controls for the same approval and sandbox settings you can configure in config.toml. Changes are scoped to the current session and revert when you exit.

Example: temporarily widen the sandbox#

/sandbox-add-write-dir /tmp/build-out

Output (inline in TUI):

Added /tmp/build-out to writable paths for this session.

Example: tighten approvals after a risky step#

/approvals untrusted

Output (inline in TUI):

Approval policy set to "untrusted" for this session.

Diff and review#

Diff and review commands surface the agent’s filesystem changes in a digestible form, then optionally fold them through a second pass of the agent for self-review. Pair /diff with /review after a long autonomous turn to catch regressions before committing.

Example: save and apply a session’s diff#

/save-diff /tmp/session.patch

Output (inline in TUI):

Saved 142 lines of diff to /tmp/session.patch

# Outside the TUI, apply the patch to a different branch
git checkout review-branch
git apply /tmp/session.patch

Output: (none — patch applied)

Example: self-review before committing#

/diff
/review

Output (inline in TUI):

[diff displayed]
[agent review: "Looks correct, but consider extracting the JWT helpers to src/auth/jwt.py for testability."]

Context and files#

These commands explicitly add or surface context — file pickers, current session status, and project-memory scaffolding. They are the workhorses for telling the agent “look at this file” without typing the full path.

Example: status snapshot#

/status

Output (inline in TUI):

session_id     : th_01abc
model          : gpt-5-pro
profile        : sprint
sandbox        : workspace-write (+ allow_network)
approval       : on-request
cwd            : /home/alice/myproject
agents_md      : found (1,842 bytes)
mcp_servers    : filesystem, github

Agents and processes#

/agent is Codex’s entry point for delegated sub-agent work — spawn a child agent for an isolated task and either wait for its result or background it. See subagents for the full reference. /ps lists long-running processes started by the agent (background servers, watchers).

Example: list processes#

/ps

Output (inline in TUI):

PID    CMD                                STARTED
4421   npm run dev (server on :4321)      14:02
4475   node test-watch.js                 14:08

Example: kill a runaway process#

/kill 4475

Output (inline in TUI):

Killed PID 4475.

MCP servers#

/mcp is the live introspection command for Model Context Protocol servers — see what’s running, what tools are exposed, and per-server tool-call counts. Sub-commands let you restart, disable, or re-enable a server inline without editing config.

See MCP Servers for configuration.

Example: restart a flaky server#

/mcp restart filesystem

Output (inline in TUI):

Stopping filesystem… ok
Starting filesystem… ok
4 tools available

Apps and plugins#

Debug and config#

When something feels wrong (a hook didn’t fire, a profile didn’t activate, an MCP tool isn’t available), these are the first commands to reach for. /debug-config is the single most-useful introspection command; it shows the fully-merged active configuration.

Example: print effective config#

/debug-config

Output (inline in TUI):

model           = "gpt-5-pro"
approval_policy = "on-request"
sandbox_mode    = "workspace-write"
profile         = "sprint"
project_trusted = true
agents_md_path  = "/home/alice/myproject/AGENTS.md"
mcp_servers     = ["filesystem", "github"]
hooks_loaded    = 2

Example: check token usage#

/tokens

Output (inline in TUI):

Input  tokens this session : 18,432
Output tokens this session : 4,210
Cache  hits / misses        : 7 / 12

Account#

Keyboard shortcuts (TUI)#

The TUI is fully keyboard-driven. Memorise these five and you’ll rarely reach for the mouse.

Custom slash commands#

Codex supports user-defined slash commands defined as Markdown files in ~/.codex/commands/ (global) or <project>/.codex/commands/ (project). Each file’s name becomes the command (e.g., ~/.codex/commands/lint.md → /lint), and the body is the prompt sent to the model.

Define /lint#

<!-- ~/.codex/commands/lint.md -->
Run `ruff check --fix .` and `mypy src/`. Report what you fixed and what
still needs human attention.

Output: (none — defines a slash command)

Invoke it#

/lint

Output (inline in TUI):

[agent runs ruff and mypy, reports results]

Arguments via $1, $2, $@#

<!-- ~/.codex/commands/translate.md -->
Translate the following text into $1: $@

/translate French "Hello, world"

Output (inline in TUI):

"Bonjour le monde"

Project-scoped commands#

<!-- myproject/.codex/commands/release.md -->
Bump the version in pyproject.toml, write a CHANGELOG entry for everything
since the last tag, and create an annotated git tag v$1.

Output: (none — defines a project-scoped slash command)

Common pitfalls#

1. /clear does NOT free the context window. It only hides the transcript visually. Use /compact to actually reclaim tokens.

2. /model mid-session changes the model from the next turn onward. The current turn (if mid-flight) finishes with the old model.

3. Tab to queue commands only works while the agent is running. Outside of an in-flight turn, Tab autocompletes.

4. /revert only undoes the last edit operation. It is not a full session-level rollback. Use /save-diff + manual git apply -R for multi-step undo.

5. Custom slash commands run in the same approval policy as the session. A /dangerous command isn’t magically safer; if you have approval_policy = "never", your custom command will execute without prompting.

6. /exit and Ctrl+D flush the history file. If the session was forked, the parent thread is not duplicated — only the active fork is saved.

7. Slash commands cannot themselves call other slash commands. You can describe a workflow but you cannot chain /lint + /test in one custom command. Use a single multi-step prompt instead.

Real-world recipes#

Two-command code review workflow#

/diff
/review

Output (inline in TUI):

[diff displayed]
[agent suggests improvements]

Inspect token usage before a long task#

Useful before a /compact to gauge whether it’s worth the round-trip.

/tokens
/compact
/tokens

Output (inline in TUI):

Input tokens: 28,431  →  Compacting  →  Input tokens: 14,108

Save a session diff as a patch and switch branches#

/save-diff /tmp/feat.patch

# Outside the TUI
git stash
git checkout main
git apply /tmp/feat.patch

Output: (none — patch applied to main)

Custom /cleanup command for a project#

<!-- myproject/.codex/commands/cleanup.md -->
1. Remove unused imports in src/.
2. Sort imports per isort profile=black.
3. Run ruff format on everything in src/.
4. Report a one-line summary.

/cleanup

Output (inline in TUI):

Removed 4 unused imports, sorted imports in 12 files, formatted 28 files.