Codex CLI, fast.

Install & launch core

# npm
npm install -g @openai/codex
# macOS Homebrew
brew install --cask codex

cd your-repo
codex             # interactive TUI in this repo
codex doctor      # diagnostic report
codex update      # check for updates
codex completion zsh   # shell completions

Run from the repo root — the working directory is the workspace the sandbox protects, and where AGENTS.md is read from.

First 10 minutes in a new repo

codex login       # ChatGPT plan, or login --api-key
codex
> /init          # scaffold AGENTS.md from the codebase
> /model         # pick model + reasoning effort
> /permissions   # tune what runs without asking
> /status        # model, sandbox, token usage

Then ask a real question before asking for code: “give me an overview of this codebase”. Codex explores with its own tools — don’t paste files in; @-mention them if you must.

Billing: plan usage by default; /status shows limits. API-key auth bills per token.

Session hygiene daily

• /new — fresh conversation between unrelated tasks. The highest-leverage habit. (/clear only wipes the screen.)
• /compact — summarize history to free tokens; Codex also auto-compacts on long-horizon work.
• /resume — reopen a past thread (also codex resume --last from shell).
• /fork — branch the conversation to explore an alternative without losing the original.
• /side — ephemeral side conversation for a quick tangent; main thread stays clean.
• /status — model, sandbox, approvals, token usage at a glance.

Setup & steering daily

• /init — scaffold AGENTS.md for the repo.
• /model — switch model and reasoning effort mid-session.
• /fast — toggle the Fast service tier (same model, faster tokens) when available.
• /permissions — adjust what runs without asking, in-session.
• /plan — demand an execution plan before any implementation.
• /goal — pin a persistent objective the agent keeps optimizing for.
• /mention / /ide — attach files / pull editor context into the next prompt.

Review & repo power

• /review — dedicated reviewer over uncommitted changes, a base branch, or a specific commit. Run it before every push.
• /diff — git diff including untracked files, without leaving the TUI.
• /approve — retry something the auto-reviewer denied.

Extending power

• /mcp — list configured MCP servers and tools.
• /skills — inspect local skills (~/.codex/skills).
• /plugins — installed + discoverable plugins (skills + MCP + apps bundles).
• /hooks — review lifecycle hooks.
• /apps — insert ChatGPT apps into a prompt as $app-slug.
• /memories — toggle memory injection/generation.
• /experimental — opt into feature flags (also codex features).

Parallel & background 2026

• /agent — switch between agent threads (multi-agent sessions).
• /ps — background terminals + recent output (dev servers, tails).
• /stop — kill all background terminal work.

TUI quality-of-life

• /statusline / /title — model/branch/tokens in the footer & terminal title.
• /theme — syntax-highlight theme; /keymap — remap any shortcut; /vim — vim composer.
• /copy — copy last response; /raw — raw scrollback for clean terminal selection.
• /personality — communication style; /debug-config — which config layer won; /feedback — file an issue with diagnostics.

While Codex is working

• Esc — interrupt; press again to backtrack the transcript and edit an earlier message. Use early and often.
• Tab — queue a follow-up instruction while a turn runs.
• Approve / reject inline — plan steps and command requests get y/n prompts in default approval modes.
• Ctrl+O — copy the latest output (same as /copy).
• Alt+R — raw scrollback mode for clean copy/paste.

Composing prompts

• @ — fuzzy file search (@src/auth/jwt.ts) to attach files.
• $app-slug — mention a connected app (via /apps).
• Ctrl+R — search prompt history.
• Ctrl+G — open $EDITOR for long prompts.
• Paste images straight into the composer (or -i mock.png from the shell) for UI work.
• ↑ — draft/message history; Ctrl+C ×2 or /quit — exit.

Flags you’ll actually use

codex "fix the flaky retry test"     # prompt as arg
codex resume --last                  # continue last session
codex resume                         # session picker
codex fork                           # branch an old session
codex -m gpt-5.4                     # model override
codex -c model_reasoning_effort=high # any config key inline
codex -s workspace-write -a on-request
codex --profile ci                   # named config layer
codex -i mock.png "build this screen"
codex --search "…"                   # live web search
codex sandbox -- npm test            # run any cmd under the sandbox

