Environment Setup and the Context Codex Uses

The context window is your largest lever

Codex's ability to produce correct code depends more on what context you give it than on how clearly you write the task. If Codex sees the module it's editing, the types it uses, related functions, and test cases, it has a high chance of succeeding. If you give it the task description and just the specific function to change, with no type information or examples of how it's used, Codex will guess and often guess wrong.

Think of context as a partial specification. Every line of code Codex sees is a statement of "here's what the system already does." Codex learns your naming conventions, your error-handling patterns, your type structures, and the dependencies between modules just by reading what's already there. The more carefully you curate context, the fewer retries you need.

What to include in context

Type definitions and interfaces. If your code uses TypeScript, Python type hints, or Java interfaces, Codex needs them. When Codex sees interface User { id: string; email: string; created: Date }, it learns that users have these fields and respects them. If you don't include the interface, Codex might invent its own fields or types.

Test files. Include example tests or the test suite for the module Codex is editing. Codex reads tests to understand what the code is supposed to do, what edge cases exist, and what the calling convention is. A good test file is better than a paragraph of explanation.

Related modules. If you're adding a feature to a payment handler and it depends on a customer lookup, include the customer module. Codex will see how customers are structured and can call the lookup correctly.

Patterns and conventions. Include a file or two that demonstrates your project's conventions: how you structure functions, name variables, handle errors, organize imports. One well-commented example is more useful than a style guide.

Configuration and environment. If Codex needs to know about environment variables, secrets, or build configuration, include a .env.example or a comment in your task explaining them (without the actual secrets).

What to exclude from context

Secrets and credentials. Never include API keys, database passwords, or any credentials in your context. Codex sees everything you give it and sends it to OpenAI's API. If you need to reference a secret (like an API endpoint), use a placeholder like ${API_ENDPOINT} and explain it in your task.

Generated or compiled code. If you have a build/ or dist/ directory, don't include it. It's noise and wastes your context budget. Codex cares about source code, not compiled artifacts.

Large dependencies. Don't include your entire node_modules/ directory. Codex doesn't need to see the implementation of libraries you use; it learns what they do from your type definitions and how you call them.

Unrelated modules. If you're editing the payment module, don't include the entire email module. Codex will waste context budget reading irrelevant code.

Logs and data files. Don't include .log files, database dumps, or CSV test data. These are noise.

A worked example: setting context for a cache feature

You want Codex to add a Redis cache layer to your database queries. Here's what good context looks like:

my-app/
├── src/
│   ├── database.ts        (the module to edit)
│   ├── database.test.ts   (tests for database module)
│   ├── redis-client.ts    (existing Redis setup)
│   ├── types.ts           (your TypeScript interfaces)
│   └── config.ts          (just the non-secret config)
├── .env.example           (what variables exist, no actual values)
└── CONVENTIONS.md         (how you name functions, handle errors)

What Codex will see:

In database.ts, it sees the current queries and their signatures. In database.test.ts, it sees examples of how queries are called and what they should return. In redis-client.ts, it sees how to initialize and call Redis. In types.ts, it sees what data types your queries work with. In config.ts, it sees any relevant configuration without secrets.

What Codex won't see:

The entire node_modules directory, log files, the build output, any actual API keys, or the email module (not relevant to database caching).

Codex reads all of this, sees the pattern (queries return typed objects, Redis is already set up, here's how we handle configuration), and writes a cache implementation that fits your project's style.

Structuring tests for Codex to validate changes

When Codex produces a diff, it ideally runs your test suite to check if the change is correct. For this to work, your tests need to be discoverable and runnable without manual configuration. A typical setup:

• Test files are named *.test.ts or *.test.js (so Codex can find them with a glob pattern).
• Tests run with a standard command like npm test or pytest tests/.
• Tests don't require environment variables that aren't in .env.example.
• Critical tests for the module Codex is touching are fast (under 1 second).

If your test setup requires 10 minutes of build or setup, Codex won't run it. Keep the core tests fast.

Common mistake

Giving Codex too much context in the hope that more information is always better. Codex works with a limited context window (usually 4K-8K tokens for the full input including the task, code, and response). If you give it 500KB of code, Codex truncates it, loses important details, and might produce a worse diff than if you'd carefully selected 50KB of the most relevant files. Curate, don't dump.