Setup Guide Beginner

This lesson walks you through everything you need to start using OpenAI Codex: prerequisites, connecting your GitHub repository, configuring the AGENTS.md file, setting up CI/CD, managing permissions, and running your first task.

Prerequisites

Before you can use Codex, you need:

  • ChatGPT Pro, Team, or Enterprise subscription — Codex is available to these plan tiers
  • GitHub account — Codex connects to your repositories via GitHub
  • A repository with code — Codex works best on existing projects with established patterns
  • Test suite (recommended) — Codex validates its changes by running tests

Connecting Your GitHub Repository

  1. Go to codex.openai.com

    Navigate to codex.openai.com and sign in with your OpenAI account.

  2. Connect GitHub

    Click "Connect GitHub" and authorize the OpenAI Codex GitHub App. Choose which repositories Codex can access — you can grant access to specific repos or all repos.

  3. Select a repository

    Choose the repository you want to work with. Codex will clone it and analyze the codebase structure.

  4. Verify access

    Codex needs read access to clone the repo and write access to create branches and pull requests.

✅
Tip: Start with a smaller, well-tested repository to learn how Codex works before connecting larger, more complex projects.

Configuring AGENTS.md

The AGENTS.md file is a configuration file you place in the root of your repository. It tells Codex how to set up the environment, what conventions to follow, and any special instructions.

AGENTS.md 
# AGENTS.md - Codex Configuration

## Setup
- Run `npm install` to install dependencies
- Run `npm run build` to compile TypeScript
- Environment: Node.js 20, TypeScript 5.x

## Testing
- Run tests with `npm test`
- Run linting with `npm run lint`
- All tests must pass before creating a PR

## Coding Conventions
- Use TypeScript with strict mode
- Follow the existing code style (Prettier + ESLint)
- Use functional components for React
- Write JSDoc comments for all public functions
- Use named exports, not default exports

## File Structure
- Source code: `src/`
- Tests: `src/__tests__/`
- Components: `src/components/`
- API routes: `src/api/`

## Important Notes
- Never modify `package-lock.json` manually
- Database migrations go in `migrations/`
- Do not add new dependencies without justification
💡
AGENTS.md is similar to CLAUDE.md: If you have used Claude Code, the concept is the same. It provides the AI agent with project-specific context, setup instructions, and coding guidelines so it can work effectively in your codebase.

Setting Up CI/CD

Codex validates its changes by running your test suite. Ensure your CI/CD pipeline is configured to run on pull requests:

.github/workflows/ci.yml 
name: CI
on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm test

Permissions and Access

Codex requires specific permissions to function:

Permission Required Purpose
Repository read Yes Clone and read the codebase to understand the project
Repository write Yes Create branches and push code changes
Pull request write Yes Create and update pull requests with generated changes
Issues read Optional Read GitHub issues for task context when referenced
Actions read Optional Monitor CI/CD pipeline results for validation
⚠
Security note: Codex runs in a sandboxed environment with no network access by default. It cannot access secrets, environment variables, or external services from your repository. This is by design for security.

First Task Walkthrough

Let us run through your first Codex task step by step:

  1. Open Codex

    Go to codex.openai.com and select your connected repository.

  2. Write a task

    Start with something simple. For example: "Add input validation to the user registration endpoint. Validate email format and require passwords to be at least 8 characters."

  3. Submit the task

    Click submit. Codex will begin processing — you can watch the logs in real time to see what it is doing.

  4. Monitor progress

    Watch as Codex reads your code, installs dependencies, makes changes, and runs tests. You can see terminal output and file changes live.

  5. Review the PR

    When complete, Codex creates a pull request on GitHub. Review the diff, check the test results, and approve or request changes.

Example First Task 
# Good first task for Codex:

Task: Add input validation to the POST /api/users endpoint.

Requirements:
- Validate email format using a standard regex
- Require password to be at least 8 characters
- Require username to be 3-30 characters, alphanumeric
- Return 400 with descriptive error messages for invalid input
- Add unit tests for each validation rule

Context:
- The endpoint is in src/api/users.ts
- Tests go in src/__tests__/api/users.test.ts
- Use the existing validation helper pattern from src/utils/validate.ts
← Introduction Creating Tasks →