$catcodex-setup.md

// OpenAI Codex

OpenAI's coding agent integrated into VS Code. Budget-friendly with strong implementation capabilities. When paired with good context files, medium reasoning handles most features.

v1.0|9 sections|IDE + terminal|subscription required

01# Overview

Codex is OpenAI's AI coding agent, available as a VS Code extension. It runs tasks in a sandboxed environment, reads your codebase, proposes changes, and runs terminal commands on your behalf. With a subscription, you get direct access without managing API keys.

Sandboxed execution

Code runs in an isolated environment before applying

Full codebase context

Reads your files, understands project structure

Session-based workflow

Conversation history with task tracking per session

Multiple reasoning levels

Low, medium, high reasoning — choose per task

💡Budget-Friendly

Codex is one of the most cost-effective AI coding agents available. The Plus plan (~$20/mo) covers most development needs, and medium reasoning is sufficient for implementation tasks when you have good context files.

02# Prerequisites

OpenAI Subscription

Plus or Pro plan

Plus (~$20/mo) is enough for most tasks

VS Code

Latest version

Codex runs as a VS Code extension

⚠️Subscription Required

Codex requires an active OpenAI Plus ($20/mo) or Pro plan. It does not accept standalone API keys — authentication happens through your OpenAI account linked to VS Code.

03# Installation

Install the Codex extension from the VS Code marketplace:

Step 1: Open Extensions

Press Ctrl+Shift+X (or Cmd+Shift+X on Mac) to open the Extensions panel.

Step 2: Search for Codex

Search for "ChatGPT - Codex" by OpenAI. It should have millions of downloads.

Step 3: Install & Sign In

Click Install, then sign in with your OpenAI account when prompted.

💡Quick Access

After installation, open Codex with Cmd+Shift+I (Mac) or Ctrl+Shift+I (Windows/Linux). You can also find it via the Command Palette: search for "Codex".

04# Getting Started

Once installed, open your project in VS Code and launch Codex. The interface has three key areas:

Session List (left)

Your conversation history — one session per feature or task

Chat Window (center)

Where you give instructions and see the agent work

Code Preview (right)

Live preview of code changes and browser output

Start a new session and give Codex a task:

prompt

Read the project structure and explain what this app does.

Add error handling to all API routes in the app/ directory.

Create a React component for a user profile card with avatar, name, and role.

📌Reasoning Levels

You can switch between reasoning levels per task:
Low — fast, good for simple edits and typos
Medium — best balance for most implementation tasks
High — slower but deeper, use for complex architecture decisions

05# Agent Workflow

Codex works best with a structured workflow. Here is the recommended approach for building features:

Start a new session per feature

Each feature or task gets its own session. This keeps context focused and prevents drift across unrelated changes.

Load context first

Tell Codex to read your context files (agents.md, build plan, etc.) before it starts implementing. This drastically reduces guessing.

Use Plan mode for complex features

Switch to Plan mode (instead of Edit) for architecture decisions. Codex will produce a plan without touching code. Review it, then switch to Edit mode to implement.

Grant permissions as needed

Codex will ask for permission to run commands, read files, or modify code. Review and approve each step.

Review the output

Codex shows all modified files. Review the diffs before accepting. Use the integrated preview to test.

06# Configuration

agents.md

Codex reads the agents.md file (or .github/agents.md) at the root of your project. This file tells Codex about your project, conventions, and rules.

agents.md

markdown

# Project: My App

## Reading Order
Before any implementation, read these files in order:
1. context/project-overview.md
2. context/architecture.md
3. context/build-plan.md
4. context/code-standards.md

## Rules
- No hard-coded values; use CSS variables and tokens
- Update the progress tracker after every feature
- Run the review skill after complex implementations
- Always check library docs before using third-party packages

Reasoning Level Selection

Choose your reasoning level based on the task complexity:

LowSimple edits, typo fixes, renaming variablesCheapest

MediumFeature implementation, component creation, API routesBalanced

HighArchitecture decisions, complex debugging, refactoringMost expensive

💡Save Tokens

Medium reasoning is enough for most implementation tasks when your context files are detailed. The thinking and planning is front-loaded in your context files, so the agent just needs to execute.

07# Context Files

Context files are what make Codex (and any AI agent) dramatically more effective. Create a context/ folder in your project root with these files:

project-overview.mdWhat the product is, who it is for, what is in and out of scope

architecture.mdStack, folder structure, system boundaries, rules the agent must follow

build-plan.mdEvery feature defined, scoped, and sequenced into phases

code-standards.mdNaming conventions, error handling patterns, component structure

library-docs.mdHow you use each library in this specific project

ui-tokens.mdColors, spacing, border radius — as CSS variables, no hard-coded hex

ui-rules.mdHow the UI behaves — fonts, cards, buttons, badges, layouts

ui-registry.mdLiving document of components — updated automatically by the imprint skill

progress-tracker.mdWhat is done, what is next — updated after every completed feature

⚠️Start Simple

You do not need all 9 files on day one. Start with project-overview.md and architecture.md, then add more as your project grows. The more context you provide, the shorter your prompts become and the more consistent the output.

08# VS Code Integration

Codex has deep integration with VS Code, including some features not available in other agents:

Integrated Browser Preview

Localhost links open directly inside VS Code as tabs. No need to switch to an external browser during development.

Element Inspector

Select any element in the preview and add it to the chat. Codex gets the exact component reference, a screenshot, and the element context.

Console Log Forwarding

Add console errors directly to chat — no need to copy and paste error messages manually.

Session List

All your conversations are saved on the left panel. Return to any session to continue where you left off.

📌Pro Tip: Element + Screenshot

When you see a visual bug, use the integrated browser's element inspector to select the broken element, then click "Add element to chat". Codex gets the exact component, the screenshot, and the context — fixing the issue in a single prompt.

09# Best Practices

One session per feature

Start a new session for each feature or task. This keeps the context window focused and prevents the agent from drifting across unrelated changes.

Context files over long prompts

Invest time in context files upfront. With good context, your prompts become very short — just "implement feature 07" instead of explaining the entire codebase.

Plan mode for architecture, Edit mode for implementation

Use Plan mode to think through complex features without touching code. Once the plan looks good, switch to Edit mode and let it implement.

Medium reasoning is usually enough

When you have detailed context files, the agent does not need to think as hard. Save high reasoning for genuine architecture decisions or complex debugging.

Two subscriptions are better than one Max

Claude ($20) + Codex ($20) gives you two different agents for $40 total. Switch between them depending on the task. Context files and skills work with both.

Commit before and after sessions

Make git commits before starting a Codex session and after reviewing the output. This gives you clean rollback points.