Codex CLI Tips & Advanced Usage: From Beginner to Power User

# Batch operation pattern: use "all" but constrain the scope
Add try-catch error handling to all async functions in src/controllers/.
Pass errors to next(err). Do not modify anything in src/middleware/.

# Analyze-first pattern: reduces unintended edits
First list all functions in src/models/ that use raw SQL queries.
Wait for my confirmation before replacing them with Sequelize ORM calls.

# Constraint + output pattern: be explicit about off-limits
Refactor the OAuth callback in src/auth/passport.ts to improve readability.
Constraints: do not change function signatures, do not alter error handling, keep all function names identical.

# Progressive pattern: break big tasks into steps
Step 1 only: analyze src/legacy/ and list every function over 50 lines
with no type annotations. Do not modify any files.

# Interactive mode: slash command (this session only)
/model gpt-4.1-mini

# CLI flag (single run)
$ codex --model o4-mini "refactor the auth module"

# config.toml (permanent default)
# ~/.codex/config.toml
model = "gpt-4.1"

## Off-limits (Codex must follow these)
- Never modify the generated/ directory — files there are auto-generated
- Never directly edit prisma/schema.prisma — run migrations with `pnpm db:migrate`
- Never put business logic in route files — it belongs in services/
- Never modify .env.example or .env — secrets live there
- The Stripe webhook handler in webhooks.ts has signature verification — tell me before touching it

## Common Commands
```bash
pnpm dev          # Start dev server with hot reload, port 3000
pnpm test         # Vitest unit tests
pnpm test:watch   # Test watch mode
pnpm build        # Build production bundle
pnpm db:migrate   # Run Prisma migrations
pnpm lint         # ESLint check (must pass before commit)
```

# ❌ Too much at once
Refactor the entire src/ directory, add type annotations, optimize performance, update docs

# ✅ Break it down
# Round 1: types only
Add TypeScript type annotations to all functions in src/services/. Make no other changes.

# After confirming Round 1 is good:
# Round 2: performance only
In the files we just typed in src/services/, identify and fix performance bottlenecks. No other changes.

# ❌ Let Codex find the files itself
Find all files that handle user authentication and refactor them

# ✅ Tell it exactly where to look
Refactor the authentication logic in these specific files:
- src/api/routes/auth.ts (route layer)
- src/services/authService.ts (business logic)
- src/middleware/jwtMiddleware.ts (JWT verification)

#!/bin/bash
# Add type annotations to all untyped files
for file in src/services/*.ts; do
  echo "Processing $file ..."
  codex exec "Add TypeScript type annotations to all untyped functions in $file. No other changes."
done

#!/bin/bash
# Only run if TypeScript files changed
DIFF=$(git diff HEAD~1 --name-only '*.ts')
if [ -z "$DIFF" ]; then
  echo "No TypeScript changes — skipping"
  exit 0
fi
codex exec "Update JSDoc comments based on the TypeScript changes in git diff HEAD~1"

#!/bin/bash
set -e  # exit immediately on any failure

# codex exec returns non-zero on failure; set -e terminates the script
codex exec "Fix all ESLint errors in src/api/. Do not change logic."

# Confirm lint passes
npm run lint
echo "✓ All lint errors fixed"

# Adjust in interactive mode with slash command
/permissions

# Or set a default in config.toml
# ~/.codex/config.toml
approval_policy = "auto-edit"  # auto-approve file edits, still confirm shell commands

# These preferences apply to every project
- State the conclusion before explaining the reasoning
- Ask me before making assumptions about intent — don't guess
- Always include error handling in generated code

## My coding style
- Prefer functional patterns
- async/await over Promise.then
- camelCase variable names