Codex CLI is a coding agent from OpenAI that runs locally on your computer. This `apohl79/codex` fork tracks upstream Codex on `main-fork` with substantial agent improvements: persistent task lists, cross-model sub-agent routing, active-agent UI, multi-provider error handling, and TUI productivity enhancements.

If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE.
If you want the desktop app experience, run codex app or visit the Codex App page.
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex.

---

Quickstart

Installing and running this fork

Install the latest apohl79 fork release on macOS:

curl -fsSL https://raw.githubusercontent.com/apohl79/codex/main-fork/scripts/install/install-apohl79.sh | bash

Or clone and build from main-fork on macOS or Linux:

git clone --branch main-fork https://github.com/apohl79/codex.git && cd codex/codex-rs && cargo install --locked --path cli

Then simply run codex to get started.

Fork features

• Plugin context declarations in plugin.json for permanent, position-aware model instructions injected via ContextContributor — zero-overhead replacement for hook-based periodic reminders (preamble/supplement slots relative to AGENTS.md, see Plugin Context below).

• Extended TUI @ file-path completion.

• Custom TUI status line support.

• Active agent and active thread context in the bottom pane.

• TUI session names shown at the top-right of the user entry box.

• Automatic short session names with a /rename --auto on|off toggle and /rename override.

• Persistent active task list above the user entry field while a turn is running.

• Optional hook output rendering with quieter default hook history.

• Multi-provider agent message handling and inter-agent trace diagnostics.

• Responses-provider and Claude context-window error handling fixes.

• Queued-input recall cleanup for TUI prompt history.

• apohl79 release packaging and installer scripts.

• macOS binary-release update checks, installation, and relaunch.

• Fork upgrade and upstream-change report skills.

• City Lights (Doom Emacs) color theme for the TUI.

• Multi-model provider support via codex-providers — use Codex with DeepSeek or Claude models through codex-providers, an OAuth-to-API provider gateway. The Codex integration includes per-model prompt adjustments for non-OpenAI reasoning budgets, the codex-manager profile wizard for zero-config Claude and DeepSeek setup, and cross-provider sub-agent support (e.g., Claude parent agent spawning GPT or DeepSeek child agents in the same session).

Plugin Context

Plugins can declare static, position-aware instruction blocks in plugin.json that Codex injects into every model API call — permanently, with zero per-turn overhead. This replaces hook-based periodic reminders that pollute context over long sessions.

{
  "context": {
    "thread": [
      {
        "slot": "contextual_user",
        "position": "preamble",
        "text": "Repository-wide rules: never commit secrets."
      },
      {
        "slot": "contextual_user",
        "position": "supplement",
        "text": "[post-turn] Check whether project context needs updating.",
        "condition_shell": "test \"${PROJECT_CONTEXT_ENABLED:-0}\" = 1"
      }
    ]
  }
}

Slots route content to specific API message roles:

Slot	API role	Behavior
developer_policy	Developer (system)	Aggregated with other developer instructions
developer_capabilities	Developer (system)	Same bucket as developer_policy
contextual_user	User message	Same slot as AGENTS.md; diffed and persisted
separate_developer	Separate developer message	Isolated from other developer sections

Position only applies to contextual_user slot entries. For developer_policy, developer_capabilities, and separate_developer, the position field is ignored — those slots map to system/developer messages where there is no AGENTS.md ordering concept.

Position	Slot	Effect
preamble	contextual_user only	Inserted before AGENTS.md
supplement	contextual_user only	Inserted after AGENTS.md

Plugin context is thread-scoped — subagents automatically inherit it. Content is read once at plugin load time. An entry may add optional condition_shell: use syntax supported by the configured user shell (the example uses POSIX shell syntax). Codex runs it from the thread working directory, before that entry is first injected. Exit code 0 injects the entry; any nonzero exit, launch failure, or a five-second timeout omits it. Standard input and output are disabled, and the shell is non-login, so conditions must not rely on profile initialization. Conditions are trusted plugin code and inherit Codex's process environment. Because injected context is persistent, a later environment change does not remove an entry already present in the thread history.

Using Codex with your ChatGPT plan

Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Business, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.

You can also use Codex with an API key, but this requires additional setup.

Docs

• Codex Documentation
• Fork notes
• Contributing
• Installing & building
• Open source fund

This repository is licensed under the Apache-2.0 License.