Getting started with Codex

A step-by-step walkthrough on getting started with OpenAI's Codex. This guide covers installation of the CLI and VS Code extension, configuration using `agents.md` and `config.toml`, effective prompting patterns, and advanced workflows like using the Model-Connectable Protocol (MCP) and the OpenAI Agents SDK for programmatic automation.

January 12, 2026 4 min read

Getting started with Codex — source: https://www.youtube.com/watch?v=px7XlbYgk7I

This video provides a comprehensive walkthrough of OpenAI’s Codex, an AI coding agent designed to augment the software development lifecycle. The session is aimed at developers and covers everything from initial setup to advanced programmatic workflows.

Introduction to Codex

Codex is presented as an AI coding agent available across multiple surfaces: a command-line interface (CLI) for lightweight tasks, a Visual Studio Code IDE extension for a rich graphical experience, and cloud environments for running asynchronous, parallel tasks. It is powered by OpenAI’s state-of-the-art models, specifically GPT-5.1 Codex Max, which is optimized for agentic coding. The models are trained on Linux, macOS, and Windows environments and are designed to handle long-running tasks like large-scale refactoring by auto-compacting long conversations.

Installation and Setup

Installation: The recommended way to install the Codex CLI is via brew or npm, as these methods provide the most up-to-date versions. The VS Code extension can be installed directly from the marketplace, and enabling auto-updates is advised.
Authentication: Users can sign in with their ChatGPT Enterprise account using the codex login command in the CLI, which authenticates them for both the CLI and IDE extension, often via an internal SSO.

Core Concepts: Context and Configuration

agents.md: This file is crucial for providing context to Codex, which is stateless between sessions. It acts as a specialized README that Codex automatically loads. Best practices include keeping it brief (under 100 lines), focusing on unlocking agentic loops (e.g., providing test and lint commands), and continually updating it. You can have a global agents.md in your home folder, a project-specific one in the repo root, and even subdirectory-specific ones. It can also point to other documentation files (execplans.md, architecture.md) to enable progressive discovery for complex tasks.
config.toml: This configuration file, written in TOML, allows users to customize default behaviors. You can set the default model, reasoning effort, sandbox mode, and approval policies. It also supports creating profiles (e.g., a fast profile for quick tasks) and configuring Model-Connectable Protocol (MCP) servers.

Prompting and Interaction

Effective prompting is key to getting the most out of Codex. Key techniques include:

Using @mention to point Codex to specific files to anchor its focus.
Starting with small, verifiable tasks before scaling to larger ones.
Providing verification steps like test commands or explicit requirements.
Pasting full stack traces for debugging.
Using image-based prompts to specify UI changes.
Resuming previous sessions via codex resume to retain context.
Generating Mermaid sequence diagrams to visualize code flow.

Advanced Features and Workflows

Model-Connectable Protocol (MCP): MCP allows Codex to connect to external tools and data sources. The video demonstrates connecting to a custom “cupcake” server and using the Context Seven MCP to fetch up-to-date API documentation, which is crucial since model knowledge has a cutoff date.
Custom Commands: Users can create custom commands, like an @test.md file in a prompts folder, to automate tasks such as generating unit tests for changed files.
Code Review: Codex can perform code reviews against a base branch or uncommitted changes. It’s trained to focus on critical P0/P1 issues to avoid being noisy, and it can be guided by a code-review-guidelines.md file.
Headless Mode and SDK: For programmatic use, codex exec runs Codex in a headless mode. Combined with a structured output schema (JSON), it enables reliable integration into automated pipelines. This can be used for security triage, test coverage bots, and release hygiene.
OpenAI Agents SDK: The video introduces using the Agents SDK to build multi-agent workflows where Codex acts as a specialized tool called by other agents (e.g., a frontend-agent or pm-agent), enabling complex, controlled rollouts for large features.