How to Use Slash Commands Within Codex CLI: A Developer Guide

Developers can use slash commands within Codex CLI by typing any input that begins with a forward-slash (/), which triggers a five-stage detection and execution pipeline that delegates to handler functions in the TypeScript SDK.

The OpenAI Codex CLI provides a powerful terminal interface for AI-assisted coding workflows through simple text commands. By leveraging slash commands within Codex CLI, developers can trigger complex operations—from generating implementation plans to executing sandboxed scripts—without leaving their terminal. This architecture separates lightweight parsing logic in the CLI entry point from heavy-duty execution handlers in the SDK, making it straightforward to extend functionality.

How Slash Commands Work in the Codex CLI

The Codex CLI processes slash commands through a streamlined pipeline that keeps the parser minimal while delegating actual work to the SDK.

Command Detection and Parsing

When you type a line starting with /, the CLI entry point at codex-cli/bin/codex.js detects the leading character and splits the input into a command name and an optional argument string. For example, input /plan my-task is separated into the command plan and the argument string my-task.

Command Lookup and Execution

The command name is matched against the built-in table defined in docs/slash_commands.md. Each entry maps to a specific handler function in the TypeScript SDK, such as CodexOptions.handlePlan located in sdk/typescript/src/codexOptions.ts. The handler constructs the appropriate request payload—for example, a PlanRequest or ListPlansRequest—and transmits it to the Codex back-end via the high-level client in sdk/typescript/src/codex.ts.

Result Handling

After execution, the CLI prints the response to the terminal, updates the TUI interface if running in interactive mode, and persists any side effects such as newly generated plan files.

Built-in Slash Command Examples

Here are practical examples of how to use slash commands within Codex CLI for common development tasks:

Creating Implementation Plans with /plan

Use the /plan command to generate structured implementation plans for new features:

$ codex /plan "Add a new feature to the API"

The CLI parses plan as the command and the quoted string as the argument. Internally, this invokes the handlePlan method in sdk/typescript/src/codexOptions.ts, which builds a PlanRequest and posts it to the server.

Executing Scripts with /run

The /run command executes generated scripts in a sandboxed environment:

$ codex /run my_script.sh

According to the command table in docs/slash_commands.md, the run handler executes the script and streams the output back to your terminal in real time.

Listing Resources with /list-plans

To view recent plans without providing arguments:

$ codex /list-plans

This sends a ListPlansRequest through the SDK, and the CLI formats the returned JSON into a readable table for quick review.

Key Implementation Files

The following files define the slash command architecture according to the OpenAI Codex source code:

• codex-cli/bin/codex.js – Entry point that scans for leading / characters and initiates command dispatch.
• docs/slash_commands.md – Authoritative registry of all built-in slash commands and their semantics.
• docs/tui-chat-composer.md – Documents auto-completion and display behavior for slash commands in the interactive TUI.
• sdk/typescript/src/codexOptions.ts – Implements concrete handlers like handlePlan and handleRun that build request payloads.
• sdk/typescript/src/codex.ts – High-level client used by the CLI to send requests and process responses from the back-end.

Summary

• Slash commands within Codex CLI begin with a forward-slash (/) and are detected in codex-cli/bin/codex.js.
• The parser splits commands into names and arguments, then looks up handlers in the table defined in docs/slash_commands.md.
• Handlers such as CodexOptions.handlePlan in sdk/typescript/src/codexOptions.ts construct requests like PlanRequest and delegate to the back-end.
• Results are displayed in the terminal, with TUI updates and side-effect persistence handled automatically.
• The modular architecture allows extending functionality by adding entries to the command table and implementing new SDK handlers.

Frequently Asked Questions

How does the Codex CLI detect slash commands?

The CLI scans input lines for a leading forward-slash (/) at the entry point in codex-cli/bin/codex.js. When detected, the line is treated as a command rather than natural language input, triggering the parsing and execution pipeline immediately.

Where are slash command handlers implemented?

Concrete handlers are implemented in the TypeScript SDK at sdk/typescript/src/codexOptions.ts. For example, the handlePlan method constructs a PlanRequest payload, while handleRun manages script execution in sandboxed environments.

Can I add custom slash commands to the Codex CLI?

Yes. The architecture separates the lightweight CLI parser from the SDK logic. To add a command, you register it in docs/slash_commands.md and implement the corresponding handler function in sdk/typescript/src/codexOptions.ts, following the pattern used by existing commands like handlePlan.

What is the difference between /plan and /run commands?

The /plan command generates implementation plans by sending a PlanRequest to the back-end and creating plan files, while /run executes existing scripts in a sandboxed environment and streams real-time output back to the terminal, as defined in the command table at docs/slash_commands.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}