DSH Codex Kanban

An AI-native Kanban companion for DeepSeek Harness.

DeepSeek Harness already provides the session and chat interface, so this plugin does not build a second one. It adds a durable visual board that the existing Harness chat can read and update through native tools. Codex remains available underneath as the official implementation provider. Card context, acceptance criteria, blockers, execution reports, and verification evidence survive every chat.

Release state: 0.4.0 is an early public release. Use it locally, keep important work in Git, and report rough edges.

Why this exists

Chat is good at thinking, but weak at holding operational truth over time. A promising answer can look the same as tested work. This plugin makes the states explicit:

backlog → ready → running → review → done

Blocked work moves to blocked with a reason. A Codex run always lands in review, never done; a human or agent must inspect it and attach evidence first.

This is useful when you:

• move between several repositories and AI chats;
• want DeepSeek to coordinate while Codex handles bounded coding work;
• need to remember exact blockers, owners, test results, commits, or URLs;
• want a local visual board without giving a cloud task service your project context;
• care about the difference between planned, edited, tested, reviewed, and finished.

What you get

• Durable model-callable board: cards live in a local JSON file, not browser storage.
• Official Codex delegation: kanban_codex uses @deepseek-ai/dsh-subagent-codex and your existing Codex CLI authentication.
• Evidence-aware workflow: acceptance criteria, blockers, evidence, and Codex reports stay on the card.
• Nightforge-style operator cockpit: a compact full-height board with project filtering, search, live updates, and detail review.
• Drag with a reliable fallback: drag cards between columns on desktop, or use the inline state menu on touch screens and keyboards.
• Safe defaults: the dashboard binds to 127.0.0.1, mutations reject foreign browser origins, and the state file is written with owner-only permissions.
• No hidden completion: successful Codex work becomes review; failed delegation becomes blocked.
• First-minute guide: an empty board explains the three useful steps and can create a safe example card for you.
• One official chat: every card opens the real Harness UI with its structured task message copied and ready to paste.
• Hidden implementation detail: Codex remains available to DeepSeek and its run history stays on the card without becoming a second user-facing chat screen.

Quick start

After an administrator installs the plugin once, normal use is entirely visual:

1. Open the Kanban Workbench at http://127.0.0.1:4317.
2. Select Create my first card. Describe one outcome and what must be true before it is finished.
3. Move the card to Ready using drag and drop or the menu on the card.
4. Select Open in Harness on the card. The plugin copies that card's title, context, state, blocker, and completion criteria while opening the official Harness UI.
5. Paste and send the prepared message in Harness. DeepSeek can update the same card and use Codex internally when implementation is appropriate.

If you want to learn safely, select Try an example. It creates one clearly labeled practice card and opens its details. It never starts Codex or changes another project by itself.

Harness does not currently expose an official URL parameter for prefilling a prompt or opening a specific session. The plugin therefore uses a safe one-click open-and-copy handoff instead of putting potentially sensitive card content in a URL or inventing a fragile private integration.

One-time administrator setup

The current DSH web settings can inspect installed plugins, but it cannot install an external GitHub plugin yet. An administrator therefore performs one installation action. Everyone else uses the screen afterward.

Prerequisites are Node.js 22.19 or newer, DeepSeek Harness, and an authenticated Codex CLI. Install into the normal web profile:

dsh plugin --profile web add github:sonozaki7/dsh-codex-kanban

The bundle installs this plugin and the official Codex provider together. Restart the DSH web profile once. No one needs to type another plugin command for normal use.

The workflow

Owners mean current accountability, not permanent assignment:

• human: judgment, credentials, approval, or an external action is needed;
• deepseek: coordination, research, or tool-driven work belongs with DSH;
• codex: bounded implementation or review is currently delegated;
• shared: handoff or joint review is expected.

See docs/WORKFLOW.md for a complete first-day example and recovery guidance.

Tools available to DeepSeek

This is a native DSH plugin, not only a dashboard. Its bundle patch inserts the plugin and the official Codex provider into the selected Harness profile. On boot it registers both tools with DSH, adds concise board rules to the agent's system prompt, and starts the local visual workbench over the same durable store. The board and the official Harness chat therefore show the same cards immediately.

kanban

Actions: list, create, update, move, evidence, and delete.

Important fields include project, status, owner, acceptance_criteria, blocked_by, evidence_text, and evidence_url. Deletion requires confirm=true.

kanban_codex

Takes an existing task_id and an optional extra instruction. The plugin builds a standalone prompt from the card, starts the official Codex subagent, and records the outcome back onto the same card.

Delegation passes the active DSH parent agent, cancellation signal, card context, and acceptance criteria to the provider. This keeps Codex inside the current Harness session and working-directory boundary instead of starting an unrelated background chat.

Codex is intentionally an internal provider rather than another visible chat tab. The board asks the owning Harness chat to delegate implementation because that session supplies permissions, cancellation, working directory, and chat lineage. The card still retains the returned automation history for review.

Moving cards

On desktop, drag any card except an actively running card to another column. The destination highlights before you drop it. Running is managed by the agent lifecycle, so it is not a manual drop target. On a phone, tablet, or keyboard, use the state menu at the bottom of each card. This matches the Nightforge Workbench interaction: drag is fast, while the visible menu remains the dependable fallback.

Configuration

The bundled defaults are in cordis.patch.yml:

dashboardHost: 127.0.0.1
dashboardPort: 4317
harnessUrl: http://127.0.0.1:3080
announceToAgent: true

The board defaults to $DSH_HOME/codex-kanban/board.json, or ~/.dsh/codex-kanban/board.json when DSH_HOME is unset. You can configure an absolute dataFile in the plugin entry for another local location. harnessUrl controls where the visual Open DeepSeek Harness actions lead and accepts only http or https addresses.

If port 4317 is occupied, select another unused local port and restart DSH. Do not bind the dashboard to a public interface unless you add a trusted authenticated proxy; the built-in server is a local cockpit, not a public multi-user service.

Data and security

• Board content is stored locally as readable JSON so it is inspectable and recoverable.
• Atomic writes prevent a half-written file after normal interruption.
• No password, token, or Codex credential is copied into the board.
• The Codex provider uses the existing local Codex CLI setup.
• Treat card text and Codex output as potentially sensitive project data. Back it up only to a location you trust.
• The dashboard has no account system. Loopback binding is the security boundary in this release.

Troubleshooting

The dashboard does not open
Check the DSH log for dsh-codex-kanban dashboard:. If the port is busy, change dashboardPort.

Codex delegation says it needs an owning agent
Run kanban_codex from a live DSH agent chat. A dashboard button cannot safely create that parent context.

Codex cannot start
Confirm codex is on PATH and authenticated in the same user account that runs DSH.

A card is blocked after automation ran

Open its automation history in the drawer. The stop reason and output are retained. Fix the card context, environment, or permission issue, then continue from Harness again.

The board file is invalid
The plugin refuses to overwrite an unsupported or malformed board. Repair or restore the JSON file, then restart DSH.

Development

npm install
npm run check
npm test
npm run pack:check

The plugin is plain ESM JavaScript and needs no build step. Contributions are welcome; please keep task states truthful and local-first behavior intact.

License

MIT