Keep work moving in Codex.
Plan tasks, return to the right conversation, and assign work to reusable Agents without leaving Codex Desktop.
English · 简体中文
Better Codex is a local workflow extension for Codex Desktop. It adds task and project management to the Codex sidebar and stores task data locally in SQLite.
Supports Apple Silicon and Intel Macs.
curl -fsSL https://raw.githubusercontent.com/Ericwong5021/better-codex/main/scripts/install.sh | bashUse the Microsoft Store version of Codex, then run this command in PowerShell:
irm https://raw.githubusercontent.com/Ericwong5021/better-codex/main/scripts/install.ps1 | iexIf Codex is running, the installer asks before closing it. Press Enter or type Y to continue. The installer downloads the latest release, verifies its SHA-256 checksum, installs the local runtime, restarts Codex, and checks that the integration is working.
After installation, Codex has two new sidebar entries:
Better Codexopens the task and project view.Agentsopens the Profile Agent manager.
The installer also configures injection-aware launch entry points:
- macOS creates
/Applications/Better Codex.app, which can be pinned to the Dock. - Windows creates a
Better Codexshortcut on the Desktop and in the Start Menu.
If Codex is already running without injection support, launching through these entries quits and restarts Codex. Save active work first.
| Area | Capabilities |
|---|---|
| Tasks and projects | Create projects and tasks, set priorities, search, filter, pin, archive, and move cards between workflow states. |
| Codex conversations | Create tasks from the current conversation and reopen the linked thread from a task card. |
| Profile Agents | Create Agents with their own description, developer instructions, model, and reasoning level, then assign tasks to them. |
| Execution status | See when a task is waiting for a session, running, under review, completed, blocked, or canceled. |
| Local data | Store projects, tasks, assignments, and run state in a local SQLite database. No Better Codex account is required. |
| Updates | Install signed updates from the notice inside Codex, or rerun the installation command to upgrade. |
- Open
Better Codexfrom the Codex sidebar. - Create a project and add a task.
- Link the task to a Codex conversation, or create it from the conversation you are using.
- Move the task as the work progresses.
- Open the task to return to its conversation.
- Assign the task to a Profile Agent when it needs a specific role or configuration.
The same workflow can be used for coding, research, writing, document preparation, data collection, and other work done with Codex.
Run the installation command again to upgrade. Better Codex upgrades the existing runtime when possible and performs a full installation when required.
Starting with v0.3.7, Better Codex also checks a signed update manifest in the background. When a new version is available, an update notice appears inside Codex. Installing the update restarts Codex automatically.
| Platform | Database |
|---|---|
| macOS | ~/.better-codex/better-codex.db |
| Windows | %USERPROFILE%\.better-codex\better-codex.db |
The Better Codex runtime listens on 127.0.0.1. It does not require a Better Codex cloud service or upload task content to one.
Check the runtime, database, Codex compatibility, and injection:
better-codex doctorShow the current service and board connection:
better-codex statusReconfigure or inspect system launch entry points:
better-codex launcher install
better-codex launcher statusRemove the sidebar entries without deleting task data:
better-codex ejectInstall Node.js 22.5 or later, then run:
git clone https://github.com/Ericwong5021/better-codex.git
cd better-codex
npm ci
npm run build
npm link
better-codex inject --launch
# Create the Better Codex launcher.
better-codex launcher installBetter Codex supports Codex Desktop on macOS and the Microsoft Store version of Codex on Windows. It relies on the desktop app's local CDP interface and page structure, so some Codex updates may require a Better Codex compatibility update.
Release packages and CI checks cover macOS on Apple Silicon and Intel, plus Windows x64.
Use GitHub Issues for bugs and feature requests. Use GitHub Discussions for questions and workflow ideas.
Please use English for public GitHub conversations so everyone can follow them.