One-Line Positioning

This is a Codex Taskboard integration plugin for DeepSeek Harness. It doesn't embed the taskboard itself; instead, it adds a "Taskboard" button to the DSH sidebar, which opens the current local Codex Taskboard launcher page as an embedded web view in the DSH main area.

Core Capabilities

• Adds a "Taskboard" button at the bottom of the DSH Web sidebar; clicking opens a side panel on the right of the main workspace
• The panel loads the Codex Taskboard running page via iframe, equivalent to opening the local Taskboard directly in a browser
• The server registers a redirect route within DSH, which 307 redirects requests to /integrations/codex-taskboard to the current active address reported by the local launcher
• Discovers the active address by reading the runtime description file written by the launcher; no fixed port dependency, so the plugin doesn't need config changes when the launcher switches ports
• The panel provides a "Refresh" button to reload content after Taskboard service restarts, and a "Close" button to collapse the panel
• When the runtime description file is missing or malformed, the redirect route returns 503 with "Codex Taskboard is not running" text to avoid blank error pages

Technical Implementation

• Language: Native JavaScript (ESM module, no build step; "type": "module" in package.json, entry published as source)
• Key Dependencies: @deepseek-ai/dsh-client-ui-sidebar (DSH official client package, injected via manifest); @deepseek-ai/cordis (host injection framework, plugin registers routes via ctx.webServer.register and sidebar buttons via ctx.slots.inject); react (client UI uses React.createElement directly in DSH's render layer, no JSX)
• Architecture Pattern: Dual-end Cordis patch plugin. cordis.patch.yml inserts a service node named codex-taskboard at host startup; server index.js obtains the webServer handle via export const inject = ["webServer"] to register the 307 redirect route; client client.js registers the frontend module via window.__ModuleLoader__.load, injecting into the sidebar.footer.action slot
• Entry Files: integrations/deepseek-harness/index.js (server activation entry, exports name, inject, apply(ctx)); integrations/deepseek-harness/client.js (browser activation entry, mounts apply(ctx) to DSH client runtime)

Use Cases

For users who have already deployed and use Codex Taskboard locally, installing this plugin brings the task list from a separate browser tab or app into the DSH main window, viewable side-by-side with conversations. It solves the problem that DSH doesn't include task management UI by default, and switching windows back and forth to view Taskboard breaks focus.

Prerequisites and Compatibility

Installation

dsh plugin --profile web add github:chuspeeism/dashi-taskboard/integrations/deepseek-harness

Configuration

This plugin has no user-configurable fields; only one environment variable affects the runtime file path:

FAQ

Q: Can this plugin be used independently?

A: No. It's just a redirect bridge between DSH and Codex Taskboard; the local machine must have the Codex Taskboard launcher running first for the button to redirect to the actual page.

Q: The "Taskboard" button doesn't appear in the sidebar after installation?

A: Check if DSH is started with the Web profile (--profile web), and whether the plugin manifest declares client platform as web; non-web profiles (like terminal profile) won't inject sidebar UI.

Q: Clicking the button shows "Codex Taskboard is not running" in the panel?

A: Usually the launcher isn't running or the description file path is incorrect; first start Codex Taskboard (npm run codex or macOS App), then click the sidebar button; you can also use the "Refresh" button in the panel to retry.

Q: Can the default runtime file path be used directly on Windows / Linux?

A: No. The default path ~/Library/Application Support/Codex Taskboard/launcher-runtime.json is macOS-style; on Windows, Taskboard data is typically in %APPDATA%\Codex Taskboard, and on Linux it generally requires npm run codex with a custom path; on Windows / Linux, you need to set the CODEX_TASKBOARD_RUNTIME_FILE environment variable to point to the correct description file.

Q: Does the plugin need any changes when the Taskboard launcher switches ports?

A: No. The plugin doesn't depend on a fixed port; the launcher writes the current URL to the runtime description file, and the plugin reads the latest value for redirect.

Q: How to uninstall?

A: Use dsh plugin --profile web remove to remove this plugin; the plugin itself doesn't store any persistent data, so after removal the sidebar button and route won't be injected on next DSH startup.

Q: What do the "Refresh" and "Close" buttons in the panel do?

A: "Refresh" increments the iframe's key value, forcing the iframe to reload and bypass browser cache; "Close" collapses the right panel, keeping the sidebar button's expanded state until next click.

Learning Curve

Beginner — just install the plugin and ensure the local Codex Taskboard launcher is running; no advanced configuration fields to fill in.

Known Issues and Limitations

• The default runtime file path ~/Library/Application Support/Codex Taskboard/launcher-runtime.json is macOS-style; on Windows / Linux, without overriding via CODEX_TASKBOARD_RUNTIME_FILE, the plugin won't find Taskboard; this plugin's package.json has no os field for platform restrictions
• The runtime description file requires version === 1 and url to be a string, otherwise the plugin throws an error and returns 503; if the launcher upgrades to a new description format, the plugin's judgment logic needs updating
• The redirect route uses 307 temporary redirect with cache-control: no-store, but cross-origin behavior within the iframe is still subject to host CSP and the launcher's own policies
• There are no TODO / FIXME / HACK comments in the source code, and no explicitly marked bugs

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

This starts the local Taskboard service when needed. It reuses an open Codex with a reachable CDP renderer, opens Taskboard in the native browser panel of an ordinary Codex without CDP, or launches the official macOS Codex app with an independent profile and loopback-only port 9231 when no Codex is open. It injects a native-looking Taskboard entry after Plugins when CDP is available and keeps watching both the service and replacement renderers. Keep this command running while using the embedded panel. The launcher does not modify ChatGPT.app or its app.asar.

The source launcher writes its authenticated endpoint to .data/launcher-runtime.json. A taskctl command installed with npm link reads this file by default, so a normal shell and a Codex task opened from the panel use the same Taskboard service without an extra environment variable.

macOS App: open and inject without a terminal

For Tauri development, run:

npm run app:dev

To build the local App and DMG, install the two Rust targets once, then run the build:

rustup target add aarch64-apple-darwin x86_64-apple-darwin
npm run app:build

Open src-tauri/target/universal-apple-darwin/release/bundle/macos/Codex Taskboard.app from Finder. The DMG is in src-tauri/target/universal-apple-darwin/release/bundle/dmg/. If you only want the stable App, download the current DMG from GitHub Releases.

The App contains its own Node runtime, Taskboard service, built web UI, Skill, CLI wrapper, and injection script. It starts the service, reuses an open Codex with a reachable CDP renderer, opens Taskboard in the native browser panel of an ordinary Codex without CDP, or launches the official Codex app when no Codex is open. It waits for the renderer, injects the sidebar entry when CDP is available, and opens the panel without showing a terminal window. The App can be copied away from this checkout; the target Mac only needs the official Codex app and does not need this repository, a system Node installation, or a separate Codex CLI installation. Taskboard data is stored in ~/Library/Application Support/Codex Taskboard, and launcher output is written to ~/Library/Logs/Codex Taskboard/codex-taskboard-launcher.log.

Windows code signing

For official Windows releases after the application is approved: Free code signing provided by SignPath.io, certificate by SignPath Foundation. Current Windows CI artifacts remain unsigned until that approval. See the Code signing policy, Privacy policy, and Windows uninstall instructions.

The local build uses ad-hoc code signing for direct verification. A public macOS download still needs Developer ID signing and Apple notarization.

Windows App: tray launcher and bundled Taskboard

Install the official Codex App from the Microsoft Store. To build the current-user NSIS installer on Windows x64, run:

npm ci
npm run app:build:windows

The installer is written to src-tauri/target/x86_64-pc-windows-msvc/release/bundle/nsis/. It installs a tray launcher, bundled Node runtime, local service, built web UI, Skill, taskctl.cmd, and injection script. Taskboard data is stored in %APPDATA%\Codex Taskboard; logs are stored in %LOCALAPPDATA%\Codex Taskboard\Logs; the Skill is copied to %USERPROFILE%\.agents\skills\manage-taskboard.

Windows CI artifacts are intentionally unsigned and do not auto-update. Review the code-signing policy before distributing a build. See Windows uninstall for retained-data behavior.

Codex 26.715.52143 ships a renderer CSP that blocks arbitrary HTTP iframes. The launcher therefore enables CDP CSP bypass, reloads that renderer once, installs the document-start script, and waits until the Taskboard OOPIF is actually loaded. CDP is unauthenticated to other processes on the same machine, so only run trusted local code while the launcher is active.

To inject into a Codex instance that was already launched with CDP by another method, run:

npm run codex:inject -- --port 9229 --open

This command also stays resident so the injected tab can restart Taskboard after a service exit. Stop it with Ctrl-C.

The script adds a Taskboard entry to the Codex sidebar and renders the iframe across Codex's complete main workspace, including the contextual titlebar area so Taskboard's own header does not leave an empty strip. That full rectangular header is placed above Electron's draggable layer and marked no-drag; because the native contextual actions are suppressed while Taskboard is active, its own actions use their normal edge padding without an artificial right-side gap. The native sidebar stays mounted, while the previous page selection and contextual header are temporarily suppressed; choosing another Codex page restores them.

“在对话中打开” selects the corresponding native Codex project when one is available and opens an unsent native composer with an e-taskboard instruction and the issue's actual identifier. The installed Skill is selected implicitly from that instruction, so the composer does not add a $manage-taskboard mention. A conversation is attributed only after it actually processes the issue: taskctl reads Codex's CODEX_THREAD_ID and records that ID on the issue or comment mutation. Recorded IDs are clickable through Codex's native route bridge. Each issue can bind either one Git branch or one worktree; the options are scanned from the selected Codex project's repository instead of being typed by hand. The integration uses Codex's existing project, composer, and route markers; it does not patch React, replace fetch, load private chunks, or edit Codex data files.

To use a different UI origin, set window.__CODEX_TASKBOARD_URL__ before the user script runs.

Configuration

npm start prints both the local URL and the available LAN URLs. Teammates on the same trusted network can open one of those LAN URLs and use the same taskboard service. Task, comment, and attachment changes are broadcast to every open client through server-sent events; reconnecting clients perform a full refresh so changes made while disconnected are not missed. A teammate using taskctl can point it at the shared service with CODEX_TASKBOARD_URL=http://<host-ip>:47823.

LAN mode has no account authentication: anyone on the trusted local network who can reach the URL can read and write the taskboard. Public internet and cloud deployment require an authenticated deployment boundary.

Share through Cloudflare

For two trusted collaborators, the taskboard can run on Cloudflare with Worker Static Assets and API routes, D1 as the authoritative business database, and a private R2 bucket for attachments. The deployment uses HTTPS Basic Authentication with a shared password and refreshes open boards after a global revision changes.

Each device keeps its own project checkout mapping and continues to use a local companion for Codex, Git/worktree, Skill, and MCP capabilities. Cloud mode never falls back to or double-writes the local SQLite database.

See Cloud collaboration for owner deployment, existing GitHub installation setup, password rotation, local path mapping, and the one-time local-data migration flow.

Verify

npm run check

This runs TypeScript checking, a production frontend build, the component tests, and the server/CLI/injection test suite.

Task Markdown

Task descriptions and comments support GFM, including tables and task lists. Fenced mermaid blocks are rendered as read-only diagrams after the viewer loads; the diagram source remains available when rendering fails. Markdown HTML comments, such as <!-- trace-analysis:v1 ... -->, are hidden from the rendered document. Raw HTML is not enabled.