# Better Codex: A task board and multi-agent layer that sits on top of Codex Desktop

> Better Codex adds a local-first task board and configurable Agent profiles to Codex Desktop, aiming to fix the mess of untitled conversations and one-size-fits-all model settings. It is a pragmatic work layer, not a model upgrade, and it carries real installation and maintenance trade-offs.

**Ericwong5021/better-codex** — A task board and Agent system inside Codex Desktop. Local-first, open source, macOS and Windows.

- Repository: https://github.com/Ericwong5021/better-codex
- Website: https://www.bettercodex.com/
- Stars: 94 · Forks: 9
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-08-27 · Updated: 2026-08-27 · Language: en
- Canonical page: https://hysenlabs.com/projects/ericwong5021-better-codex

## The problem: Codex is a chat log, not a work tracker

The README is blunt about its motivation. Your session list becomes a graveyard of similarly titled conversations, and finding the thread where you debugged auth means scrolling and guessing. One global model config rules every session, so raising the reasoning level for a hard refactor makes every new session pay for it. Ideas that come up mid-conversation have nowhere to live, so they evaporate. Better Codex treats these as missing work-layer features, not model flaws. It targets developers, solo operators, content creators, product managers, sales staff, and office workers, anyone whose work spans several Codex conversations and needs progress tracking, review, or repeated revisions. The pitch is that real work is project-shaped, not conversation-shaped, and Codex hands you a chat log.

## What it adds: tasks, projects, and per-Agent configuration

Better Codex turns conversations into tasks and organizes them by project, status, and owner. You can open a task to return to its linked conversation. You can capture ideas as new tasks before they disappear. The board shows tasks that need review, a decision, or unblocking. The Agents feature lets you set the model, reasoning level, permissions, instructions, and concurrency limit for each role. That is a direct answer to the one-global-dial problem. Each Agent profile is independent, so a research Agent can run on a cheaper model while a refactor Agent uses a higher reasoning level. The README describes a daily loop: open the Task board from the Codex sidebar, create a project and task, assign it to yourself or an Agent, choose manual or automatic mode, and watch the board. Tasks return to you when they need human input. This is not a new IDE or a new model. It is a management layer over the existing Codex app.

## How it runs: a Node.js bundle, an MCP server, and a local database

The architecture is local-first. Better Codex runs as a small Node.js bundle and requires Node.js 22.5 or later. The installer checks the Node version before changing an existing installation. If Node is missing or too old, it asks before installing the current LTS release, and declining leaves the existing installation and database untouched. The installer adds the CLI, a Skill, a local runtime, and a 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 stay in the local database. After installation, you restart Codex from the Better Codex launcher, and Task board and Agents appear as two sidebar entries. Uninstall is a single command: better-codex uninstall. The installer also removes legacy standalone-EXE installations, but only after the Node.js bundle passes version and health checks. That sequencing is a careful touch, but it means the installer is doing real work, not just copying files.

## Installation commands and the one-command promise

The README gives two install paths. On macOS, run: curl -fsSL https://raw.githubusercontent.com/Ericwong5021/better-codex/main/scripts/install.sh | bash. On Windows PowerShell, run: irm https://raw.githubusercontent.com/Ericwong5021/better-codex/main/scripts/install.ps1 | iex. Both are one-liners, but they pipe remote scripts into your shell, which is a security consideration you should weigh. The installer checks Node.js before touching an existing install, and it can install the current LTS if you agree. The installation registers the MCP server, which is how Codex discovers the Task board and Agents entries. The README does not give a manual install path or a package manager option. If you prefer not to pipe curl to bash, there is no documented alternative here. The project's release cadence is active, with v0.4.11 pushed on 2026-08-28, so the install script may change frequently. Verify the script contents before running it, especially if you are on a shared machine.

## Optional remote access: a Docker Relay with a strict boundary

Remote access is optional and keeps the local Runtime authoritative. You open More, then Remote access, and copy a VPS installation prompt into Codex. The Relay runs in Docker on a Linux server and uses either a bundled Caddy HTTPS service or your existing reverse proxy. Your Runtime makes an outbound WSS connection, and the Relay forwards live browser traffic. The README claims the Relay stores no projects, tasks, conversations, Agent configuration, or attachments. That is a strong privacy boundary, but it also means the Relay is a thin pipe, not a sync server. The Relay supports multiple administrator-created Web accounts, each with an independent profile, and can assign tasks to any enabled Web account. Self-registration is not available; you use better-codex relay user-* commands from the self-hosting runbook. Codex verifies the signed, version-pinned SELF_HOSTING.md runbook, inspects the environment, preserves existing services, and verifies the public service before reporting success. This is a more involved setup than the local install, and it assumes you have a Linux server and are comfortable with Docker and reverse proxies.

