Codex Taskboard: A Local-First Issue Board for Codex and the taskctl CLI

The problem Codex Taskboard addresses

Agent sessions produce work items faster than they produce a record of them. A Codex task can inspect a file, change it, and move on, leaving no durable state that a later session or a second window can read. Codex Taskboard is the project's answer: an issue board that runs as a local HTTP service, stores its data in SQLite at `.data/taskboard.sqlite`, and serves both a browser UI and a command-line client from one API.

The intended user is someone who already works inside Codex and wants issue state visible in the same window rather than in a separate browser tab or a hosted tracker. The repository ships a Codex Skill at `skills/manage-taskboard` and an injection script that adds a sidebar entry after Plugins. The README describes the Skill's workflow in specific terms: it teaches Codex to inspect an issue, move it to `in_progress`, use optimistic versions, verify the work, and move it to `in_review`, promoting it to `done` only after the user confirms acceptance. That last constraint is the interesting design decision. The agent is not permitted to close its own work.

Everything is local by default. The service binds to 127.0.0.1:47823, and the README notes that cloud deployments are configured through a loopback companion service using `taskctl cloud login`. The project is not trying to be a shared team tracker.

One HTTP API behind the UI, the CLI and the Skill

The architecture is a single Node process. `server/index.mjs` hosts the API, the Vite-built React frontend is served from the same origin, and `cli/taskctl.mjs` is a thin client over the same endpoints. That is why the README can say the same HTTP API powers the React UI and the `taskctl` CLI. There is no separate sync layer to reason about, and no second source of truth.

State lives in SQLite, which means the board survives restarts without a database server. The CLI locates its target service in two ways: `CODEX_TASKBOARD_URL` points it at another local or LAN service, and the source launcher writes an authenticated endpoint to `.data/launcher-runtime.json`, which a `npm link`-installed `taskctl` reads by default. That file is what lets a normal shell and a Codex task opened from the panel share one Taskboard service without exporting an environment variable.

The Codex integration is the part with real moving parts. The injector attaches to a Codex renderer over the Chrome DevTools Protocol, so it needs a reachable CDP port. The recommended launcher, `npm run codex`, handles four cases: it starts the local service if needed, reuses an open Codex that has a reachable CDP renderer, opens Taskboard in the native browser panel of an ordinary Codex without CDP, or launches the official macOS app with an independent profile and loopback-only port 9231 when nothing is open. The README states that the launcher does not modify `ChatGPT.app` or its `app.asar`, which is the right boundary for a tool that injects into someone else's window.

The trade-off is that injection is a live attachment, not an installation. The injector terminal has to stay running while you use the embedded panel, and the launcher keeps watching both the service and replacement renderers. Close the terminal and the sidebar entry stops being maintained.

Installing Codex Taskboard and creating your first issue

The README requires Node.js 22.5 or newer, which matches the `engines` field in `package.json`. From a checkout, install, build the web UI, and start the service:

npm install
npm run build
npm start

Open http://127.0.0.1:47823 and the board should be there. The SQLite file appears at `.data/taskboard.sqlite`. For frontend work, `npm run dev` runs the Vite UI at http://127.0.0.1:5173 and proxies API requests to the local service, so you get live reload without restarting the server.

The CLI ships as a bin entry named `taskctl`. The README's first real use is creating a project and an issue, run through the package script:

npm run taskctl -- project create \
  --id my-project \
  --name "My project" \
  --workspace-path /absolute/path/to/repository

npm run taskctl -- issue create \
  --project my-project \
  --title "Implement the next slice" \
  --status todo \
  --priority high \
  --labels product,mvp

The `--workspace-path` value is an absolute path to the repository the project tracks. If you want `taskctl` on your shell path instead of behind `npm run`, the README suggests `npm link`.

To give Codex the board, symlink the bundled Skill into the skills directory and start a new Codex task:

ln -s /absolute/path/to/codex-taskboard/skills/manage-taskboard \
  ~/.agents/skills/manage-taskboard

The README notes that the desktop app keeps that same directory synchronized with its bundled Skill. After the symlink, a new Codex task should be able to inspect an issue and move it through the states the Skill defines.

For the embedded panel on macOS, the one-command path is:

CODEX_TASKBOARD_HOST=127.0.0.1 npm run codex

Keep that command running. If you prefer to attach to a specific window, the manual route starts a second Codex instance on a dedicated CDP port and then runs the injector against it. The README uses port 9231 for both and notes that if it is occupied you should pick another port in both commands.

Where Codex Taskboard breaks down