Headless / exec mode CI

# one-shot, non-interactive
codex exec "update the changelog for the next release"

# pipe anything in
cat error.log | codex exec "root-cause this stack trace"

# machine-readable event stream
codex exec --json "lint my commit messages"

# CI: full autonomy inside a container
codex exec -s danger-full-access -a never \
  "fix the failing tests and commit"

Building something bigger? The Codex SDK (TypeScript/Python) and codex app-server expose the same agent programmatically; codex cloud manages cloud tasks from the terminal, and codex remote-control runs a daemon you can drive remotely.

AGENTS.md hierarchy

~/.codex/AGENTS.md      # you, everywhere (style, tools)
./AGENTS.md             # repo root — commit it
./packages/api/AGENTS.md # nested — closest file wins

What belongs there: build/test commands, conventions the model gets wrong, repo etiquette (“never commit to main”), gotchas. What doesn’t: anything derivable from the code. It’s loaded every session — bloat costs context and attention.

It’s an open standard (agents.md) — the same file serves Codex, Claude Code, Cursor, and friends.

Memories & the context window 2026

• Memories — Codex distills useful context from past sessions and injects it into new ones. Toggle with /memories; enable via [features] memories = true.
• /new between tasks. Stale context degrades quality more than anything else.
• Auto-compaction keeps long-horizon work alive, but a deliberate /compact at a natural breakpoint beats an automatic one mid-thought.
• /side and /fork keep tangents and experiments out of the main thread.
• /status shows token usage when things feel sluggish; prune unused MCP servers — tool schemas are a silent context hog.

Plan → implement → review default

For anything non-trivial: /plan (or start in -s read-only) and have Codex research the change. Read the plan, push back, approve. Implement in Auto mode, then /review against the base branch before committing.

Skipping the plan step is the #1 cause of “it confidently did the wrong thing.”

TDD with an agent default

Ask for failing tests first, from the spec — explicitly not implementation. Commit them. Then: “make these pass; don’t modify the tests.” The red/green loop gives Codex an objective target it will grind against autonomously.

Visual iteration

For UI: paste a mock (or codex -i mock.png), give it eyes — a Playwright/Chrome DevTools MCP server for screenshots — and say “iterate until it matches.” Agents with visual feedback converge in 2–3 rounds; agents without don’t.

Parallel sessions with worktrees power

git worktree add ../proj-auth feature/auth
cd ../proj-auth && codex

One Codex per worktree = zero collisions. In-session, /agent switches between agent threads, and gpt-5.4-mini makes cheap subagents.

Local ↔ cloud handoff 2026

Start locally, delegate the long grind: codex cloud manages Codex Cloud tasks from the terminal, and the /apps→Desktop handoff moves a CLI thread into the Codex app. @codex on a GitHub PR or issue triggers cloud work and review there.

Safe full-auto loops

Mechanical sweeps (lint, codemods, dependency bumps): run inside a container with -s danger-full-access -a never and let it grind. Outside a container, prefer Auto mode — workspace-write with no network is already “safe YOLO.” Checkpoint with git; there’s no /rewind, so commits are your undo.

Branch the conversation

Two plausible designs? /fork and try both, then keep the winner. Quick tangent (“what does this env var do?”) — /side so the main thread’s context stays on task. Wrong direction mid-turn — Esc, edit the earlier message, resend.

Review before merge

/review runs a dedicated reviewer model over your diff — uncommitted work, a branch delta, or one commit — and it doesn’t modify files, so it’s safe to run constantly. Pair with /diff for your own pass. You still own the merge.

CI & automation

codex exec --json in a pipeline step covers triage, changelog generation, failure analysis. Use a ci profile pinning model, sandbox, and approval policy so behavior is reproducible. GitHub-side, @codex mentions and Codex code review handle PR flow.

Anatomy & install

~/.codex/skills/deploy-checks/SKILL.md

