Skip to content

README.md

Latest commit

 

History

History
115 lines (82 loc) · 6.75 KB

README.md

File metadata and controls

115 lines (82 loc) · 6.75 KB

Codex
Home developers.openai.com/codex · GitHub
Engine name codex
CLI command codex
Instructions file AGENTS.md
Skills directory .agents/skills/

Install and authenticate:

# Install via npm
npm install -g @openai/codex

# Or via Homebrew
brew install --cask codex

# Authenticate (opens browser OAuth or prompts for API key)
codex

Requires a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan — or an OpenAI API key. Credentials are stored in the system keychain.

HAL usage:

  • Config: engine.name: "codex". Optional: engine.command, engine.model (e.g. gpt-5.1-codex-mini), engine.session (false | true | "shared" | "user"; see Session configuration), engine.sessionMsg, and the permission flags under engine.codex (see table below).
  • Invocation: codex exec -C <cwd> ... for fresh, or codex exec resume --last / codex exec resume <UUID> for session continuation.
  • Sessions: session: true or omitted = experimental per-user mode. HAL stores the user's Codex session ID in session.json, resumes with codex exec resume <UUID>, and discovers new session IDs from ~/.codex/sessions/ JSONL transcripts. session: "shared" = shared (resume --last). session: false = stateless. In "user" mode, /clear only deletes the user's local session.json; in "shared" mode, /clear still starts a fresh shared Codex session.
  • Permission flags: HAL always passes --skip-git-repo-check so Codex runs without the trusted-directory check. You can escalate via engine.codex:

Per-user Codex session recovery

HAL relies on Codex's local session files under ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl.

  • Codex writes JSONL transcript files for each session.
  • HAL matches sessions by the transcript cwd field.
  • HAL reads the real session identifier from the JSONL session_meta record when available, falling back to the rollout filename UUID only if needed.
  • On a fresh per-user run, HAL snapshots the existing matching session files before execution and then stores the newly created matching session ID after the run completes.

If HAL cannot recover a session ID after a fresh per-user run, it does not fall back to shared resume --last continuation. Instead it warns the Telegram user and keeps later messages stateless until recovery succeeds.

Field Description Default
codex.networkAccess Allow outbound network in shell commands false
codex.fullDiskAccess Unrestricted filesystem access (implies network) false
codex.dangerouslyEnableYolo Disable all sandboxing and approvals false

Higher tiers supersede lower ones. Warning: Use dangerouslyEnableYolo only in hardened environments (e.g. Docker, VMs).

  • Project file: AGENTS.md.

Filesystem access and cwd boundary

Safe by default. Codex's --full-auto mode enforces a workspace sandbox that confines write access to the working directory passed via -C <cwd>. HAL always passes this flag in the default tier, so out of the box the agent cannot write files outside the project directory.

The permission tiers and what they unlock:

Tier (config field) CLI flags added What it unlocks
Default (false/false/false) --full-auto Writes confined to cwd. No network in shell commands.
networkAccess: true --full-auto -c sandbox_workspace_write.network_access=true Same write confinement, but shell commands can make outbound network requests.
fullDiskAccess: true --sandbox danger-full-access Full read/write access to the entire filesystem. Network access implied.
dangerouslyEnableYolo: true --dangerously-bypass-approvals-and-sandbox No sandbox, no approvals. Complete unrestricted access.

Higher tiers supersede lower ones. When dangerouslyEnableYolo is set, sandbox flags and approval requirements are fully bypassed — the agent can do anything the OS user can do, including deleting files, running network calls, and modifying system paths.

Recommendation: Keep the defaults for most projects. Enable networkAccess only if the agent genuinely needs to fetch data during a task. Enable fullDiskAccess or dangerouslyEnableYolo only in isolated environments (Docker containers, VMs, ephemeral CI runners).

Available models

Last updated: 2026-03-03 — source

Codex works with any model supporting the Responses API. These are the recommended models:

Model Description
gpt-5.3-codex Most capable Codex model (recommended)
gpt-5.3-codex-spark Research preview — ChatGPT Pro only
gpt-5.2-codex GPT-5.2 optimized for agentic coding
gpt-5.2 GPT-5.2 general agentic model
gpt-5.1-codex GPT-5.1 Codex
gpt-5.1-codex-max GPT-5.1 Codex Max — long-running tasks
gpt-5.1-codex-mini GPT-5.1 Codex Mini — cost-effective
gpt-5.1 GPT-5.1
gpt-5-codex GPT-5 Codex
gpt-5 GPT-5
gpt-5-mini GPT-5 Mini — fast, cost-efficient
gpt-5-nano GPT-5 Nano — fastest, cheapest

Instruction files and precedence

Codex uses AGENTS.md (and optionally AGENTS.override.md) as the root instruction format. It builds a chain of instructions that are concatenated (merged), not “one file wins”.

Discovery order:

  1. Global: In ~/.codex (or CODEX_HOME), Codex reads AGENTS.override.md if present, otherwise AGENTS.md. Only one file at this level.
  2. Project: From the project root (usually Git root) down to the current working directory, Codex checks each directory for AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. At most one file per directory is included.

Merge behavior: All chosen files are concatenated from root downward, joined with blank lines. Content from directories closer to cwd appears later, so it effectively overrides earlier guidance. Codex stops when total size reaches project_doc_max_bytes (default 32 KiB). Empty files are skipped.

If both AGENTS.md and AGENTS.override.md exist in the same directory: Only AGENTS.override.md is used in that directory (override wins). In subdirectories you can layer e.g. root AGENTS.md + services/payments/AGENTS.override.md for payment-specific rules.

See Custom instructions with AGENTS.md.

engine:
  name: codex
  model: gpt-5.1-codex-mini
  codex:
    networkAccess: true
    fullDiskAccess: true

← Back to engines index