Skip to content

README.md

Latest commit

 

History

History
307 lines (226 loc) · 14.1 KB

README.md

File metadata and controls

307 lines (226 loc) · 14.1 KB
Raw

Codex CLI - Complete Technical Documentation

Comprehensive technical documentation for Codex CLI, OpenAI's terminal-based AI coding agent

Documentation Version License Status Cross-Referenced

📚 What is This?

This is a comprehensive technical documentation suite covering the implementation details and internals of Codex CLI - OpenAI's sophisticated, Rust-based terminal coding agent.

🎯 For Developers & Contributors

This documentation focuses on:

  • Internal architecture and implementation details
  • Rust source code analysis and patterns
  • System internals that official docs don't cover
  • Development guides for extending Codex

📖 For End Users

Official user documentation is available at:

🔗 Complementary, Not Competing

These docs complement official documentation:

  • Official Docs: How to use Codex (configuration, commands, features)
  • This Suite: How Codex works internally (architecture, code, patterns)

Coverage: 23 in-depth documents • 250+ pages • 300+ code examples • 50+ architecture diagrams

🚀 Quick Start

⚠️ START HERE: Official vs Custom Docs

Required Reading: 00 - Official vs Custom Documentation

Understand the difference:

  • Official Docs (OpenAI) = How to use Codex → Go to official docs
  • Custom Docs (This Suite) = How Codex works internally → You're here!

🎯 Quick Navigation

New to Codex CLI?

  1. Official Getting Started ← Start here for usage
  2. 01 - Overview ← Then read this for architecture overview
  3. 23 - Flow Diagrams ← Visual guides to understand flows

Want to Understand the Architecture?

  1. 02 - Architecture - Complete system design
  2. 23 - Flow Diagrams - Visual flow references
  3. 10 - Implementation - Core implementation patterns

Need to Configure or Deploy?

  1. Official config.md ← User configuration guide
  2. 08 - Configuration ← Internal config system details
  3. Official sandbox.md ← Security usage guide
  4. 07 - Security & Sandboxing ← Security implementation

Building Tools or Extensions?

  1. 06 - Tool System - Tool architecture deep-dive
  2. 11 - Tool Implementations - Real code examples
  3. 21 - Tool System Guide - Practical development guide

Understanding Automation (Exec Mode)?

  1. Official exec.md ← How to use codex exec
  2. 22 - Exec Mode Internals ← Implementation details

📖 Complete Documentation Index

🏗️ Architecture & Design

Understand how Codex CLI is built and why it works the way it does.

Document Description Best For
01 - Overview Introduction, capabilities, and quick start First-time users
02 - Architecture System design, components, patterns Architects, contributors
10 - Implementation Entry points, event loops, async patterns Core developers

🤖 LLM & Prompt System

How Codex processes prompts and communicates with language models.

Document Description Best For
03 - Prompt Processing Prompt lifecycle and assembly Understanding context flow
04 - LLM Integration Model clients, streaming, providers API integrations
05 - System Prompts AGENTS.md, custom prompts, hierarchy Customizing behavior

🔧 Tools & Execution

The tool system that allows Codex to take actions.

Document Description Best For
06 - Tool System Tool architecture, registry, execution Building new tools
11 - Tool Implementations Detailed tool code and examples Tool developers

🔒 Security & Configuration

How Codex stays safe and how to configure it.

Document Description Best For
07 - Security & Sandboxing Sandbox modes, approvals, safety Security auditing
08 - Configuration Config files, env vars, CLI flags Setup and deployment

💾 State & Interface

How Codex manages state and presents information.

Document Description Best For
09 - State Management Sessions, history, diff tracking Understanding state flow
12 - UI Layer Terminal UI, rendering, interactions UI development

🔌 Integration & Reference

Authentication, external integrations, and code reference.

Document Description Best For
13 - Authentication Auth flows, token management Auth integration
14 - MCP Integration Model Context Protocol support MCP server authors
15 - Code Reference File index and code navigation Finding implementations
16 - Hidden Features Undocumented commands, flags, env vars Power users, developers
17 - CLI Reference Complete CLI commands and flags Command-line users
18 - MCP Development Building MCP servers from scratch MCP developers

⚡ Advanced Topics & Practical Guides

Automation, visual references, and optimization.

Document Description Best For
19 - Performance Speed, cost, quality optimization Tuning and optimization
20 - State Management Guide Practical state management guide Session management
21 - Tool System Guide Practical tool development guide Tool creators
22 - Exec Mode Internals Non-interactive automation implementation CI/CD, scripting
23 - Flow Diagrams Complete visual flow references Understanding system flows

🎯 Documentation by Use Case

I Want To...

