.png)
5 days ago
1
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
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 = 120Global 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.
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!)
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.
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 /approvals in 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.
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.
/model — pick gpt-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)
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 serversFor parallelizable tasks (migrations, multi‑pkg refactors), I don’t over‑engineer. You don’t need another fancy github tool. I either:
Batch with codex exec from shell, in parallel, with tight prompts.
Or use the TypeScript SDK to spin “threads” and orchestrate runs, resuming by thread id.
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”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 --silentIf 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.
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.
model_reasoning_effort = “high” for hairy changes.
shell_environment_policy to 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.
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.
profiles.toml (drop into ~/.codex/config.toml)
profile = “work” # ...the earlier config block...resume a session
codex resume # most recent codex resume <session> # specificattach web search in TUI
codex --search(Enable the native search tool for the session.)
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.
