Codexion

English | 简体中文

Codexion is a lightweight local companion for Codex Desktop. It safely launches or adopts the desktop app and uses the loopback Chrome DevTools Protocol (CDP) to provide small, restrained UI enhancements without modifying the installed application.

Codexion currently includes two extensions. Sanity Meter adds a compact speedometer and the remaining weekly percentage to the native title-bar actions. For example, 82% means 82% of the weekly allowance remains. Moving the indicator out of the sidebar leaves room for native footer features such as Voice.

GitHub Issue Inbox adds a compact trigger beside the native title-bar actions. It polls selected repositories through the locally installed and authenticated GitHub CLI, excludes issues authored or already answered by the current user, and offers Handle and Ignore actions. Handling creates one Codex task in the repository's matching local workspace; a durable issue-to-thread mapping prevents duplicate task creation across refreshes and restarts.

The Inbox header's Current repo switch queries the active Codex task's GitHub remote directly, even when it is not selected in Settings. If the task has no GitHub remote, Codexion shows a clear empty state without changing the saved repository selection.

Codexion is not a Codex plugin. CDP must be enabled when the desktop process starts, while plugin session hooks run after that process already exists. A standalone companion can coordinate and verify the complete lifecycle instead of attempting to launch a competing second instance.

Status

• Platform: macOS
• Runtime: Node.js 22 or later
• Default app: /Applications/ChatGPT.app
• Default CDP endpoint: 127.0.0.1:9341
• Data sources: Codex app-server for usage and the local gh CLI for selected repositories
• Refresh intervals: 60 seconds for usage; 3 minutes for GitHub issues

Codexion does not modify app.asar, application binaries, or signed resources. It does not create a separate browser profile or require another login.

Issue Inbox is optional. It requires GitHub CLI and an existing gh auth login session. Codexion never stores the GitHub token.

Quick start

macOS app

Tagged releases provide a signed and notarized Apple Silicon Codexion.app in a DMG. Download the DMG from GitHub Releases, drag Codexion to Applications, and open it. The app is a background launcher and companion, so it does not add a second settings window or Dock UI. Releases that include the built-in updater check the signed GitHub release feed automatically while Codexion is running. An installation from an older release without the updater needs one final manual DMG upgrade.

Codexion keeps watching the Codex renderer after launch. If Codex is later reopened without CDP, the companion repairs the launch configuration, reconnects, and restores quota and Issue Inbox state automatically. Opening Codexion again from Applications restarts its background Core, which is useful when diagnosing a stalled companion.

From source

git clone https://github.com/lyuai/codexion.git
cd codexion
pnpm install
pnpm start

After installing dependencies, you can also double-click:

scripts/start.command

If the current Codex process does not expose CDP, Codexion asks it to quit normally and opens it again with loopback debugging enabled. Save active work before the first run. If Codex accepts the normal quit request but remains running for five seconds, Codexion force-terminates that verified process and relaunches it; it never targets an unverified PID or starts a competing second instance.

Use a different port or app location when needed:

CODEXION_CDP_PORT=9342 scripts/start.command

pnpm start -- \
  --app /Applications/ChatGPT.app \
  --port 9342

CODEXION_APP_PATH can also set the default application path.

How it works

codexion start performs a complete, verified lifecycle:

1. Locate the Codex Desktop main process.
2. Inspect the CDP endpoint and verify its process owner.
3. Reuse the process when it already owns the requested port.
4. Otherwise request a normal application quit through macOS.
5. Launch the trusted Codex executable with CDP bound only to 127.0.0.1.
6. Wait for the endpoint and verify that the newly launched PID owns it.
7. Select the main renderer instead of auxiliary views such as the avatar overlay.
8. Read a normalized weekly snapshot and non-secret account identity from the Codex app-server.
9. Update the title-bar speedometer and remaining percentage every minute.
10. Poll selected GitHub repositories and render unhandled issues in the title bar.
11. Health-check the renderer and restore both extensions if Codex is restarted.

Usage retrieval and UI injection are intentionally separate: app-server provides data, while CDP only renders the extension. This avoids coupling data access to unstable renderer HTTP routes.

GitHub Issue Inbox

1. Install gh and run gh auth login if it is not already authenticated.
2. Open Codex Settings.
3. Choose Codexion at the bottom of the Integrations section.
4. Filter and select the repositories to monitor. Changes apply immediately.

The Maintenance section shows the running Core version and can restart the Codexion background companion without restarting Codex Desktop. The page reports a timeout and points to the local log when macOS does not complete the restart request.

The Issue window control limits the Inbox to the last 3, 7, 14, or 30 days, or all open issues. The default is 3 days. Changes apply immediately, persist locally, and use the same right-aligned checkmark selection pattern as native Codex menus. Each Inbox item shows its age in the upper-right corner.

Use Current repo in the Inbox header to temporarily query the repository associated with the active Codex task. It does not need to be selected above, and the switch does not change your saved repository selection. The main list still follows the configured age window; the three newest older eligible issues appear by default in Older issues, with the remainder available on demand. Empty states name the active window. Codexion prefetches the active task's repository when the task changes and keeps a short-lived local cache, so opening the panel normally has no loading step. Expired data remains visible while it refreshes in the background; Refresh bypasses the cache. The repository catalog used by Codexion Settings is also prefetched at startup and cached for five minutes, while selections continue to apply immediately.

