Agents.md

Terminal-Based AI Coding

OpenAI Codex CLI

A powerful command-line tool that brings AI-assisted coding directly to your terminal, helping you build features, fix bugs, and understand unfamiliar code without leaving your workflow.

Explore Features Quick Start Guide

Core Features

Key Features of OpenAI Codex CLI

Discover how Codex CLI enhances your development workflow with powerful AI capabilities

Zero-Setup Installation

Get started with just a simple npm install command. Codex CLI is designed to integrate seamlessly into your existing development environment without complex configuration.

The tool works right out of the box, requiring only an OpenAI API key to begin enhancing your coding workflow with AI assistance directly in your terminal.

Flexible Approval Workflows

Choose from three different modes of operation based on your comfort level. From suggestion-only mode where you approve every change, to fully automated mode for hands-off operation in a sandboxed environment.

Multi-Modal Input

Support for text, screenshots, or diagrams as input, allowing AI to generate or edit code based on visual content.

Terminal-Native

Fully operates within your terminal, eliminating context switching for a streamlined workflow.

Security & Control

Approval Modes

Choose the level of autonomy that works for you with three flexible approval workflows

Mode	What the Agent Can Do	When to Use
Suggest (default)	Read files. Proposes edits & shell commands, but requires your approval before making changes or executing commands.	Safe exploration, code reviews, learning a codebase.
Auto Edit	Read and write files automatically. Still asks before running shell commands.	Refactoring or repetitive edits where you want to keep an eye on side-effects.
Full Auto	Read, write, and execute commands autonomously inside a sandboxed, network-disabled environment scoped to the current directory.	Longer tasks like fixing a broken build or prototyping features while you grab a coffee.

Getting Started

Quick Start Guide

Get up and running with OpenAI Codex CLI in minutes

Installation

npm install -g @openai/codex

Next, set your OpenAI API key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Note: This command sets the key only for your current terminal session. You can add the export line to your shell's configuration file (e.g., ~/.zshrc) but we recommend setting for the session.

Running Codex CLI

Run interactively:

codex

Or, run with a prompt as input:

codex "explain this codebase to me"

Run in Full Auto mode:

codex --approval-mode full-auto "create a todo-list app"

Practical Examples

Usage Examples

See how Codex CLI can help with common development tasks

Refactor Components

codex "Refactor the Dashboard component to React Hooks"

Codex rewrites the class component, runs npm test, and shows the diff.

Generate SQL Migrations

codex "Generate SQL migrations for adding a users table"

Infers your ORM, creates migration files, and runs them in a sandboxed DB.

Write Unit Tests

codex "Write unit tests for utils/date.ts"

Generates tests, executes them, and iterates until they pass.

Bulk Rename Files

codex "Bulk-rename *.jpeg -> *.jpg with git mv"

Safely renames files and updates imports/usages.

Technical Details

System Requirements

Make sure your system meets these requirements before installing

Requirement	Details
Operating System	macOS 12+, Ubuntu 20.04+/Debian 10+ or Windows 11 (via WSL2)
Node.js	Version 22 or newer (LTS recommended)
Git (optional)	Version 2.23+ for built-in PR helper
RAM	Minimum 4GB (8GB recommended)

Advantages & Limitations

Pros and Cons

Understanding the strengths and limitations of OpenAI Codex CLI

Advantages

Zero Setup: Works instantly with just an OpenAI API key, no complex configuration required.
Security: Runs in a network-disabled and directory-sandboxed environment for enhanced security.
Multi-modal: Can accept screenshots or diagrams as input to implement features based on visual content.
Open Source: Fully open source, allowing users to inspect and contribute to the code.

Limitations

Windows Support: No direct Windows support, requires WSL2 for Windows users.
API Key Required: Requires an OpenAI API key and associated costs for usage.
User Intervention: May require user intervention in complex scenarios.
Learning Curve: Terminal-based interface may have a learning curve for developers not familiar with command-line tools.