The Codex Cheat Sheet · Little Might

Codex is OpenAI’s terminal-native coding agent. It runs in your repo, edits files, runs commands, and can operate fully autonomously. Here’s what you actually need to know.

Not a tutorial. Just the reference.

CLI Basics

# Start an interactive session
codex

# Run a one-shot task and exit
codex "Fix all TypeScript errors in src/"

# Fully autonomous — no approval prompts
codex --approval-mode full-auto "Run the tests and fix any failures"

# Auto-edit files but ask before running shell commands
codex --approval-mode auto-edit "Refactor the auth module"

# Use a specific model
codex --model o3 "Rewrite the data pipeline for performance"

# Start with images attached
codex --image screenshot.png "What's wrong with this UI?"

Approval Modes

The most important flag. Controls how much Codex can do without asking.

Mode	What it does
`suggest`	Shows diffs, asks before every file change (default)
`auto-edit`	Edits files freely, asks before running shell commands
`full-auto`	Does everything — file edits, shell commands, the works

codex --approval-mode full-auto "task"
# or shorthand:
codex --full-auto "task"

Rule: Use full-auto in a branch. Never on main with uncommitted work.

Key Flags

--approval-mode <mode>        suggest | auto-edit | full-auto
--model / -m <model>          Which model to use (see below)
--quiet / -q                  Non-interactive output (for scripts/CI)
--no-project-doc              Ignore AGENTS.md for this session
--project-doc <file>          Use a custom project doc instead of AGENTS.md
--dangerously-auto-approve-everything  Skip all approval prompts (same as full-auto)
--writable-root <path>        Path Codex is allowed to write to
--context / -c <file>         Add a file to the initial context
--image <file>                Attach an image to your prompt
--config                      Print the config file location
--version                     Show version

Models

Model	When to use it
`o4-mini`	Default. Fast, smart, good for most tasks
`o3`	Most capable. Use for architecture, complex refactors
`gpt-4.1`	Great for simple edits and quick iterations
`gpt-4.1-mini`	Fast and cheap for repetitive tasks

Switch mid-task:

codex --model o3 "Redesign the database schema for multi-tenant support"

`AGENTS.md` — Your Codex Context File

Codex reads AGENTS.md at the start of every session. This is your persistent project context — the stuff you’re tired of repeating.

# Project Name

## What this is
SaaS billing dashboard built with Next.js and Stripe.

## Stack
Next.js 14, TypeScript, Supabase, Stripe, Tailwind v4, Vercel.

## Rules
- Always write tests before implementation
- Use pnpm, not npm or yarn
- Never modify the database schema directly — use migrations
- All components go in components/ui/

## Key files
- src/app/api/ — all API routes
- supabase/migrations/ — schema history
- src/lib/stripe.ts — Stripe integration

## Gotchas
- Auth uses httpOnly cookies, not JWT. Don't touch it.
- The analytics endpoint is rate-limited to 10 req/s.
- We're on Tailwind v4 — no arbitrary values.

## Allowed operations
- Edit any file in src/
- Run: pnpm test, pnpm build, pnpm lint
- Never: git push, rm -rf, edit .env

The Subdirectory Stack

AGENTS.md files compose across directories:

Root AGENTS.md — global rules for the whole repo
src/api/AGENTS.md — rules specific to that module
Codex reads parent files automatically when working in a subdirectory

Same pattern as Claude Code’s CLAUDE.md. Same payoff: agents stay in their lane without you having to repeat yourself.

Keyboard Shortcuts

Shortcut	Action
`↑ / ↓`	Navigate input history
`Ctrl + C`	Cancel current generation
`Ctrl + D`	Exit the session
`Shift + Enter`	New line without sending

Sandbox — How Codex Isolates Work

Codex runs in a sandbox. By default it can only touch:

The current working directory
Temp directories

macOS: Uses Apple’s Seatbelt (sandbox-exec). Shell commands run inside the sandbox.
Linux: Uses landlock kernel-level isolation.
Docker: Full container isolation — best for CI.

Set a custom writable path:

codex --writable-root /path/to/safe/dir "Build the feature"

Running in CI / Headless

# Output-only, no interactivity
codex --quiet "Run the test suite and output failures"

# Full auto for CI pipelines
codex --approval-mode full-auto --quiet "Fix lint errors and format code"

Pipe it into scripts, chain it with other commands, log the output.

Prompt Patterns That Actually Work

Be specific about scope

“Only touch src/auth/session.ts. Fix the JWT expiry bug. Don’t refactor anything else.”

Codex will expand its scope if you let it. Don’t let it.

Give it the error output

“The build is failing with this error: [paste]. Here’s the relevant file: [paste]. Fix it.”

Codex can’t see your logs. Bring the context.

Use full-auto for repetitive work

codex --full-auto "Update all deprecated API calls to use the new SDK format"

Mechanical, well-understood changes are exactly what full-auto is for.

Plan complex work first

“Before writing any code: outline your approach to adding multi-tenant support to the auth system. List the files you’ll touch.”

Ask for a plan before execution on anything with real blast radius.

Enforce your standards in AGENTS.md

Anything you’ve said twice in a prompt belongs in AGENTS.md. That’s the rule.

Agentic Mode — Letting Codex Run

When you trust it:

# Run in full-auto, let it go
codex --full-auto "Run the full test suite, fix any failures, and output a summary"

Make it safe:

Write AGENTS.md first — especially the “never do this” rules
Work in a branch, not main
Scope the task tightly — vague = chaos
Review the diff before you merge (git diff HEAD)

Quick Reference

codex                               Start interactive session
codex "task"                        One-shot task
codex --full-auto "task"            Full autonomous mode
codex --approval-mode auto-edit     Edit files freely, ask before shell
codex -m o3 "task"                  Use most capable model
codex -q "task"                     Quiet/headless output
codex --no-project-doc              Ignore AGENTS.md
codex --context file.ts "task"      Attach a file to context
codex --image screen.png "task"     Attach an image
codex --config                      Show config file location

Three Rules

1. Write AGENTS.md first. Before you run Codex on any real project, write the context file. Especially the “never do this” list. It compounds.

2. Scope every task. “Fix the bug” is an invitation to chaos. “Fix the JWT expiry logic in src/auth/session.ts” is a task.

3. Branch before full-auto. git checkout -b codex/fix-thing, run it, review the diff, merge or discard. Never let full-auto loose on main.