# SKILL.md
---
name: deploy-checks
description: Pre-deploy validation for our k8s services.
  Use before any production deploy.
---
1. Run ./scripts/preflight.sh
2. Verify migrations are reversible…

codex plugin           # install / manage plugins
/plugins               # browse discoverable plugins in-session
/skills                # inspect what's loaded

The description is the trigger — write it as a “when to use” sentence. Restart Codex after installing or editing a skill so metadata reloads.

Third-party picks & why curated

• ComposioHQ/awesome-codex-skills — the curated community index; the fastest way to see what exists before writing your own.
• Agensi marketplace — security-scanned skill downloads (unzip into ~/.codex/skills/). Why it matters: skills ship executable scripts that run with your permissions — provenance is the whole game.
• anthropics/skills document suite (pdf, docx, xlsx, pptx) — the SKILL.md format is a cross-tool standard, so the best Claude-ecosystem skills work in Codex too. Real Office files via scripts instead of hallucinated markup.
• Your own — the highest-ROI skill encodes your release process, migration checklist, or test conventions. Explained it twice? Make it a skill.

Audit GitHub-sourced skills before installing — read the SKILL.md and every script it calls.

Setup

# CLI
codex mcp add github -- npx -y @modelcontextprotocol/server-github
codex mcp list

# or config.toml — with per-tool control
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp@latest"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
disabled_tools = ["delete_repository"]
default_tools_approval_mode = "auto"

/mcp in-session lists servers and tools. enabled_tools/disabled_tools trim context cost and risk per server.

Worth the context cost

• Playwright / Chrome DevTools — lets Codex drive a browser and see your app. The single biggest upgrade for frontend work.
• GitHub — PRs, issues, CI runs as tools (plain gh via shell is often enough).
• Context7 — version-correct library docs on demand; kills “trained on the old API” bugs.
• Sentry — the actual stack trace and breadcrumbs for the bug you’re fixing.
• Postgres (read-only) — schema-aware queries while debugging data issues.
• Apps (/apps) — Figma, Linear, and other ChatGPT app connectors as $mentions, no MCP config needed.

Every server’s tool schemas consume context. Connect what you use; prune when /status shows bloat.

Hooks power

# ~/.codex/config.toml
[[hooks.PreToolUse]]
matcher = { tool_name = "shell" }
[[hooks.PreToolUse.hooks]]
command = "./scripts/block-prod-db.sh"

[[hooks.PostCompact]]
[[hooks.PostCompact.hooks]]
command = "notify-send 'History compacted'"

Deterministic shell commands at lifecycle points — guarantees, not suggestions. Classic uses: auto-format after edits, block dangerous commands, notify on long-running turns. /hooks to inspect. Caveat: not yet Windows-compatible.

A useful baseline config

model = "gpt-5.5"
model_reasoning_effort = "medium"   # minimal…xhigh
approval_policy = "on-request"      # untrusted|on-request|never
sandbox_mode = "workspace-write"
web_search = "cached"               # disabled|cached|live
file_opener = "vscode"
notify = ["terminal-notifier", "-title", "Codex", "-message"]

[sandbox_workspace_write]
network_access = false

[features]
memories = true

[tui]
notifications = true
theme = "github-light"

Profiles: ~/.codex/ci.config.toml overlays the base when you pass --profile ci — pin a model/sandbox/approval combo per context.

• /plan for anything non-trivial. Cheap insurance against confident nonsense.
• /new between tasks — and remember /clear doesn’t do what you think.
• Interrupt early. Esc in the first minute saves ten later.
• Give it a feedback loop. Tests, a browser, a compiler — verifiable targets make the agent self-correcting.
• Commit constantly. Git is your rewind button; there isn’t another one.

• Invest in AGENTS.md like onboarding a new hire — and keep it short.
• Encode repeated explanations as skills; distribute team setups as plugins.
• Tune the sandbox, don’t fight it — network_access, writable_roots, profiles. Approval fatigue means your config is wrong.
• Match effort to the task — xhigh for architecture, minimal/mini/Spark for chores.
• /review like it’s a teammate’s PR — then read the diff yourself. You still own the merge.