Reading Codebases and Writing Code

The core value of Codex CLI is that it works directly with your code. It does not need you to copy and paste files into a chat window. In this lesson, you will learn how to use Codex to understand existing codebases and write new code efficiently.

What You Will Learn

• How Codex reads and indexes your project files
• Techniques for asking Codex to explain code you do not understand
• How to have Codex write new features from scratch
• How to guide Codex through multi-file changes
• Best practices for giving clear instructions

---

How Codex Reads Your Code

When you start Codex in a project directory, it automatically reads your codebase to build context. This includes:

• Project configuration — package.json, Cargo.toml, pyproject.toml, go.mod, and similar files
• Directory structure — Understanding what lives where
• Source files — Reading the actual code to understand patterns and architecture
• Documentation — README files, inline comments, and configuration docs

Codex uses this context to make informed decisions about how to write code that fits your project's style and conventions.

Exploring Unfamiliar Code

One of the most useful things Codex can do is help you understand code you did not write. Here are practical prompts for codebase exploration:

Get a High-Level Overview

codex "give me a high-level overview of this project's architecture"

Codex will scan the directory structure, read key files, and explain the overall architecture, including frameworks used, how the code is organized, and how different parts connect.

Understand a Specific File

codex "explain what src/services/payment.js does, step by step"

Codex reads the file and gives you a clear walkthrough of the logic, including what each function does and how they relate to each other.

Trace a Flow

codex "trace what happens when a user clicks the checkout button, from the frontend to the database"

This is especially powerful. Codex follows the code path across multiple files, from the UI event handler to API calls to database operations, giving you a complete picture of the flow.

Find Where Something Is Defined

codex "where is the user authentication logic implemented in this project?"

Instead of manually searching through files, Codex scans the codebase and points you to the relevant files and functions.

Writing New Code

When it comes to writing code, the quality of Codex's output depends heavily on the clarity of your instructions. Here are patterns that work well:

Be Specific About Requirements

Instead of vague instructions like:

codex "add a search feature"

Give specific requirements:

codex "add a search endpoint at GET /api/search that takes a 'q' query parameter, searches the products table by name and description using a case-insensitive LIKE query, and returns the matching products as JSON with id, name, price, and description fields"

The more specific you are about inputs, outputs, and behavior, the better the result.

Reference Existing Patterns

Codex understands your codebase, so you can reference existing code:

codex "add a DELETE /api/products/:id endpoint following the same pattern as the existing PUT endpoint in the same file"

This tells Codex to follow the conventions already established in your project.

Build Incrementally

For complex features, break the work into steps:

codex "first, create a new model file for blog posts with title, content, author, and publishedAt fields"

Then:

codex "now add CRUD API routes for blog posts, following the same patterns as the existing user routes"

Then:

codex "add input validation to the blog post routes using the same validation library used elsewhere in this project"

This incremental approach gives you checkpoints where you can review and correct course.

Multi-File Changes

Codex handles multi-file changes naturally. When a task requires changes across multiple files, Codex plans the full set of modifications before starting.

For example:

codex "add a new 'categories' feature with a database model, API routes, and update the product model to reference a category"

Codex will:

1. Create a new model file for categories
2. Create API route files for CRUD operations
3. Update the product model to include a category reference
4. Update any imports or configuration files needed

You can see all planned changes before they are applied (in Suggest mode) or review them afterward with git diff.

Best Practices for Clear Instructions

Do include:

• The specific files or areas of code you want changed
• Input/output expectations
• Error handling requirements
• References to existing patterns in your codebase
• The language or framework conventions to follow

Do not include:

• Ambiguous terms like "make it better" or "clean up the code"
• Multiple unrelated tasks in a single prompt
• Assumptions about what Codex already knows about your preferences

Good Prompt Examples

codex "add TypeScript types to the user service — define an interface for User with id (number), email (string), name (string), and createdAt (Date)"

codex "convert the callback-based file upload handler in src/upload.js to use async/await and add error handling that returns a 500 status with the error message"

codex "create a React component at src/components/UserCard.tsx that displays a user's avatar, name, and email. Use the same styling approach as the existing ProductCard component"

---

Key Takeaways

• Codex reads your project files automatically to understand structure, patterns, and conventions
• Use Codex to explore unfamiliar codebases by asking for overviews, explanations, and flow traces
• Write specific, detailed prompts that include inputs, outputs, and behavior requirements
• Reference existing code patterns so Codex follows your project's conventions
• Break complex features into incremental steps for better results
• Codex handles multi-file changes naturally, planning all modifications before executing
• Review changes with git diff after Codex finishes, especially in Auto Edit or Full Auto modes