Interactive TUI
Use codex when you want to watch plans, approve actions, inspect diffs, and steer the task as it runs.
No matching entries. Clear the filter or try a command name such as plan, review, exec, permissions, AGENTS, or skills.
Mental Model
Codex CLI is a local terminal coding agent. It reads the selected workspace, edits files, runs commands under approval and sandbox policies, and shares configuration with the IDE extension and Codex app.
Non-interactive runs
Use codex exec for scripts, CI helpers, JSONL event output, and repeatable checks that should exit cleanly.
AGENTS.md
Codex reads global and project instruction files at run start. Closer directory guidance appears later and overrides broader guidance.
Permissions
Approval policy decides when Codex asks. Sandbox or permission profiles decide what commands can read, write, and reach over the network.
Commands That Matter
These are the commands and slash commands that carry most day-to-day engineering work.
codex
Start the interactive terminal UI in the current workspace. Best default for agentic implementation work.
codex "query"
Start with an initial prompt and stream the answer. Good for quick codebase questions or focused analysis.
codex exec "task"
Run non-interactively. Add
--json, --output-schema, or -o when wiring Codex into scripts.codex resume --last
Continue the most recent local session. Use
--all to ignore current-directory filtering.codex review --uncommitted
Run a dedicated local code review agent over staged, unstaged, and untracked changes.
codex --model gpt-5.5
Pin the launch model. As of June 2026, official docs recommend
gpt-5.5 for most Codex tasks.codex -s workspace-write -a on-request
Set sandbox and approval behavior for one session. Prefer tighter defaults until a repo and task are trusted.
codex -i screenshot.png "task"
Attach screenshots, diagrams, or design specs to the initial prompt.
codex mcp list
Inspect configured MCP servers. Use
codex mcp add to connect external tools and context.codex plugin list
List available plugins from configured marketplace snapshots. In-session,
/plugins opens the browser.codex cloud
Browse Codex Cloud tasks and apply resulting diffs locally. Use
codex cloud exec --env ENV_ID to launch cloud work.codex doctor | codex update | codex completion zsh
Diagnose the install, update the binary, and install shell completion for daily use.
/plan | /goal | /diff | /review | /compact
The core in-session control loop: plan, track objective, inspect changes, review, and manage context.
/permissions | /approve | /status | /debug-config | /hooks
Inspect and adjust what Codex can do, retry an auto-review denial once, and debug effective configuration.
/skills | /plugins | /mention | /ide | /agent | /fork | /side
Add task-specific capability, attach files or IDE context, inspect subagents, fork the thread, or ask a side question.
Useful Workflows
Codex works best with explicit context and a concrete definition of done.
1
First session in a repo
Generate instructions, inspect configuration, and keep setup factual.
codex /init /status /permissions Edit AGENTS.md down to: - setup/build/test commands - repo layout and important directories - conventions and do-not rules - what done means and how to verify
2
Feature work
Plan first, then make Codex prove the change.
/plan Add account deletion using existing auth and audit-log patterns. /goal Implement the approved plan, keep tests green, and preserve public API shape. Implement. Add focused tests, run the smallest relevant suite, then run typecheck. Show commands and results. /diff /review
3
Bug fix
Give repro steps and constraints; require failing-then-passing evidence.
Bug: settings save reports success but does not persist after refresh. Repro: 1. npm run dev 2. visit /settings 3. toggle Enable alerts 4. click Save 5. refresh and observe reset Reproduce locally before editing. Add a regression test if feasible. Fix root cause, then rerun repro and relevant checks.
4
Review before commit
Use Codex's reviewer as a separate pass, not as the author grading itself.
codex review --uncommitted "Prioritize correctness bugs, data loss, security issues, and missing tests. Ignore subjective style." codex review --base main codex review --commit HEAD
5
Scripted automation
Use exec for repeatable terminal workflows and machine-readable output.
git diff --name-only main | codex exec --json \ "Review these changed files for migration risks. Return concise findings." codex exec --output-schema schema.json \ "Classify this CI failure and suggest the next command to run."
6
Parallel review
Use subagents for read-heavy work where summaries are better than raw logs.
Review this branch with parallel subagents: - one for security risks - one for test gaps - one for maintainability Wait for all three, then summarize findings by category with file references.
Configuration Map
Codex quality depends heavily on clean configuration. Keep durable facts out of prompts and in the right file.
| Artifact | Use it for | Do not use it for | Scope |
|---|---|---|---|
~/.codex/AGENTS.md |
Personal working agreements that should apply in every repo. | Project-specific commands or conventions. | User global. |
AGENTS.md |
Repo layout, setup, build/test/lint commands, conventions, constraints, and done criteria. | Long tutorials or volatile details. Keep it short and accurate. | Project or nested directories. |
AGENTS.override.md |
Temporary or more-specific override guidance. Nearby overrides beat broader files. | Permanent team norms that should merge with broader guidance. | User, repo, or subdirectory. |
~/.codex/config.toml |
Personal defaults: model, approval policy, sandbox mode, profiles, MCP servers, feature flags. | Team-required policy or repo-only hooks. | User global. |
.codex/config.toml |
Trusted repo settings shared by a project, including MCP, hooks, and profile defaults. | Secrets or machine-specific paths. | Project; only loaded when trusted. |
.codex/hooks.json |
Deterministic lifecycle scripts: prompt checks, command policy, post-tool review, stop validation. | Soft preferences. Hooks should enforce real policy or automation. | User, project, system, managed, or plugin. |
.agents/skills/*/SKILL.md |
Reusable task workflows with optional scripts, references, and assets. | Always-on repo behavior. Put that in AGENTS.md. |
Repo, user, admin, system, or plugin. |
Config precedence: CLI flags and
--config overrides win, then trusted project config from root to current directory, selected profile files, user config, system config, and built-in defaults.Skills and Plugins Worth Adding
Skills define reusable procedures. Plugins distribute skills, app integrations, MCP servers, and related assets. Verify availability with /skills and /plugins.
$skill-creator
Use first when turning a repeated workflow into a skill. It helps decide trigger conditions, scope, scripts, and references.
$skill-installer
Installs curated or repository-hosted skills for local experimentation. Good for adding focused capabilities without building a full plugin.
Codex Security plugin
Use for authorized code scanning, vulnerability confirmation, and reviewed security fixes. Strong fit for auth, data flows, and web backends.
GitHub workflow skills
Useful third-party skill category for addressing PR comments, fixing CI, summarizing diffs, and opening PRs through gh or a GitHub app.
Browser automation skills
Use when UI work needs screenshots, DOM inspection, local app checks, and visual regression loops.
Document artifact skills
Install only if the repo touches generated docs, spreadsheets, decks, reports, or office-file QA. They add specialized render-and-verify workflows.
Image generation skills
Good for app assets, mockups, placeholders, sprite sheets, and UI imagery. In Codex CLI you can also invoke image generation with $imagegen.
App plugins
OpenAI docs list Gmail, Google Drive, Slack, Sites, and similar plugins as examples. Use them when the task needs external workspace data.
Team plugins
Package mature skills, MCP servers, hooks, and app mappings into a plugin when more than one engineer or repo should use them.
Install and inspect pattern
codex /plugins /skills $skill-installer linear # CLI plugin management codex plugin marketplace list codex plugin list codex plugin add <plugin>
Before installing third-party skills or plugins, inspect scripts, hooks, MCP servers, required app connections, and what data may leave the repo.
Prompt Patterns
Codex prompts are most reliable when they include goal, context, constraints, and done-when criteria.
Explore before editing
/plan Read @src/auth/session.ts and @src/auth/middleware.ts. Explain the current refresh flow, identify likely failure points, and propose the smallest safe fix. Do not edit files yet.
Implement with evidence
Implement the approved plan. Add or update tests for the timeout case. Run the focused test first, then the package typecheck. Report commands, results, and files changed.
Review stance
/review Prioritize correctness bugs, security issues, data loss, and missing tests. Give file references and concrete fixes. Ignore subjective style unless it hides a bug.
Side question
/side Compare the two migration options in the last plan. Do not change the main task. Return a short decision table and recommendation.
Safety and Control
Make Codex fast by removing low-value prompts, not by removing boundaries.
Use Auto first
Auto lets Codex work in-scope and still asks before outside-scope or network actions. Switch to Read Only for audits.
Avoid full access
danger-full-access and bypass flags are for externally sandboxed automation or intentionally broad local work.
Deny sensitive files
Use permission profiles to deny **/*.env, credential folders, production dumps, and generated secrets.
Gate network access
Enable network per profile and define domain rules where possible. Treat web search results as untrusted context.
Trust hooks deliberately
Non-managed command hooks require review and trust. Changed hook definitions are skipped until trusted again.
Let git be the guardrail
Use small diffs, /diff, /review, and focused commits. Codex transcripts help, but git is the source of rollback truth.