codex developer-tools guides tips tutorial

Codex CLI Tips and Workflows to Get You Started

Practical tips, workflows, and configuration tricks for getting the most out of OpenAI's Codex CLI. Covers AGENTS.md setup, approval policies, cloud sandboxes, GitHub integration, and power-user techniques.

Karl Wirth ·

Codex CLI is powerful out of the box. But most developers use maybe 30% of what it can do. This guide covers the tips, configuration options, and workflow patterns that separate casual users from power users.

Setting Up for Success

AGENTS.md: Give Codex Context

The single highest-impact thing you can do is create an AGENTS.md file at your project root. This is the Codex equivalent of Claude Code’s CLAUDE.md — persistent instructions the agent reads at the start of every session.

# AGENTS.md

## Project Overview
This is a Next.js 14 app with TypeScript, Tailwind CSS, and Prisma ORM.

## Architecture
- `/app` — App Router pages and API routes
- `/lib` — Shared utilities, database client, auth helpers
- `/components` — React components (use shadcn/ui patterns)
- `/prisma` — Database schema and migrations

## Conventions
- Use TypeScript strict mode. No `any` types.
- API routes return `{ data, error }` shape.
- Components use named exports, not default exports.
- Tests go next to source files: `foo.ts` → `foo.test.ts`

## Common Patterns
- Database: Always use `prisma` client from `/lib/db.ts`
- Auth: Check `getServerSession()` in API routes
- Errors: Throw `AppError` from `/lib/errors.ts`, not generic Error

## Do NOT
- Add dependencies without asking
- Modify the Prisma schema without migration instructions
- Use `console.log` for debugging — use the logger from `/lib/logger.ts`

A good AGENTS.md reduces the number of correction prompts you need by 50%+. Update it as your project evolves.

Cascading Configuration

Codex supports cascading AGENTS.md files. A root-level file provides global context, and subdirectory files add specific instructions:

project/
├── AGENTS.md              ← Global conventions
├── frontend/
│   └── AGENTS.md          ← Frontend-specific instructions
└── backend/
    └── AGENTS.md          ← Backend-specific instructions

Codex merges all applicable AGENTS.md files for the current working directory.

Approval Policies

Codex has three approval modes that control how much autonomy the agent has:

Suggest Mode (Default)

codex --approval-mode suggest

Codex proposes changes and waits for your approval before every action. Safest, but slowest.

Auto-Edit Mode

codex --approval-mode auto-edit

Codex can read files and edit code automatically, but asks permission before running commands. Good balance of speed and safety.

Full-Auto Mode

codex --approval-mode full-auto

Codex runs everything without asking — file edits, commands, installations. Fastest, but use with caution. Best combined with git worktrees so you can review and revert easily.

Recommendation: Start with auto-edit for most work. Use full-auto only in isolated worktrees where the worst case is “delete the worktree and start over.”

GitHub Integration Workflows

Codex’s native GitHub integration is one of its strongest features.

Issue-to-PR Workflow

# Start from a GitHub issue
codex "Implement the feature described in issue #142. When done, create a PR."

Codex reads the issue, implements the feature, creates a branch, commits, pushes, and opens a PR. One prompt, complete workflow.

PR Review Response

When you receive code review comments on a Codex-generated PR:

codex "Address the code review comments on PR #87. Read the comments and make the requested changes."

Codex reads the review comments, makes the fixes, and pushes updated commits.

CI Fix Loop

codex "PR #87 has failing CI checks. Read the error logs and fix the issues."

Codex reads the CI output, identifies the failures, and fixes them. Particularly useful for linting errors, type errors, and test failures that the agent introduced.

Cloud Sandbox Delegation

One of Codex’s unique features: you can delegate tasks to cloud sandboxes that run independently.

From ChatGPT

In the ChatGPT web interface:

  1. Describe the task
  2. Select “Use Codex” (or it will suggest Codex for coding tasks)
  3. Codex spins up a cloud sandbox, clones your repo, and works on it
  4. Results are available as a PR or patch

Benefits

  • Async: You don’t need your terminal open. Fire and forget.
  • Isolated: Each sandbox is a fresh environment. No worktree management needed.
  • Parallel: Delegate 5 tasks simultaneously from ChatGPT.

