Boost your Codex CLI productivity with scripts
lessons from two month of using codex cli every single day for 14 hours
Past two month I’ve been using Codex as a local, scriptable coding agent that can read, modify, and run code in my repo in an intelligent and efficient manner. If you just use codex as is you will get far from my own experiment of treating it like a blackbox but you will hit a wall. This guide derives from mix and match of tools and scripts that have worked best to keep you moving. I wish someone had given me these lessons
TL;DR setup
Create ~/.codex/config.toml once and forget it:
model = “gpt-5-codex”
model_reasoning_effort = “high”
approval_policy = “on-failure” # ask if a command fails
sandbox_mode = “workspace-write” # writes only inside repo
history.persistence = “save-all” # keep transcripts
file_opener = “vscode”
[profiles.safe]
approval_policy = “on-request”
sandbox_mode = “read-only”
[profiles.work]
approval_policy = “on-failure”
sandbox_mode = “workspace-write”
[profiles.yolo]
approval_policy = “never”
sandbox_mode = “danger-full-access”
[mcp_servers.context7]
command = “npx”
args = [”-y”,”@upstash/context7-mcp”]
startup_timeout_sec = 20
tool_timeout_sec = 120
Global flags you’ll actually use: --model, --profile, --sandbox, --ask-for-approval, --search, --config key=value. And codex resume when you need to pick up a prior session.
TOOLS.md for 10x’ing Codex Performance
So I posted this table over at r/codex and seems to have gotten the attention of OpenAI staff and have added git-delta to the TOOLS.md from suggestions from Joshua (great suggestion!)
---
## CLI Toolbelt
Fast, user‑friendly tools Codex prefers when available. Install with your package manager (examples shown for Homebrew):
```bash
brew install fd ripgrep ast-grep jq fzf bat eza zoxide httpie git-delta
# Optional fzf keybindings
$(brew --prefix)/opt/fzf/install --key-bindings --completion --no-bash --no-fish
```
| Tool | What it is | Typical command(s) | Why it’s an upgrade |
| -------------- | ---------------------------------------- | ------------------------------------------------ | ------------------- |
| fd | Fast, user‑friendly file finder | `fd src`, `fd -e ts foo` | Simpler than `find`, respects `.gitignore`, very fast |
| ripgrep (`rg`) | Recursive code searcher | `rg “TODO”`, `rg -n --glob ‘!dist’` | Much faster than grep/ack/ag; great defaults |
| ast-grep (`sg`)| AST‑aware search & refactor | `sg -p ‘if ($A) { $B }’` | Searches syntax, not text; precise refactors |
| jq | JSON processor | `jq ‘.items[].id’ < resp.json` | Structured JSON queries, filters, transforms |
| fzf | Fuzzy finder (any list ➜ filtered) | `fzf`, ``history | fzf`` | Fast fuzzy pickers; pairs well with `rg`/`fd` |
| bat | `cat` with syntax, paging, git | `bat file.ts`, `bat -p README.md` | Syntax highlighting, line numbers, Git integration |
| eza | Modern `ls` | `eza -l --git`, `eza -T` | Better defaults, icons/trees/git info |
| zoxide | Smart `cd` (learns paths) | `z foo`, `zi my/project` | Jumps to dirs by frecency; fewer long paths |
| httpie (`http`)| Human‑friendly HTTP client | `http GET api/foo`, `http POST api bar=1` | Cleaner than `curl` for JSON; shows colors/headers |
| git-delta | Better `git diff`/pager | `git -c core.pager=delta diff` | Side‑by‑side, syntax‑colored diffs in terminal |
Preferred defaults inside Codex
- Use `rg` for searching code and logs; fall back to `grep` only if needed.
- Use `fd` for finding files; fall back to `find` only if needed.
- Use `jq` to parse/pretty‑print JSON from APIs and logs.
- Use `httpie` for ad‑hoc API exploration; use `curl` for fine‑grained CORS/DNS tests.
- Use `timeout` to avoid running commands indefinitely and tests actually finish
- Use `git-delta` as it changes the reading order of diffs and can help with better code reads.
---AGENTS.md is superior
Put guardrails, not a manual in AGENTS.md at repo root (and optionally per package). Codex (and other agents) use it as the predictable “what to run/how to verify” source. GitHub code review with @codex review also reads your AGENTS.md review rules. Keep it terse.
Template I use:
# AGENTS.md
## Setup
- Install: pnpm i
- Dev: pnpm dev
- Tests: pnpm test
## Conventions
- TypeScript strict, no any
- Single quotes, no semicolons
## Review guidelines
- No PII in logs
- Auth middleware wraps all routes
## Troubleshooting
- If Vitest flakes on CI: rerun with `pnpm vitest --retry 2`
Anti‑patterns
Don’t @‑dump huge docs; pitch when/why to read a path.
Avoid “Never do X” without the preferred alternative.
Use AGENTS.md as a forcing function—wrap gnarly invocations behind small CLIs the agent can call.
Use Approvals
Think of posture as “how hard can Codex push.” My defaults:
Read‑only when planning or just chatting.
Workspace‑write + on‑failure approvals during local implementation.
Only flip to full access for isolated sandboxes. Use
/approvalsin TUI; persist via config.
Codex’s sandboxes (macOS seatbelt / Linux landlock) plus approval modes are worth learning; they prevent most “oops ran a curl | sh” moments.
Managing Context
No magical compaction. Make context external and durable:
Document & Clear: Ask Codex to dump its plan & current state to
docs/plan.md, then continue from that file in a fresh session.Catch‑up: Feed only the diffs after a reset.
catchup.sh
#!/usr/bin/env bash
set -euo pipefail
base=${1:-origin/main}
files=$(git diff --name-only “$base”...HEAD | tr ‘\n’ ‘ ‘)
codex exec “Read these changed files: $files.
Summarize the delta and list what’s incomplete. Do not modify code yet.”
When you’re truly done: codex resume <id> later to query “how did we fix X?” instead of re‑deriving it.
Minimal slash commands (inside the TUI)
/model— pickgpt-5-codex, bump reasoning on hard problems./approvals— flip between Read‑only / Auto / Full access./mcp— quick view of attached tools.
Keep it short; don’t build a cockpit of custom commands. (OpenAI Developers)
MCPs over “APIs”
Prefer MCP servers (stdio or HTTP) to teach Codex “how to do things” with real tools: docs, browser control, Figma, Sentry, GitHub, Playwright. Wire once in config.toml or via codex mcp add. Let the agent script against those tools instead of inventing bespoke RPCs.
# examples
codex mcp add context7 -- npx -y @upstash/context7-mcp
# then in TUI: /mcp to see connected servers
“Subagents” is just scripts
For parallelizable tasks (migrations, multi‑pkg refactors), I don’t over‑engineer. You don’t need another fancy github tool. I either:
Batch with
codex execfrom shell, in parallel, with tight prompts.Or use the TypeScript SDK to spin “threads” and orchestrate runs, resuming by thread id.
# shotgun refactor example (6 workers)
git grep -l ‘legacyFoo’ -- ‘*.ts’ \
| xargs -P 6 -n 1 -I{} codex exec \
“In {}, replace ‘legacyFoo’ with ‘newFoo’ safely.
Update imports, run the package tests, and stage only that file.”
import { Codex } from “@openai/codex-sdk”;
const codex = new Codex();
const t = codex.startThread();
await t.run(”Plan the auth revamp with checkpoints”);
await t.run(”Implement step 1 and verify tests”);
// later
await codex.resumeThread(t.id).run(”Continue with step 2”);
CI: Don’t complicate it
The Codex Exec GitHub Action runs codex exec in a hardened GH runner to autofix failures and open a reviewable PR. Start with a prompt that says “only minimal change to make tests pass,” keep sandbox_mode=”workspace-write”, and re‑run tests in‑job.
# .github/workflows/codex-autofix.yml
name: Codex Auto-Fix on CI failure
on:
workflow_run:
workflows: [”CI”]
types: [completed]
jobs:
fix:
if: ${{ github.event.workflow_run.conclusion == ‘failure’ }}
runs-on: ubuntu-latest
permissions: { contents: write, pull-requests: write }
steps:
- uses: actions/checkout@v4
with: { ref: ${{ github.event.workflow_run.head_sha }}, fetch-depth: 0 }
- uses: actions/setup-node@v4
with: { node-version: ‘20’, cache: ‘npm’ }
- name: Run Codex
uses: openai/codex-action@main
with:
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
prompt: >
Run tests, apply the smallest safe patch to make them pass, stop.
No opportunistic refactors. Explain what you changed.
codex_args: ‘[”--config”,”sandbox_mode=\”workspace-write\”“]’
- run: npm test --silent
- uses: peter-evans/create-pull-request@v6
if: success()
with:
branch: codex/auto-fix-${{ github.run_id }}
title: “Auto-fix failing CI via Codex”
Block at submit not write
You don’t need bespoke “agent hooks.” Use git hooks to gate commits and force test‑then‑commit loops:
.git/hooks/pre-commit
#!/usr/bin/env bash
set -euo pipefail
pnpm test --silent
If you want a stricter agent workflow, require a file your test script creates:
# .git/hooks/pre-commit
[ -f /tmp/codex-pre-commit-pass ] || { echo “Run tests first”; exit 1; }
Codex will happily iterate until the hook passes; far less confusing than blocking writes mid‑plan.
Use Codex Cloud stuff as much as possible
When work is independent from your local context, delegate to Codex Cloud and review diffs as PRs. You can also tag @codex review in a PR to run Codex as a reviewer; it respects your AGENTS.md Review guidelines and leaves normal review comments. Control cloud internet access via allowlists & HTTP method restrictions.
Must Use Settings
model_reasoning_effort = “high”for hairy changes.shell_environment_policyto tightly filter env vars exposed to subprocesses.history.persistence = “save-all”when you want transcripts for audits/meta‑analysis.
All live in~/.codex/config.toml.
What I don’t do
I don’t rely on opaque “auto‑compression.” I reset, then catch‑up with diffs.
I don’t create a zoo of slash commands; I fix the underlying ergonomics (CLIs + AGENTS.md).
I don’t let agents free‑range the network; tighten posture, allowlist, review diffs.
Copy‑paste starters
profiles.toml (drop into ~/.codex/config.toml)
profile = “work”
# ...the earlier config block...
resume a session
codex resume # most recent
codex resume <session> # specific
attach web search in TUI
codex --search
(Enable the native search tool for the session.)
Takeaway
Treat Codex like a junior/intermediate engineer with a strong shell: tight posture, explicit tests, tiny prompts, TOOLS.md for more advanced code/file wrangling, durable context in AGENTS.md, and automation in CI.