Codexion detects known Codex workspaces and matches their origin remote to owner/repository. Each ordinary workspace root is inspected once and remembered locally, so background polling does not keep touching the same folder. Protected Desktop, Documents, and Downloads workspaces are never inspected by background polling. If a workspace is under one of those or another protected location, use File Access > Open System Settings to grant Codexion optional Full Disk Access, then choose Rescan. Codexion does not crawl the disk; it only checks workspace roots already recorded by Codex. An issue without a matching local workspace remains visible, but Handle reports a clear error and does not create a task. Ignore is local and reversible by editing Codexion state.

Ignored issues appear in the Ignored Issues section on the same Settings page. Choose Unignore to restore one; if it is still open and otherwise eligible, it returns on refresh.

Handled and ignored records are stored at:

~/Library/Application Support/Codexion/state.json

The Handle action starts a task with the issue number, title, and URL, asks Codex to reproduce and fix the problem and run relevant tests, and explicitly forbids posting to GitHub or closing the issue without approval. The issue node ID is persisted before and after task creation so a retry can reuse a previously created thread instead of opening another one.

CLI

codexion start   Prepare or reuse Codex with CDP, then run Sanity Meter
codexion attach  Attach to an existing CDP-enabled Codex process
codexion doctor  Print app, process, and CDP diagnostics

Repository commands:

pnpm start
pnpm attach
pnpm doctor

Logs and diagnostics

The double-click launcher stores runtime state at:

~/Library/Application Support/Codexion/codexion.log
~/Library/Application Support/Codexion/codexion.pid

Inspect the current environment with:

pnpm doctor
curl http://127.0.0.1:9341/json/version

Symptom	Cause and recovery
The profile percentage is missing	Run pnpm doctor; confirm CDP is ready and the main renderer is present
The profile percentage shows —	Usage is unavailable or unrecognized; Codexion never estimates it from local task counts
The port is occupied	Select another CODEXION_CDP_PORT or stop the unrelated local process
Multiple main processes are detected	Quit all Codex Desktop instances normally, then start again
Codex was restarted and extensions disappeared	Keep Codexion running; it detects the replacement process and restores CDP and extension state automatically
Opening Codexion appears to do nothing	It has no Dock window; opening it again restarts the background Core. Inspect codexion.log for the result
Codex does not quit normally	After a five-second grace period, Codexion force-terminates only the verified Codex PID and relaunches it with CDP

Project layout

src/
├── lifecycle/  Process identity, normal quit, launch, and port ownership
├── cdp/        Loopback target discovery and CDP session
├── app-server/ Shared Codex app-server JSON-RPC client
├── github/     gh adapter, repository/workspace discovery, state, and task dispatch
├── usage/      App-server provider, response adapters, and UsageSnapshot
└── ui/         Widget installation, placement, styling, and rendering

scripts/
├── start.command   Double-click launcher
└── doctor.command  Double-click diagnostics

See Architecture for module boundaries and the security model.

Future customization

Backgrounds, themes, status indicators, and other enhancements should be independent extensions, not additions to the lifecycle or Sanity Meter modules.

For a background extension, the recommended design is:

1. Create src/extensions/background/ with configuration, CSS generation, and lifecycle logic.
2. Accept only local files explicitly selected by the user and validate type, size, and real path.
3. Inject a uniquely identified <style> or controlled DOM node through CDP.
4. Use narrow selectors and CSS variables; never replace native React components.
5. Provide idempotent apply, disable, and reset operations.
6. Store settings in Codexion's own application data directory, never inside the Codex bundle.
7. Fail closed when a renderer update invalidates the expected anchor or shell.

See Extension development for a proposed extension interface, a detailed background example, resource handling, locator rules, and a security checklist.

Roadmap

• Verified one-click macOS CDP lifecycle
• Codex app-server weekly usage provider
• Native-style Sanity Meter beside the current account
• Local GitHub Issue Inbox with repository selection and idempotent task dispatch
• Codexion page in Codex Settings
• doctor diagnostics
• Installable macOS companion application with signed automatic updates
• Extension registry and unified enable/disable behavior
• Local background and theme extension
• One-click native reset for all extensions
• Renderer and app-server compatibility matrix

The roadmap describes direction, not promised release dates. Discuss substantial designs in an issue before implementation.

Development

pnpm install
pnpm format
pnpm lint
pnpm check
pnpm test
pnpm build

Before submitting a change, run at least:

pnpm lint
pnpm check
pnpm test
pnpm build

Principles

• Local first: data, CDP, and control remain on the local machine.
• Verify ownership: a reachable port is insufficient; it must belong to the target process.
• Controlled lifecycle: prefer a normal quit, then force-restart only the verified Codex PID when it refuses to exit; never launch an uncontrolled second instance.
• Adapter boundaries: isolate Codex protocol and DOM changes in providers and extensions.
• Honest status: show unavailable state when real data is absent; never invent a plausible value.
• Reversible UI: every enhancement must be independently removable and restore native behavior.
• Minimal surface: do not embed a browser, clone Codex, or modify signed resources.

Contributing

Issues, compatibility reports, documentation, and code improvements are welcome. Please read:

• Contributing guide
• Security policy
• Code of conduct

Open a feature request before implementing backgrounds, themes, persistent controllers, or cross-platform support so the safety and recovery boundaries can be agreed first.

License

Codexion is available under the MIT License. Codex, ChatGPT, OpenAI, and related names and marks belong to their respective owners. Codexion is an independent community project and is not affiliated with or endorsed by OpenAI.