DSH Codex Kanban

An AI-native Kanban and Codex chat fusion plugin for DeepSeek Harness.

It gives DeepSeek, Codex, and you one durable view of the work. DeepSeek can plan and maintain cards through tools. Codex can implement or review a card through the official DSH Codex provider. You get a local operator dashboard where context, acceptance criteria, blockers, execution reports, and verification evidence survive every chat.

Release state: 0.1.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.
• Local operator cockpit: search, owner filters, card creation, live updates, detail review, and handoff-copy actions.
• 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.

Quick start

1. Prerequisites

• Node.js 22.19 or newer.
• A working DeepSeek Harness installation.
• The Codex CLI installed and authenticated. Run codex once in your terminal if you have not signed in yet.

2. Install the plugin

Choose the DSH profile you normally use; web is only an example:

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

The bundle patch installs this plugin and the official Codex subagent provider together. Restart that DSH profile after installation.

3. Open the dashboard

By default it is available only on your computer:

http://127.0.0.1:4317

4. Ask DeepSeek to use it

Try:

List my Kanban, then create a ready card for adding rate-limit tests to this repository. Include observable acceptance criteria and assign it to Codex.

Then:

Delegate that card to Codex. Keep it in review until the focused tests and diff have been inspected, then attach the evidence.

The workflow

State	Meaning	Move on when
backlog	Worth remembering, not ready to start	Scope becomes clear
ready	Context and acceptance criteria are sufficient	Work actually begins
running	Someone or an agent is actively working	Result needs review or a blocker appears
review	Work was returned, but is not yet accepted	Evidence proves the criteria
blocked	A concrete dependency prevents progress	The blocker is resolved
done	The stated criteria are met and evidenced	Nothing remains in this card

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

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.

The dashboard copies handoff prompts rather than starting Codex directly. That is deliberate: the official provider needs the owning DSH agent session so permissions, cancellation, working directory, and chat lineage stay correct.

Configuration

The bundled defaults are in cordis.patch.yml:

dashboardHost: 127.0.0.1
dashboardPort: 4317
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.

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 Codex ran
Open its Codex run in the drawer. The stop reason and output are retained. Fix the card context, environment, or permission issue, then delegate 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