Codex CLI guide for real codebase work
A practical Codex CLI workflow for reading a repo, changing code, checking tests and keeping changes small.
Quick answer
A good Codex CLI workflow is simple: read project instructions, inspect the code path, make the smallest useful change, run the local checks and summarize what changed with file references.
The operating loop
Start with fast repo search, then read the closest files before editing. After each change, run the narrowest check that proves the behavior and only widen the test scope when the risk is real.
What makes it reliable
Reliability comes from bounded edits, explicit assumptions, non-destructive git behavior, and refusing to hide failing migrations, tests or security checks.
FAQ
Should Codex edit before reading the codebase?
No. The agent should inspect local patterns first, then make changes that fit the existing architecture.
What is the best first check after a code edit?
Run the narrowest relevant check first: a unit test, type-check, pSEO check or lint command depending on what changed.
Learn the workflow
Related guides
Claude Code Plan Mode: A Practical Guide
Claude Code Plan Mode lets you review and steer a task plan before any file is touched. Full guide: shortcut (Shift+Tab), activation, when to use it, and how to execute the plan.
Most people use Claude Code like a chat: describe the task, watch it execute. That works for small changes. For anything touching more than two files, there's a better path. If you are looking for the shortcut, press Shift+Tab to toggle Plan Mode. To turn it off, press Shift+Tab again or use /plan only for the prompt that needs planning. The dedicated Plan Mode troubleshooting guide covers the common terminal and version issues. Plan Mode. What Plan Mode does When you activate Plan Mode, Claude reads your codebase and produces a step by step execution plan but makes no changes. You see exactly what it intends to do before a single file is written. This gives you a checkpoint: approve the plan, redirect it, or catch a wrong assumption before it cascades into 15 wrong edits. How to activate Plan Mode the shortcut Two ways: Keyboard shortcut : press Shift+Tab…
Read the guide5 Claude Code Hooks I Use Daily
Claude Code hooks run shell commands on session start, file writes, and tool calls. Here are the 5 I use daily and how to configure them.
Most people discover Claude Code for the AI. They miss the hooks. Hooks are shell commands that execute automatically when something happens in your Claude Code session: a session starts, a tool runs, Claude stops. You define them in .claude/settings.json . They run silently in the background. Here are the 5 I use every day. What hooks look like The available events: SessionStart , UserPromptSubmit , PreToolUse , PostToolUse , Stop . Hook 1 Auto inject date on every prompt Event : UserPromptSubmit Claude doesn't have real time awareness. Every prompt gets the current date injected automatically. Useful for anything time sensitive: changelogs, deadlines, scheduling logic. Hook 2 Push notification when Claude stops Event : Stop Long tasks (refactors, test runs, analysis) can take 2–5 minutes. Without a notification I'd either stare at the screen or miss the result. This fires whenever Claude finishes a task, whether it succeeded or…
Read the guideCLAUDE.md: A Guide for Every Developer
One markdown file that makes AI coding assistants actually understand your codebase. Here's what to put in it.
There's a reason Claude Code writes great code in some projects and generic boilerplate in others. It's not the model. It's CLAUDE.md . It is one part of my Claude Code workflow: project conventions reduce guesswork, but they do not guarantee a speedup or remove the need to review the change. What it is CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session. Think of it as the onboarding doc you'd give a senior contractor on day one: stack, conventions, rules, context. Without it, Claude infers patterns from what it sees in the codebase. Sometimes it infers correctly. Often it doesn't especially for implicit conventions your team just "knows". With a good CLAUDE.md , Claude outputs code that follows your rules without being told each time. What to put in it 1. Stack and versions Simple but important. Claude will use the right…
Read the guide