English | 简体中文

Codex Taskboard

A local-first issue board that runs in a browser and can be embedded in Codex through the standalone CDP launcher or its injection script. The same HTTP API powers the React UI and the taskctl CLI used by the bundled Codex Skill.

Requirements

• Node.js 22.5 or newer
• macOS App and DMG builds: Xcode Command Line Tools and Rust 1.88 or newer with the aarch64-apple-darwin and x86_64-apple-darwin targets. npm install installs the Tauri CLI used by this project.
• Windows NSIS builds: the Microsoft Store Codex App, Rust 1.88 or newer, and Visual Studio Build Tools with the C++ workload and Windows SDK.

Run locally

npm install
npm run build
npm start

Open http://127.0.0.1:47823. The SQLite database is stored at .data/taskboard.sqlite.

For development with live frontend reload:

npm run dev

The Vite UI runs at http://127.0.0.1:5173 and proxies API requests to the local service.

Use the CLI

Run it from the project:

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

Use npm link if you want taskctl on your shell path. Set CODEX_TASKBOARD_URL to point the CLI at another local or LAN service. Cloud deployments are configured through the loopback companion (device-local loopback service for auth and path mapping—not a chat persona) with taskctl cloud login.

Install the Codex Skill

Copy or symlink skills/manage-taskboard into the Codex skills directory, then start a new Codex task:

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

The desktop app keeps this same directory synchronized with its bundled Skill. The Skill teaches Codex to inspect an issue, move it to in_progress, use optimistic versions, verify the work, and then move it to in_review; it moves the issue to done only after the user explicitly confirms acceptance or asks to mark it complete.

Embed in Codex

Manual: use a dedicated CDP port

Keep the existing Codex window open. From the Taskboard repository, start a second Codex instance with a dedicated CDP port:

open -n -a /Applications/ChatGPT.app --args \
  --remote-debugging-port=9231 \
  --remote-allow-origins=http://127.0.0.1:9231

After the new Codex window appears, run the injector in another terminal:

CODEX_TASKBOARD_HOST=127.0.0.1 \
npm run codex:inject -- --port 9231 --open

Keep the injector terminal running while using the embedded panel. The original Codex window remains unchanged, and the new window receives the Taskboard sidebar entry. If port 9231 is occupied, use another port in both commands.

Recommended: launch an independent Taskboard window with one command

Keep existing Codex windows open and run:

CODEX_TASKBOARD_HOST=127.0.0.1 npm run codex