Codex Manager

English | 简体中文

Your local control center for OpenAI Codex.

Codex Manager is an unofficial, local-first desktop app for understanding and managing Codex usage on your own machine: sessions, models, reasoning effort, tokens, accounts, providers, projects, and AGENTS.md files in one place.

Download for macOS (Apple silicon) →

Download

Download the latest signed macOS release · Release assets and checksums · All releases

The latest non-draft, non-prerelease GitHub Release is the stable macOS arm64 download source of truth. Each version must independently pass Developer ID signing, Apple notarization, stapling, and public asset verification; verify its published assets and checksums when your workflow requires it.

If Codex Manager makes your workflow easier, consider starring the repository to follow future releases.

Why Codex Manager?

As Codex usage grows, useful context is spread across the CLI, local rollout files, configuration, account state, and project instructions. It becomes difficult to answer which model and reasoning effort a task used, how many tokens were observed, which projects have an AGENTS.md, and which account or provider is active.

Codex Manager brings those views into a single local desktop control center. Observed data is labeled by source, missing values remain unavailable, and estimates are not presented as provider bills.

Features

Observe

• Browse sessions, turns, model interactions, models, providers, reasoning effort, timing, and available token categories.
• Inspect input, output, cached read/write, and reasoning output tokens with source/provenance.
• Filter and cursor-page activity; open detail views without persisting message or reasoning text.
• Estimate API-equivalent cost from a versioned pricing catalog. This is not ChatGPT subscription billing or a provider invoice.
• The overview uses a compact layout with one recent-activity row; the homepage API-equivalent estimate is rounded to two decimal places while coverage semantics remain unchanged.

Manage

• Read Codex sessions and archived_sessions incrementally and normalize them into local SQLite.
• Discover observed projects, Git roots, worktrees, and the effective AGENTS.md chain.
• Create, edit, save, restore, and review project AGENTS.md revisions only inside an explicitly authorized root.
• Use the official Codex login/App Server boundary for account, plan, quota windows, and reset times; macOS beta supports multiple imported OAuth profiles with explicit switching.
• Official subscription data is cache-first after the first successful read; a manual Refresh action forces a live read and the UI labels cache age and last-confirmed state.
• Save custom Responses-compatible provider metadata and use an explicit local gateway when needed.

Local-first

• Default storage is local SQLite; there is no product telemetry or cloud sync.
• API keys, OAuth profile secrets, and the local gateway bearer stay in application-specific Keychain storage or native runtime memory.
• Optional OTel receiver and provider gateway are disabled until the user enables them and are bound to local interfaces.
• User actions are explicit: the app does not silently rewrite Codex configuration or rotate accounts in the background.

Quick Start

1. Download the latest macOS .dmg from Releases.
2. Install and launch Codex Manager.
3. On first launch, it discovers available local Codex data under the configured Codex home (normally ~/.codex).
4. Open the activity view to inspect observed sessions and model usage.
5. To edit an AGENTS.md, first authorize the project root in Settings. To use a provider gateway, save a provider and explicitly start the loopback listener; the overview exposes explicit start/stop controls for the existing Responses gateway.

The desktop app does not automatically change config.toml or auth.json. The signed release includes Developer ID signing, Apple notarization, and stapling; account switching and provider use still require explicit user actions.

Screenshots

All screenshots use synthetic, sanitized demo data.

Activity and token usage	Accounts and quota

Projects and AGENTS.md	Custom Responses providers

Supported platforms

• Supported: macOS 13+, arm64 release artifacts.
• Windows: unavailable; no equivalent supported secret-store and file-safety implementation is claimed.
• Linux: unavailable; no equivalent supported secret-store and file-safety implementation is claimed.

Core collection, normalization, storage, pricing, and project parsing are kept behind cross-platform interfaces, but that is not a claim of current Windows or Linux support.

How it works

Codex Manager uses adapters rather than exposing private source formats directly to the UI:

• Rollout adapter: incrementally reads local sessions and archived_sessions JSONL. It records metadata, not message bodies. Token snapshots are deduplicated by session, ordinal, event type, and cumulative vector; they are not blindly summed.
• OTel adapter: optional authenticated OTLP/HTTP on local TLS loopback. It can provide request status, duration, and bounded classifications. Current Codex metrics do not reliably identify a conversation, so the app does not invent request-to-session joins.
• CLI Schema compatibility: a short-lived probe verifies whether the local CLI supports the App Server Schema. It is not a collection source, does not attach to Codex Desktop's private stdio, and does not affect rollout collection; the latest probe is persisted.
• Official App Server adapter: separate short-lived, bounded reads provide account, plan, and ChatGPT Codex quota data. It does not attach to Codex Desktop's private stdio or read historical data.
• Filesystem and AGENTS adapter: discovers observed cwd and explicitly authorized roots, resolves the effective chain, and uses canonical-path, no-follow, conflict-check, and atomic replacement protections for writes.

Observability and data boundaries

Every metric carries a source or confidence boundary. unavailable means that the source did not provide a verifiable field; it is not zero. unobserved means a reliable terminal state was not available; it is not a success, failure, or proof of still running.

Rollout metadata is an internal compatibility source, not a stable public API. OTel codex.api_request events can add request status, duration, and fixed provider/origin/route classifications, but raw hosts, paths, query strings, and bodies are not stored. Native Codex telemetry usually does not provide reliable wire response bytes or request-level TTFB. The activity view therefore does not claim all requests, strict real-time completeness, or a complete provider bill.

API-equivalent pricing uses recognized model calls and the versioned local catalog. Unknown models and incomplete fields stay uncovered; the result is not ChatGPT subscription cost, OpenAI Platform billing, or a third-party provider invoice.

See the capability matrix and architecture for field-level semantics and limits.

Accounts, providers, and the local gateway

Official Codex subscription access remains in the trusted codex login, App Server, official credential store, and explicit account-switching path. OAuth access/refresh tokens never enter the provider gateway.

Imported-profile switching is explicit and is supported only when Codex resolves cli_auth_credentials_store to file; keyring and auto modes fail closed. Because the CLI and IDE extension share the active credential file, finish running Codex tasks before switching accounts.

The optional gateway is a Codex-only OpenAI Responses identity pass-through. The overview provides its current status and explicit start/stop controls:

• Stopped by default; it binds only to 127.0.0.1 after an explicit start.
• Supports /v1/models, /v1/responses, and /v1/responses/compact; it does not translate Chat Completions, Anthropic, or Gemini protocols.
• Remote upstreams must be HTTPS public origins; loopback HTTP is allowed only for explicit local development. Redirects, private/link-local addresses, userinfo, query, and fragment are rejected.
• The client bearer is not forwarded upstream. API keys are injected only in the native layer; request/response bodies, headers, queries, and full upstream errors are not persisted.
• The overview never displays the bearer or provider API k