Understand How It Works

  1. Start with 01 - Overview for the big picture
  2. Read 02 - Architecture for system design
  3. Check 03 - Prompt Processing for request flow
  4. Explore 16 - Hidden Features for undocumented capabilities

Configure and Deploy Codex

  1. Read 08 - Configuration for all options
  2. Review 07 - Security & Sandboxing for security settings
  3. Check 13 - Authentication for auth setup

Build Custom Tools

  1. Study 06 - Tool System for architecture
  2. Review 11 - Tool Implementations for examples
  3. Reference 15 - Code Reference for finding code

Customize Behavior

  1. Read 05 - System Prompts for prompt customization
  2. Learn about AGENTS.md files and custom prompts
  3. Check 08 - Configuration for behavior settings
  4. Discover 16 - Hidden Features for experimental flags and env vars

Integrate with External Systems

  1. Review 14 - MCP Integration for MCP protocol
  2. Check 04 - LLM Integration for provider support
  3. Study 13 - Authentication for auth patterns

Contribute to Development

  1. Read 02 - Architecture for design patterns
  2. Study 10 - Implementation for core code
  3. Review 15 - Code Reference for navigation

🎓 Learning Paths

Path 1: User → Power User

For those who want to use Codex effectively:

  1. 01 - Overview - Learn the basics
  2. 08 - Configuration - Customize your setup
  3. 05 - System Prompts - Create custom prompts
  4. 16 - Hidden Features - Unlock undocumented capabilities
  5. 07 - Security & Sandboxing - Understand safety

Path 2: Developer → Contributor

For those who want to contribute code:

  1. 02 - Architecture - Understand the design
  2. 10 - Implementation - Core implementation details
  3. 09 - State Management - How state works
  4. 06 - Tool System - Tool architecture
  5. 11 - Tool Implementations - Tool examples

Path 3: Architect → Integrator

For those building on top of Codex:

  1. 02 - Architecture - System design
  2. 04 - LLM Integration - API integration
  3. 14 - MCP Integration - MCP protocol
  4. 13 - Authentication - Auth patterns
  5. 06 - Tool System - Extension points

📊 Documentation Stats

  • Total Documents: 23 comprehensive guides
  • Total Words: ~120,000 words
  • Code Examples: 300+ with syntax highlighting
  • Architecture Diagrams: 50+ ASCII art flow diagrams
  • Tables & References: 80+ comparison tables
  • Cross-References: 200+ internal links (+ official docs)
  • Coverage: Architecture, Tools, Security, Config, State, UI, Integration, Hidden Features, CLI Reference, MCP Development, Performance Tuning, Exec Mode, Flow Diagrams

🛠️ Technical Details

What's Documented

  • ✅ Complete Architecture - Every component and interaction
  • ✅ All Tools - Full tool system with implementation details
  • ✅ Security Model - Sandboxing, approvals, and safety mechanisms
  • ✅ Configuration - Every config option and environment variable
  • ✅ Prompt System - How prompts are processed and customized
  • ✅ State Management - Sessions, history, and diff tracking
  • ✅ LLM Integration - All supported providers and APIs
  • ✅ MCP Protocol - Model Context Protocol integration

Based On

  • Codex Version: Latest development build
  • Analysis: 150+ source files, 50,000+ LOC examined
  • Rust Components: codex-rs/core/, codex-rs/cli/, codex-rs/tui/
  • System Prompts: All official prompts analyzed
  • Validation: All code examples from actual source

🤝 Contributing

Found an issue or want to improve the docs?

  1. For Documentation Issues: Open an issue describing what's unclear or incorrect
  2. For Code Questions: Check 15 - Code Reference first
  3. For Feature Requests: See 02 - Architecture to understand design constraints

📋 Version Information

Property Value
Documentation Version 2.0.0 (Enhanced)
Codex CLI Version Latest Development
Last Updated October 25, 2025
Format GitHub-flavored Markdown
Cross-Referenced ✅ Linked to official docs
Verified ✅ Code examples checked against source

📄 License

Documentation: Technical analysis provided as-is
Codex CLI: Apache License 2.0 © OpenAI

🔗 Quick Links

Official Resources

Analysis Documents

Navigation Guides

🎯 Where to Start?

Choose your path:

  1. I'm a new user → Official Getting Started first, then 01 - Overview

  2. I want to understand internals → 23 - Flow Diagrams then 02 - Architecture

  3. I'm building tools/extensions → 06 - Tool System and 11 - Tool Implementations

  4. I'm setting up CI/CD → Official exec.md then 22 - Exec Mode Internals

  5. I want to see comparisons → Official vs Custom Comparison

Ready to dive in? Start with 23 - Flow Diagrams for visual overviews, or 01 - Overview for architecture introduction!