Open Codex CLI Documentation

The repository includes several demonstration examples for different use cases:

• camerascii: Converts a webcam feed into animated ASCII art.
• build-codex-demo: Recreates the original 2021 Codex YouTube demonstration.
• impossible-pong: A game where Codex dynamically creates increasingly difficult levels.
• prompt-analyzer: A data science application designed for clustering prompts.

Codex CLI examples are organized into self-contained directories. Each example follows a specific structure to facilitate repeatable runs and task definitions:

• run.sh: A helper script that automates the setup of a new session.
• task.yaml: The task specification containing the prompt passed to Codex.
• template/ (optional): Starter files or markdown instructions that Codex reads before beginning the task.
• runs/: The directory where work is performed and outputs are stored, created by run.sh.

For large-scale tasks, you can grant Codex more autonomy to plan and track progress. A recommended pattern is to create a .codex/ directory in your working directory to serve as a shared workspace for the agent.

Best Practices for Large Tasks:

• Seed the project with a high-level requirements document.
• Instruct Codex to create and update dated plan files (e.g., .codex/plan_2025-04-16.md) to track milestones.
• Ask Codex to update the README.md with a dated changelog as it completes significant work.

Note: The .codex/ directory is not a special-cased configuration directory; it is treated as a standard project directory used for managing shared state between you and the agent.

When running the prompt clustering analysis, visual representations of the data are generated in a plots/ directory. These include:

• Bar charts: Showing the relative sizes of each cluster.
• t-SNE scatter plots: Visualizing the high-dimensional prompt data in 2D space, with points colored by their assigned cluster.

Open Codex can ingest project-specific instructions to guide its behavior. It merges Markdown instructions in the following priority order (highest priority first):

1. ~/.codex/instructions.md — Personal global guidance.
2. codex.md at the repository root — Shared project notes.
3. codex.md in the current working directory — Sub-package specifics.

To disable this feature, use the --no-project-doc flag or set the environment variable CODEX_DISABLE_PROJECT_DOC=1.

The utility generates two main types of output:

analysis.md

• Overview table: Contains cluster labels, generated names, member counts, and descriptions.
• Detailed sections: Provides five representative example prompts for every cluster.
• Special lists:
  • Noise / outliers: Items labeled -1 when using dbscan.
  • Potentially ambiguous prompts: Items that lie almost equally close to two centroids (only available when using kmeans).

plots/ directory

• cluster_sizes.png: A bar chart visualizing the number of prompts in each cluster.
• tsne.png: A visual representation of the prompt embeddings.

Once installed and configured, you can use Open Codex in several ways:

Interactive Mode

Launch the interactive REPL:

open-codex

Single Prompt Mode

Pass a prompt directly to the CLI:

open-codex "explain this codebase to me"

Full Auto Mode

Run with high autonomy. In this mode, Codex can scaffold files, run them in a sandbox, and install dependencies automatically. You must use the --approval-mode full-auto flag:

open-codex --approval-mode full-auto "create the fanciest todo-list app"

To begin using the Codex CLI, you can view the help menu or ask a direct question. For a practical demonstration, you can use Codex to generate files in a new directory. By default, Codex operates in suggest mode, where you must confirm changes (selecting "Yes (y)") until the task is complete.

# View help
codex --help

# Ask a direct question
codex "write 2-3 sentences on what you can do"

# Example task: Create a styled HTML poem
mkdir first-task && cd first-task
git init
codex "Create a file poem.html that renders a poem about the nature of intelligence and programming by you, Codex. Add some nice CSS and make it look like it's framed on a wall"

The utility embeds prompts using OpenAI, discovers groupings via unsupervised clustering, and uses ChatGPT to name and describe those clusters.

By default, running the script without arguments looks for prompts.csv, uses text-embedding-3-small for embeddings, gpt-4o-mini for labeling, and outputs results to analysis.md and a plots/ directory.

Basic usage:

python cluster_prompts.py

Codex is designed for Unix-like environments.

• macOS: Supported.
• Linux: Supported.
• Windows: Not supported directly. You must use Windows Subsystem for Linux (WSL2).
• Node.js: Requires version 22 or higher.

You can provide persistent custom instructions to Codex by creating a markdown file at ~/.codex/instructions.md. These instructions guide the AI's behavior and constraints during interactions.

# ~/.codex/instructions.md

- Always respond with emojis
- Only use git commands if I explicitly mention you should