The release history is the first thing to weigh. The three most recent releases are v1.1.23-beta.1, v1.1.23-beta.2, and v1.1.23-beta.3, dated 2026-09-08 and 2026-09-17. Every listed release carries a beta tag, so there is no stable release line to pin to. The last push to the repository was on 2026-09-17, the same day as the newest beta. Anyone who needs a frozen version with a support promise should look elsewhere for now.

Platform coverage is narrow in a way that is easy to miss. The README states that the first Linux desktop release supports Ubuntu 24.04 LTS on x64 only, and explicitly lists what is not supported: ARM64, Fedora, RPM packages, and other Linux distributions. Windows builds require Visual Studio Build Tools with the C++ workload and Windows SDK, plus the Microsoft Store Codex App. The README also states that current Windows CI artifacts remain unsigned until code signing approval, so Windows users are running unsigned binaries from CI in the meantime.

The Codex embedding path is the most fragile part. It depends on CDP being reachable, on the injector process staying alive, and on port 9231 being free. The README does not document a rollback procedure for the injection, so if a sidebar entry ends up in a state you do not want, the documented recovery is not spelled out. The launcher avoids modifying `ChatGPT.app` and `app.asar`, but that also means there is no uninstall step to follow beyond stopping the process.

Finally, Codex Taskboard is the wrong tool if your issues need to be shared. It is local-first by design, and the cloud path routes through a device-local loopback companion for auth and path mapping rather than a multi-tenant server. Teams that need comments, notifications, or a web URL that other people can open should not adopt this.

How Codex Taskboard differs from a Git-backed issue tracker

The obvious comparison is a Git-native issue tracker such as GitBug, or a hosted board such as GitHub Issues. Those tools treat the repository as the system of record: issues live in commits, refs, or a remote API, and every participant reads them through Git or HTTP. Codex Taskboard inverts that. It keeps state in a local SQLite file at `.data/taskboard.sqlite` and exposes it over a loopback HTTP API, with the CLI and the UI as two clients of the same service. Nothing about the board is versioned with your code, and nothing about it is shared unless you point `CODEX_TASKBOARD_URL` at a LAN service.

That difference decides the use case. A Git-backed tracker gives you history, branching, and offline merge semantics, and it costs you a commit-shaped workflow that an agent has to learn. Codex Taskboard gives you a low-friction state machine that an agent can drive through a Skill with optimistic version checks, and it costs you durability guarantees tied to your repository. If the SQLite file is lost, the board is lost; the README documents no export or backup command.

The second comparison is against simply tracking work in the Codex conversation. That has no persistence across sessions and no shared state between two Codex windows. Codex Taskboard's value is precisely that the state outlives the session and is readable from a shell through `taskctl`.

Licence, packaging and the cost of keeping up

The project is licensed under Apache-2.0, which permits commercial use, modification, and redistribution provided you keep the licence and notice files and state significant changes. It also includes an explicit patent grant. That is a permissive choice with fewer obligations than a copyleft licence, but it is not legal advice and the `LICENSE` file is the authority.

Upgrade cost is currently high because of the beta cadence. Three beta releases landed within nine days in September 2026, and the version field in `package.json` reads 1.1.23. If you track the repository directly, expect to rebuild the web UI and restart the service on each pull. The packaged macOS App bundles its own Node runtime, the Taskboard service, the built web UI, the Skill, the CLI wrapper, and the injection script, so App users avoid the Node 22.5 requirement entirely; the README states the target Mac needs only the official Codex app and does not need this repository, a system Node installation, or a separate Codex CLI installation. That is the lower-maintenance path if you are on macOS.

Two operational details carry real cost. Data moves to `~/Library/Application Support/Codex Taskboard` in the App, while launcher output goes to `~/Library/Logs/Codex Taskboard/codex-taskboard-launcher.log`, so a source install and an App install keep their state in different places. And the README states that a public macOS download still needs Developer ID signing and Apple notarization, which means a locally built App is ad-hoc signed and not equivalent to a notarized release.

Editorial conclusion

Adopt Codex Taskboard if you already run Codex on macOS or Ubuntu 24.04 x64 and want issue state that a Skill can move through in_progress and in_review without leaving the editor. Skip it if you need a hosted board, ARM64 Linux, RPM packages, or a stable non-beta release line. Before committing, verify that `npm run build` and `npm start` come up on 127.0.0.1:47823, that `taskctl` reads `.data/launcher-runtime.json` after `npm link`, and that your Codex build exposes a reachable CDP renderer on port 9231.

Frequently asked questions

Official sources

1. chuspeeism/dashi-taskboard on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases