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.

Known issue in v0.6.6: upgrading a database near 512 MiB can fail at migration 14 and prevent startup. The v0.6.7 source fixes this with a fixed 1 GiB database budget. Existing databases must not be deleted as a workaround. See diagnosis and validation.

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.
• Use the separate Codex configuration page to switch among official direct, local CLIProxyAPI, and saved external Responses-compatible providers with preview, CAS/atomic apply, and restore.
• Use the separate Local proxy page to import and manage a CLIProxyAPI OAuth profile pool, then expose the local loopback endpoint to Codex. External API-key providers remain a Codex configuration concern and do not pass through CLIProxyAPI.

Local-first

• Default storage is local SQLite; there is no product telemetry or cloud sync.
• Official and CLIProxyAPI OAuth secrets remain in separate application-specific Keychain domains; provider API keys stay in Keychain and are used by the Codex configuration path.
• Optional OTel receiver and CLIProxyAPI core are disabled until the user enables them and bind only 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 the local proxy, import a CLIProxyAPI-compatible OAuth profile and explicitly enable it on the overview. The first enable downloads and verifies the reviewed prebuilt CLIProxyAPI baseline for the current platform; Codex Manager never builds the Go core locally.

Codex configuration changes are explicit and transactional; the app does not edit auth.json. The signed release includes Developer ID signing, Apple notarization, and stapling; account switching and proxy 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

v0.6.7 upgrade startup fix

Version 0.6.7 increases the fixed SQLite database budget from 512 MiB to 1 GiB and calculates the page limit from the actual page size. This lets the observed near-limit v13 database create the migration-14 index without deleting existing data. Capacity regression tests and migration of a private copy passed; installing the fixed build and verifying startup on the user’s machine remain user-operated and unaccepted. See the v0.6.7 release notes.

Previous v0.6.6 reliability improvements

The v0.6.6 source includes the following reliability fixes. The stable download is the latest verified public Release; source versioning alone does not indicate publication.

• Task totals remain unavailable after an invalid token snapshot; earlier valid calls still contribute to explicitly partial API-equivalent estimates. Missing call metadata uses the same fallback for activity and pricing across incremental batches.

• Retention also applies during initial import, rebuild and scheduled maintenance. Tasks without an observed terminal state or a usable timestamp are retained; source rollout files and credentials are unaffected.

• AGENTS editing protects unsaved changes and rejects stale read results. Activity filter choices cover the selected view's full history. Write success and a subsequent refresh failure are reported separately.

• Local proxy status refreshes while its page is visible. Slow native work runs off the UI thread, and proxy startup health checks have a bounded deadline.

• Changed rollout files receive priority within bounded queues; background discovery resumes across scan budgets so older files remain reachable.

• In-app confirmations protect unsaved AGENTS edits, AGENTS creation/restoration, Codex configuration changes and local proxy OAuth profile removal in the desktop WebView.

Implementation and validation boundaries are recorded in the v0.6.6 release notes.

The v0.6.6 source in an isolated debug desktop, using synthetic data; this is a validation screenshot, not a claim of signed-package installation.

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 s