Limitations

  • Latency: Cloud sandboxes have startup time (30–60 seconds)
  • No local state: Can’t access local databases, running servers, or local tools
  • Limited debugging: If something goes wrong, you can’t inspect the sandbox interactively

Power-User Tips

Tip 1: Structured Prompts

Give Codex structured prompts with clear deliverables:

Task: Add user profile editing

Requirements:
1. API endpoint: PUT /api/users/:id
2. Input validation: name (string, 1-100 chars), bio (string, max 500 chars)
3. Authorization: users can only edit their own profile
4. Frontend: form component at /settings/profile

Tests:
- Unit tests for the API endpoint
- Integration test for the full flow

Constraints:
- Use existing auth middleware from /lib/auth.ts
- Follow existing API response shape from /lib/api-response.ts

This style of prompt produces consistently better output than “add user profile editing.”

Tip 2: Use Codex-Mini for Simple Tasks

codex --model codex-mini "Fix the TypeScript errors in src/components/Header.tsx"

Codex-mini is faster and cheaper for straightforward tasks. Save the full model for complex work.

Tip 3: Session Persistence

Codex sessions maintain history. If you need to iterate:

codex  # Start a session
> "Add a users API endpoint"
# ... agent works ...
> "Now add pagination to that endpoint"
# ... agent builds on previous context ...
> "Add rate limiting"
# ... continues building ...

Each follow-up prompt has the full context of what came before.

Tip 4: Dry Runs

codex --approval-mode suggest "Refactor the payment module to use the strategy pattern"

In suggest mode, Codex shows you everything it plans to do without executing. Review the plan, then either approve or adjust your prompt.

Tip 5: Combining with Claude Code

Many developers use both Codex and Claude Code. A practical pattern:

  1. Use Claude Code for the complex reasoning tasks (architecture decisions, complex refactors)
  2. Use Codex for execution tasks (implementing well-defined features, CI fixes, PR management)

Tools like Nimbalyst let you run both on the same kanban board, routing tasks to the right agent. You can also have one agent supplement or check the other’s work: let Codex scaffold a feature quickly, then have Claude Code review the implementation for edge cases and security issues. Or use Claude Code to architect a solution, then hand the implementation plan to Codex for execution.

Common Codex Gotchas

1. Dependency Installation

Codex in full-auto mode may install packages without asking. If you don’t want surprise dependencies:

# Use auto-edit mode — it can edit files but asks before running npm install
codex --approval-mode auto-edit

Or add to your AGENTS.md:

## Do NOT
- Install new npm packages without listing them first and getting approval

2. Overly Eager Formatting

Codex sometimes reformats files beyond what you asked for. To prevent:

# In AGENTS.md
## Style
- Do NOT reformat existing code. Only change lines directly related to the task.
- Respect existing formatting, even if it doesn't match your preferences.

3. Test Framework Assumptions

Codex may assume Jest when you use Vitest, or Mocha when you use Pytest. Specify in AGENTS.md:

## Testing
- Test framework: Vitest (not Jest)
- Run tests: `npm run test`
- Test files: `*.test.ts` next to source files

Workflow: Daily Codex Routine

A productive day using Codex:

Morning:

  1. Review overnight cloud sandbox results (if you delegated tasks)
  2. Start a Codex session for the day’s main feature
  3. Delegate small bug fixes to cloud sandboxes

During development: 4. Use auto-edit mode for focused feature work 5. Switch to suggest mode when working on sensitive code (auth, payments) 6. Use Codex-mini for quick fixes and formatting tasks

End of day: 7. Create PRs for completed work 8. Delegate overnight tasks to cloud sandboxes 9. Review and merge PRs from earlier sessions

Verdict

Codex CLI rewards investment in configuration. A well-written AGENTS.md, the right approval mode, and structured prompts make the difference between “it works sometimes” and “it ships features reliably.”

The biggest unlock is combining Codex’s speed with proper guardrails — auto-edit mode for safety, AGENTS.md for conventions, worktrees for isolation. Once those are in place, Codex becomes a genuine multiplier.