## Limitations and wrong-tool cases

The most obvious limitation is that Better Codex is tied to Codex Desktop. If you do not use Codex heavily, this tool has no value. It is also macOS and Windows only. Linux is not mentioned as a desktop target. The install method, piping a remote script, is a trust barrier. The Node.js requirement, version 22.5 or later, may force you to upgrade your runtime or accept an installer-proposed LTS install. The README does not describe what happens if the MCP server fails to register, or how to debug a broken sidebar entry. The project is in an active beta phase, with versions like v0.4.10-beta.44 and v0.4.10-beta.45 in the release list. That suggests API or behavior changes between releases. If you need a stable, long-term tool, this may not be it yet. The remote Relay adds complexity and a second failure domain, and the README does not explain what happens to in-flight tasks if the WSS connection drops. The documentation is also thin on data export or migration, so consider your exit path before you store months of project history in the local database.

## Alternatives: what else does this job?

The closest alternative is a generic project tracker like GitHub Projects, Trello, or Linear, which also organize tasks by project and status. The difference is that those tools are not integrated with Codex. Better Codex links each task to its original Codex conversation, so you can reopen the exact thread where the work happened. A generic tracker gives you a card, but you must manually copy links or context. Another alternative is to stay inside Codex and use its built-in session management, accepting the graveyard. That costs nothing and has no install risk, but it gives you no board, no per-Agent configuration, and no automatic task routing. A third alternative is to use Codex's own Agent features if they exist, but the README implies Codex lacks a work layer, which is why this project exists. The real difference is the tight coupling: Better Codex changes how Codex behaves from the inside, while a generic tracker sits outside and requires manual synchronization.

## Maintenance, upgrade cost, and license

The project is Apache-2.0 licensed, so you can use, modify, and redistribute it, with the usual conditions. The maintenance cost is non-trivial. The README describes an installer that manages a CLI, a Skill, a local runtime, a system launcher, and an MCP server registration. That is more moving parts than a simple plugin. Upgrades are frequent, with multiple beta releases in a single day, which suggests active development but also a higher chance of breakage. The installer's health checks before removing legacy EXE installations are a sign that the project cares about smooth upgrades, but they also imply that upgrades are not always trivial. You will need to re-run the install script or a similar update path to get new versions. The README does not document a separate update command, so you may need to check the releases page and reinstall. The local database is a black box; there is no documented schema or backup procedure in the material. For a tool that stores your project history, that is a gap you should investigate before relying on it.

## Conclusion

Adopt Better Codex if you live inside Codex and your work spans many conversations that need grouping, review, or handoff to separate Agent profiles. Skip it if you rarely open Codex or if you cannot tolerate a Node.js runtime and a launcher-managed install. Before adopting, verify that your Codex version matches the installer's expectations, confirm your Node.js is 22.5 or newer, and read SELF_HOSTING.md if you plan the optional Relay. The project is young, so check the latest release notes for breaking changes before each upgrade.

## FAQ

### How do I install better-codex on macOS?

Either drag the application into Applications from the disk image, which bundles Node.js, or run the shell installer that pipes the install script into bash. The app then runs from the menu bar and you use Open Codex or Enable board to enter the launcher flow.

### What version of Node.js does better-codex require?

Node.js 22.5 or later. The installer checks this before changing an existing installation, and if Node is missing or too old it asks before installing the current LTS release.

### Where is my data stored in better-codex?

Projects, tasks and conversation data remain in a local database on your machine. The registered MCP server runs only on your computer, and there is no hosted backend for that data.

### Can users register themselves for better-codex remote access?

No. Web accounts are created by an administrator using the relay user commands in the self-hosting runbook, each gets an independent profile, and self-registration is not available.

### How do I remove better-codex?

Run better-codex uninstall. On Windows, reopen Codex through the Better Codex launcher rather than starting it directly; on macOS use the menu bar entry to re-enter the launcher flow.

## Sources

- [Official documentation](https://www.bettercodex.com/)
- [Official README](https://github.com/Ericwong5021/better-codex#readme)
- [Project repository](https://github.com/Ericwong5021/better-codex)
- [Release notes](https://github.com/Ericwong5021/better-codex/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ericwong5021-better-codex