Getting started with Codex

This session provides a comprehensive guide to getting started with OpenAI Codex, an AI coding agent designed to enhance developer productivity by automating routine tasks. Codex operates across multiple surfaces, including a CLI for terminal interactions, a VS Code-based IDE extension for a rich graphical experience, and cloud environments for running asynchronous, parallel tasks.

Core Concepts and Models

Codex is powered by OpenAI’s state-of-the-art models, such as GPT-5.1 Codex Max, which is specifically trained for agentic coding in the Codex CLI harness. These models are continuously improved for speed, efficiency, and the ability to generate production-ready code. They are natively trained in Linux, macOS, and Windows environments, ensuring reliability in both bash and PowerShell while adhering to sandboxing rules. A key feature is the model’s ability to auto-compact long conversations, making it suitable for large-scale, long-running tasks like major refactoring projects.

Installation and Setup

Getting started with Codex involves two main steps:

1. CLI Installation: The recommended method is via brew or npm, as these package managers provide the most up-to-date versions. The CLI will notify you when a new version is available. Alternatively, binaries are available on GitHub.
2. IDE Extension: The official OpenAI Codex extension can be installed from the VS Code Marketplace. It’s recommended to enable auto-updates to access the latest features.

After installation, you log in using your work email or SSO via the codex login command in the terminal or the sign-in prompt in the IDE. This authenticates you for both surfaces. You can check your session status with the /status command.

The agents.md File: Providing Context

Since coding agents are stateless between sessions, the agents.md file is crucial for providing persistent context. Codex automatically loads this file from the current directory, giving the agent a TL;DR on the project.

Key aspects of agents.md:

• Creation: Use the /init command in the CLI to auto-generate a file. You can have a global agents.md in your home folder for universal instructions and repo-specific ones in project roots or subdirectories.
• Content: Common sections include project overview, file structure, build/test commands, CLI tools, and implementation workflows.
• Best Practices: Keep it brief (under 100 lines is typical), focus on unlocking agentic loops by providing feedback mechanisms (linters, tests), and update it continuously as the project evolves.
• Progressive Discovery: Use agents.md to point to other task-specific documentation (e.g., execplans.md, frontend.md, architecture.md). This allows the agent to progressively load more context as needed for complex tasks, like a multi-hour refactor, by following a structured plan.

Configuration with config.toml

Further customization is possible through the config.toml file (Codex CLI is written in Rust). This file allows you to set defaults for:

• Model: The default model and reasoning effort.
• Sandbox and Approval: The sandbox_mode (e.g., workspace_write) and approval_policy (e.g., on_request).
• Features: Toggle features like web_search or terminal notifications.
• Profiles: Create different configuration profiles (e.g., a ‘fast’ profile for quick tasks) that can be invoked with codex -p <profile_name>.
• MCPs: Configure Model-facing Co-processor servers.

Prompting Best Practices

Effective prompting is key to getting the best results from Codex.

• Anchor the Agent: Use @-mention to point Codex to specific files to focus its attention.
• Start Small: Begin with smaller, verifiable tasks and gradually ramp up to more complex ones. You can even ask Codex to break down a large feature into smaller tasks.
• Include Verification: Provide steps for Codex to check its work, such as running tests or linters.
• Debugging: Paste the full stack trace directly into the prompt for effective bug fixing.
• Brainstorm: Use open-ended prompts to brainstorm feature improvements or performance optimizations.

CLI and IDE Tips

• Image Prompts: Provide screenshots in your prompt to give visual context, which is often easier than describing UI elements textually.
• To-Dos: In the IDE, write // TODO comments and click “Implement with Codex” to have the agent complete the task.
• Resume Sessions: Use codex resume in the CLI to continue a previous conversation, preserving valuable context.
• Mermaid Diagrams: Ask Codex to generate a Mermaid sequence diagram to visualize a codebase’s operational flow.
• Custom Commands: Create .md files in a prompts folder within your Codex home directory (e.g., @test.md) to define reusable, complex commands like generating unit tests.

Advanced Workflows and MCPs

Model-facing Co-processors (MCPs) are a protocol for connecting models to external tools and context. Codex supports standard I/O and HTTP transport for MCPs, enabling integrations with services like Figma, Jira, Linear, and DataDog. A key example is Context Seven, an MCP that provides up-to-date documentation for external libraries and frameworks, overcoming the model’s knowledge cutoff.

Programmatic Use and Headless Mode:

• codex exec: Run Codex in headless mode for programmatic use in CI/CD pipelines. You can provide a structured output schema (JSON) to get parseable results for tasks like code quality analysis or security triage.
• Agents SDK: Integrate Codex with the OpenAI Agents SDK to build complex, multi-agent workflows. You can create specialized agents (e.g., frontend, backend, PM) that hand off tasks to each other, with Codex acting as a tool for code implementation.
• Custom Automations: Build powerful automations like on-prem code review, auto-fixing CI failures by having Codex check out the branch and push a fix, or auto-labeling GitHub issues based on their content.

• Tags:
• Code Generation
• Prompt Engineering
• Developer Tools
• MCP
• AI Agent
• CLI
• Agents SDK
• Code Review
• OpenAI Codex
• AGENTS.md
• Config.toml
• VS Code Extension