From start to finish, keep your work in Codex clear and visible.

A native task board and multi-Agent collaboration system that runs inside the Codex app. Local-first, one-command install.

简体中文 · English

Why this exists

If you use Codex heavily, some of this probably sounds familiar:

• Your session list is a graveyard.
  Dozens (hundreds?) of conversations, all titled roughly the same, none of them grouped by what you were actually working on. Finding "that thread where we debugged the auth flow" means scrolling and guessing.

• One model config rules everything.
  You bump the reasoning level for a hard refactor, and now every new session pays for it. You tune the model for quick Q&A, and your next deep debugging session starts underpowered. There's one global dial, and every task fights over it.

• Ideas have nowhere to live.
  Mid-conversation, you think of three more things worth doing. Codex gives you no place to put them, so they end up in a notes app, a TODO comment, or nowhere. The work you meant to do quietly evaporates.

• Codex is conversation-shaped, but your work isn't.
  Real work is a project that spans days and many threads. Codex hands you a chat log and wishes you luck.

None of this is the model's fault. The model is great. What's missing is a work layer on top of it. So we built a better Codex, literally Better Codex.

What you get

Find any conversation again.
Turn conversations into tasks and organize them by project, status, and owner. Open a task to return to its linked conversation.

Capture ideas before they disappear.
Add new tasks as they come up, then get back to your current work.

See task progress at a glance.
Assign work to yourself or an Agent, then run it manually or automatically. Tasks return to your board when they need review, a decision, or unblocking.

Configure each Agent separately.
Set the model, reasoning level, permissions, instructions, and concurrency limit for each role.

Who it's for

Better Codex works across many roles. If your work spans several Codex conversations and needs progress tracking, review, or repeated revisions, it can fit the same task workflow.

• Developers. Manage requirements, bugs, refactors, and release checks by project. Each task can stay linked to its original conversation, with progress, results, and pending reviews collected on the board.
• Solo companies. Keep product ideas, customer feedback, operations, and content plans on one board. Give research, drafting, and checking to different Agents while keeping final decisions with you.
• Content creators. Save ideas in the backlog, then organize research, outlines, drafts, and revisions as tasks. Each piece can stay linked to its original conversation, so you know where to continue when you come back later.
• Product managers. Manage requirements, user feedback, competitor research, bugs, and release checks separately. Linked conversations preserve the discussion, while the board shows the next step and current owner.
• Sales professionals. Organize public account research, meeting preparation, proposal drafts, and follow-up tasks. Create a project for each account or opportunity instead of scattering research and next steps across conversations.
• Office staff. Track meeting notes, announcement drafts, report preparation, spreadsheet work, and recurring administrative tasks. Give each Codex-assisted task to an Agent, then review the results in one place.

A day with Better Codex

1. Open Better Codex from the Codex sidebar to use the task board, Agents, projects, and settings in the plugin page. Optional desktop integration also provides separate Task board and Agents entries.
2. Create a project and capture a task, manually or straight from the conversation you're in.
3. Assign it to yourself, the default Codex profile, or one of your Agent profiles.
4. Keep manual mode for full control, or enable automatic mode and let ready Agent-owned tasks run.
5. Watch the board. When a task needs review or a decision, it comes back to you.
6. Open the task to read its linked conversation, send a reply, or continue in Codex.

The same loop works for coding, research, writing, document prep, and anything you already do in Codex.

Installation

macOS 13+ (DMG, for releases that include it): drag Better Codex.app into Applications, then open it. The app runs quietly in the menu bar and shows Runtime readiness separately from Codex integration. The DMG includes Node.js. Use Open Codex / Enable board in the menu to enter the existing launcher flow. Closing Better Codex stops the board service while existing model turns keep their execution processes; results synchronize when Better Codex starts again.

macOS (command-line installer):

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/Ericwong5021/better-codex/main/scripts/install.ps1 | iex

Better Codex runs as a small Node.js bundle and requires Node.js 22.5 or later. The installer checks this before changing an existing installation. If Node.js is missing or too old, it asks before installing the current LTS release; declining leaves the existing Better Codex installation and database untouched.

The installer adds the CLI, Skill, local runtime, and system launcher, then registers the better-codex MCP server with Codex. The MCP server runs only on your computer and provides the Better Codex app entry and route. Projects, tasks, and conversation data remain in the local database. Legacy standalone-EXE installations are removed only after the Node.js bundle passes version and health checks.

On macOS, choose Open Codex / Enable board from the Better Codex menu bar. On Windows, reopen Codex through the Better Codex launcher. Task board and Agents appear as two entries in your sidebar. Run better-codex uninstall to remove Better Codex completely.

Remote access

Remote access is optional and keeps the local Runtime authoritative. Open More → Remote access and copy the VPS installation prompt into Codex.

The Relay supports multiple administrator-created Web accounts. Each account has an independent profile and can assign tasks to any enabled Web account. Self-registration is not available; use the better-codex relay user-* commands in the self-hosting runbook.

The Relay runs in Docker on your Linux server and uses either the bundled Caddy HTTPS service or your existing reverse proxy. Your Runtime makes an outbound WSS connection; the Relay forwards live browser traffic and stores no projects, tasks, conversations, Agent configuration, or attachments.

