title: "Prompting for Agents — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: [02-project-memory]
Prompting for Agents — Codex CLI
This guide covers prompting techniques specific to Codex CLI. For general prompting principles, see concepts.md in this module.
Approval Modes Shape Your Prompting Strategy
Codex CLI operates in different approval modes, and each mode changes how you should think about prompting. The mode you choose determines how much autonomy the agent has, and that directly affects how precise your prompts need to be.
Suggest Mode
In suggest mode, Codex proposes changes but does not execute them until you approve. Every file edit, every command, every action requires your explicit sign-off.
How this affects prompting: You can afford to be more exploratory. Since nothing happens without your approval, there is less risk in giving broad or experimental prompts.
Explore the codebase and suggest how to improve the error handling across all API endpoints.
What would it take to migrate from Express to Fastify? Show me the changes without making them.
These prompts would be risky in full-auto mode because the agent might start making sweeping changes. In suggest mode, they are safe — you review each proposed change and approve only what makes sense.
Suggest mode is ideal for:
- Learning a new codebase (ask the agent to explain and propose, then review)
- Exploratory refactoring (see what the agent suggests before committing to a direction)
- High-risk changes (database migrations, auth modifications, config changes)
- When you are not yet confident in the agent's judgment for your project
Auto-Edit Mode
In auto-edit mode, Codex can write files automatically but still requires approval for shell commands. This is a middle ground — file changes happen without friction, but anything that executes (tests, builds, installs) needs your approval.
How this affects prompting: Be clear about the scope of file changes, since those will happen immediately. You still have a safety net for commands.
Update all the TypeScript interfaces in src/types/ to use strict null checks. Then run the type checker to see what breaks.
The file updates happen automatically. When the agent tries to run tsc, you get a chance to review and approve.
Full-Auto Mode
In full-auto mode, Codex executes everything — file edits and commands — without asking. This is the fastest workflow but requires the most precise prompting.
How this affects prompting: Be specific and bounded. State exactly what you want, specify constraints clearly, and scope the task tightly.
Fix the failing test in tests/api/users.test.ts. The test expects a 200 status but the endpoint returns 201. Update the test assertion, don't change the endpoint.
Notice the explicit constraint: "update the test assertion, don't change the endpoint." In full-auto mode, without that constraint, the agent might choose to change the endpoint instead — both are valid fixes, but you have a preference.
Full-auto mode prompting tips:
- Always specify constraints on what should NOT change
- Scope tasks to specific files or functions
- Include your definition of "done" (tests pass, type checks pass, etc.)
- Avoid open-ended exploration — save that for suggest mode
The Sandbox and What It Means for Prompting
Codex CLI runs in a sandboxed environment that restricts network access and filesystem writes to the project directory. This sandbox protects your system but also constrains what you can ask the agent to do.
What the sandbox allows:
- Reading and writing files within your project directory
- Running commands that operate locally (tests, linters, build tools)
- Using tools and dependencies already installed in your project
What the sandbox restricts:
- Network requests (no fetching external APIs, no installing new packages from the internet)
- Writing outside the project directory
- Accessing system-level resources
How this affects prompting: Do not ask the agent to do things that require network access or system-level operations. If your task requires installing a new package, install it yourself first, then ask the agent to use it.
# This will fail in the sandbox:
"Install lodash and use it to rewrite the utility functions."
# This works (after you install lodash yourself):
"Rewrite the utility functions in src/utils.ts to use lodash. It's already installed."
When the agent encounters a sandbox restriction, it will tell you. Adjust your prompt to work within the constraints, or perform the restricted action yourself and then continue.
Multi-Turn Conversations in Codex
Codex CLI supports multi-turn conversations where each prompt builds on the previous context. This works similarly to Claude Code but with a few differences to keep in mind.
Building Context Across Turns
Turn 1: "Read through the src/api/ directory and summarize what each endpoint does."
Turn 2: "The orders endpoint is missing pagination. Add limit and offset query parameters."
Turn 3: "Good. Now add the same pagination pattern to the products endpoint."
Each turn benefits from the agent's accumulated understanding. By turn three, the agent knows your project structure, the pagination pattern you approved, and which endpoints you care about.
Keeping Sessions Focused
Codex CLI sessions work best when they stay focused on a coherent thread of work. Context accumulates with each turn, and unrelated tangents dilute the agent's focus.
If you find yourself switching topics, consider starting a new session. The cost of re-establishing context is usually less than the cost of an agent that is juggling two unrelated tasks in its memory.
Referencing Specific Files and Functions
Just like with Claude Code, explicit references are one of the most effective prompting techniques:
Look at the validateEmail function in src/utils/validation.ts. It doesn't handle international domain names. Fix it.
The OrderService class in src/services/orders.ts has a calculateTotal method that doesn't account for discounts. Update it to apply the discount rules defined in src/config/pricing.ts.
When you reference files, the agent reads them directly instead of searching the project. This is faster and eliminates the chance of it finding the wrong file.
Referencing Patterns
A powerful technique is pointing to an existing implementation as a template:
Add a DELETE endpoint for products. Follow the same pattern as the DELETE endpoint in src/api/orders.ts, including the soft-delete logic and the audit log entry.
This leverages existing code as a specification. The agent reads the referenced implementation and replicates the pattern, adapted for the new context.
Effective Prompt Patterns for Common Tasks
Bug Fix (Suggest Mode)
There's a race condition in src/services/queue.ts where two workers can pick up the same job. Investigate and suggest a fix.
In suggest mode, the agent will analyze the code, identify the race condition, and propose a fix for your review.
Bug Fix (Full-Auto Mode)
The queue processor in src/services/queue.ts has a race condition on the job claim. Add a database-level lock to ensure only one worker can claim each job. Run the existing tests to verify nothing breaks.
In full-auto mode, the prompt is more specific: it names the fix approach (database-level lock) and includes a verification step (run tests).
Feature Addition
Add a health check endpoint at GET /health that returns a JSON object with:
- status: "ok" or "degraded"
- database: result of a simple query
- uptime: process uptime in seconds
Add it in src/api/health.ts following the route registration pattern in src/api/index.ts.
Test Writing
Write unit tests for the src/services/pricing.ts module. Cover:
- Standard pricing calculation
- Discount application
- Tax calculation
- Edge cases: zero quantity, negative prices, missing product
Put the tests in tests/services/pricing.test.ts. Use the testing patterns from the existing test files.
Code Exploration
I'm new to this codebase. Walk me through how a request flows from the API endpoint in src/api/orders.ts through to the database. What services, middleware, and models are involved?
This is a great use of suggest mode — no changes needed, just analysis.
How Prompting Differs Across Models
Codex CLI can work with different underlying models, and each model has different strengths. Your prompting may need slight adjustments:
More capable models handle ambiguity better. You can be more concise and trust the model to fill in gaps. Complex multi-step tasks work well in a single prompt.
Smaller or faster models benefit from more explicit instructions. Break tasks into smaller steps, be more specific about what you want, and include examples of the desired output format when relevant.
A practical approach: start with your natural prompting style. If the results are not what you expected, add more detail. If you are consistently writing very long prompts, you might be over-specifying — try being more concise and see if the quality holds.
Tips for Getting Consistent Output
Be Explicit About Output Format
If you care about how the result looks, say so:
Add error codes to the API responses. Use the format: { "error": { "code": "AUTH_EXPIRED", "message": "..." } }
Reference Existing Conventions
Add logging to the payment service. Use the same logger and log format as src/services/orders.ts.
State What Not to Change
Refactor the database queries in src/repositories/users.ts to use parameterized queries. Don't change the function signatures — the service layer depends on them.
Include Verification Steps
Update the date formatting to use ISO 8601. After making the changes, run the test suite to check for regressions.
Use the codex.md File for Persistent Conventions
If you find yourself repeating the same instructions across sessions (coding style, preferred libraries, project-specific patterns), put them in a codex.md file at the project root. This file is automatically read at the start of each session, so conventions you document there do not need to be restated in every prompt. See Module 02 for details on project memory.
Summary
The key Codex CLI-specific techniques are:
- Match your prompting precision to your approval mode — exploratory in suggest mode, precise in full-auto mode
- Understand sandbox constraints and work within them — pre-install dependencies, avoid network-dependent tasks
- Use multi-turn conversations to build context and iterate, but keep sessions topically focused
- Reference files and existing patterns to eliminate ambiguity and leverage your codebase as a specification
- Adjust for model capabilities — more concise for stronger models, more explicit for smaller ones
- Use codex.md for persistent conventions so you do not repeat yourself across sessions
Combined with the general principles in the concepts module, these techniques will help you get reliable, high-quality results from Codex CLI across different tasks and approval modes.