Codex verifies the signed, version-pinned self-hosting runbook, inspects the environment, preserves existing services and partial installations, and verifies the public service before reporting success. After deployment, enter the public URL in Better Codex to get the Runtime connection command. The same page then shows service status, version, browser access, and a verified upgrade prompt.

Beta testers using remote access must upgrade the local Runtime and the VPS Relay/Web UI separately. Follow the Beta upgrade guide to keep both sides on the same version and verify the public service after the Runtime reconnects.

FAQ

Is this an official OpenAI product?
No. Better Codex is an independent open-source project built on top of Codex Desktop. It is not affiliated with or endorsed by OpenAI.

Where does my data go?
It stays on your computer. Projects, tasks, assignments, conversations, Agent configuration, attachments, and run state live in the local SQLite database (~/.better-codex/better-codex.db on macOS, %USERPROFILE%\.better-codex\better-codex.db on Windows), and the Runtime listens on 127.0.0.1 only. Optional remote access sends live HTTPS/WSS traffic through your Relay while the Runtime is online; the Relay does not persist business data. See the Self-hosting runbook for the exact boundary.

Why does Better Codex register an MCP server?
The local MCP app provides the full Better Codex plugin page using the same UI as Web. It connects tasks, Agents, projects, and settings to the local Runtime over MCP. Credentials stay in the local MCP process, and Runtime remains the owner of task data. Native thread commands and catalog synchronization use a separate desktop bridge without product rendering.

Will it break my Codex?
The app entry and route are registered through the local MCP server. Product UI renders in the plugin page. A separate desktop bridge uses the local CDP interface for native thread commands and catalog synchronization without patching Codex binaries. A Codex update can occasionally require a matching Better Codex compatibility update; when that happens, an update notice appears inside Codex. If anything looks off, run better-codex doctor.

How do I disable or uninstall it?
better-codex stop stops the local Runtime while retaining installed components and task data. better-codex uninstall removes the MCP server, background service, launcher, Skill, Agent profiles, local data, and CLI bundle.

How do updates work?
Better Codex checks a signed update manifest in the background and shows a notice inside Codex when a new version is available. You can also rerun the install command at any time. Runtime updates pause new dispatch while active conversations continue in the independent Session Host and Codex App Server. The new Runtime replays committed Host deliveries and reconciles active turns before becoming ready; failed activation restores the previous Runtime against the same Host. A protocol-incompatible Host update waits for active turns and unacknowledged deliveries to drain before replacing the Host. Remote access has a separate VPS Relay and Web UI update, so Beta testers must complete and verify both sides as described in the Beta upgrade guide.

Which platforms are supported?
Codex Desktop on macOS (Apple Silicon and Intel) and the Microsoft Store version of Codex on Windows x64. Release packages and CI cover all three. Codex compatibility is capability-based rather than pinned to a permanent version list; if required native bridge capabilities are unavailable, Better Codex reports a desktop bridge failure and reports the incompatibility without modifying board data.

Useful commands

better-codex doctor            # check MCP, runtime, database, Codex compatibility, desktop bridge state
better-codex status            # show the current service and board connection
better-codex mcp status        # inspect the MCP registration
better-codex mcp install       # register or repair the MCP server
better-codex launcher install  # install the system launcher
better-codex launcher status   # inspect the system launcher
better-codex stop              # stop the local Runtime, keep task data
better-codex uninstall         # uninstall completely and delete local data

Install from source

Better Codex supports persistent task events, execution attempts, and task dependencies. MCP tools include tasks_history, external_tasks_report, and external_observations_events; see the data contract and integration boundaries. External reporting requires an explicitly enabled, authenticated Runtime connection. Installing the local MCP server does not connect a cloud Dot to it. Dot setup is not exposed in this release.

Requires Node.js 22.5 or later.

If the stable build is already installed, install the source checkout as a separate development instance. Stable keeps ~/.better-codex and the Better Codex launcher; development uses ~/.better-codex-dev and Better Codex Dev. On first launch, development creates ~/.better-codex-dev/better-codex.db as a consistent snapshot of the stable database when one exists. The snapshot then evolves independently: development migrations and test data never modify the stable database. Runtime files, logs, attachments, and update state are also isolated. A desktop bridge yields when another profile owns the renderer; neither launcher stops the other profile’s active tasks.

git clone https://github.com/Ericwong5021/better-codex.git
cd better-codex
npm ci
npm run dev:install

The development instance does not auto-update its core. Pull source changes and run npm run dev:refresh to explicitly refresh the local development installation. npm run build only builds source artifacts. Use npm run dev:status to inspect the development instance and npm run dev:uninstall to remove its launcher and stop it while preserving development data.

Community

• Found a bug or want a feature? Open a GitHub Issue.
• Questions and workflow ideas belong in GitHub Discussions.
• Want to help test Beta releases? Read the Beta testing notes and Beta upgrade guide.
• Please use English in public GitHub conversations so everyone can follow them.

If Better Codex makes your Codex better, a star helps other heavy users find it.