Codex Kanban

Codex Kanban gives Codex a task layer that outlives the conversation. Tasks, questions, blockers, comments, activity and attachments live in .kanban/board.json inside your repository, so they survive restarts, show up in code review, and belong to the project rather than to a chat.

It also meets you where you already are: on first run it can turn this repository's existing Codex sessions into Backlog tasks, with a checklist before anything is written. Codex reads and writes the board through 20 MCP tools and a kanban skill; humans get the same board as a local web app and a CLI. No hosted service, database, account or runtime dependency.

What you get

Related MCP server: Weft

Install

Requirements: Codex with plugin support, and Node.js 22 or newer.

codex plugin marketplace add https://github.com/SilasSolivagus/codex-kanban
codex plugin add codex-kanban@silassolivagus

Local checkout:

codex plugin marketplace add /path/to/codex-kanban
codex plugin add codex-kanban@silassolivagus

Update later:

codex plugin marketplace upgrade silassolivagus
codex plugin add codex-kanban@silassolivagus

Start a new Codex session in the repository you want to track.

Three ways to use it

Installing the plugin never opens a browser. The default board appears in the conversation; the web board is a separate serve step.

1. In Codex (agent writes, you decide)

"Track the SSO redirect bug as a high-priority task with the auth label. Ask me whether staging or production should get the fix first."

Codex creates the task, posts a question, and leaves it in Needs you. Answer it, then say "approve with the staging option" — Codex records the answer and closes the task with your confirmation. Ask "what needs me?" any time for just the attention queue.

2. Local web board (for humans)

# from a checkout
node plugin/bin/codex-kanban.mjs serve

# from the installed plugin (version may differ)
node "$HOME/.codex/plugins/cache/silassolivagus/codex-kanban/0.7.3/bin/codex-kanban.mjs" serve

serve opens http://127.0.0.1:4317 by default; pass --no-open to only print the URL. It binds to loopback, has no account system, and makes no outbound requests. --port changes the port; --host 0.0.0.0 exposes the board to your network.

To start the board at login:

Add --open (macOS/Linux) or -Open (Windows) to also open the browser at login.

3. CLI (for scripts)

node plugin/bin/codex-kanban.mjs board
node plugin/bin/codex-kanban.mjs add "Fix the login redirect" \
  --description "Users land on / after SSO instead of the page they came from." \
  --priority high --label auth
node plugin/bin/codex-kanban.mjs move 1 --to in_progress
node plugin/bin/codex-kanban.mjs ask 1 \
  --prompt "Which environment should get the fix first?" \
  --option Staging --option Production
node plugin/bin/codex-kanban.mjs approve 1 --confirmed-by "Staging first"
node plugin/bin/codex-kanban.mjs render --open

Numeric references such as 1 resolve to <prefix>-1. --root PATH points at another repository; by default the CLI uses the nearest directory above the current one containing .git or .kanban.

Import your history

A board does not have to start empty.

• Web: an empty board offers this repository's Codex sessions, with a time range (30 days / 90 days / all time), a candidate cap (10–100), and a checklist. Pick what belongs on the board; nothing is written before you confirm.

• Codex chat: when the board is empty, the kanban skill asks the same question and shows the titles first.

• CLI: preview by default, apply explicitly.

# preview only
node plugin/bin/codex-kanban.mjs import --root "$PWD" --since 30d

# create the previewed tasks
node plugin/bin/codex-kanban.mjs import --root "$PWD" --since 30d --apply

Rules: only sessions whose cwd is inside this repository; at least two user turns; only the thread name and last user message are read; imported tasks land in Backlog with an imported label and a source pointing at the session; duplicates by title are skipped. Skip is remembered per repository, and Projects → Import history reopens the offer.

Tools

Every tool takes root, the absolute repository path. It is required unless CODEX_KANBAN_ROOT is set; there is deliberately no fallback to the server's working directory, because an installed plugin runs from the plugin cache. Writes to an existing task take the current version from kanban_task_get; approve and reject also require as: "user" and confirmed_by.

Projects, archive and attachments

• Projects are workstreams inside one repository; identifiers are unique per project.

• Archiving is enforced in the domain layer: PROJECT_ARCHIVED for a task in an archived project, TASK_ARCHIVED for an archived task.

• Attachments live in .kanban/attachments/<id> with metadata on the task. Add that directory to .gitignore if you do not want binaries in git.

• Needs you, blocked and review are overlays computed from state; they never overwrite the stored status.

Architecture

flowchart LR
  U[You] --> A[Codex app or CLI]
  A --> S[kanban skill<br/>when to read, ask, write or import]
  A --> M[MCP server<br/>20 kanban_* tools]
  S --> M
  W[Local web board<br/>127.0.0.1] --> M
  I[Codex sessions<br/>$CODEX_HOME] --> P[Import scanner]
  P --> W
  P --> C[CLI import]
  C --> M
  M --> B[".kanban/board.json<br/>atomic · versioned"]
  M --> H[".kanban/board.html<br/>self-contained view"]
  M --> F[".kanban/attachments/"]

The skill owns policy — read before answering, ask instead of blocking, never approve its own work, offer import on an empty board. The server owns the data path: one board per repository, every write through the same store. The import scanner only reads session titles and the last user message.

Data model

Schema 2, created on first write:

{
  "schema": 2,
  "projects": [
    {
      "id": "prj_default",
      "name": "my-app",
      "prefix": "MYAPP",
      "workspacePath": null,
      "nextTaskNumber": 2,
      "archivedAt": null,
      "createdAt": "2026-10-22T07:45:38.341Z",
      "updatedAt": "2026-10-22T07:45:38.341Z"
    }
  ],
  "tasks": [
    {
      "id": "tsk_8116bbc1-7390-4031-9c1f-719fd79c6f3b",
      "projectId": "prj_default",
      "identifier": "MYAPP-1",
      "title": "Fix the login redirect",
      "status": "in_progress",
      "priority": "high",
      "labels": ["auth"],
      "blockedReason": null,
      "pendingQuestion": null,
      "links": [],
      "attachments": [],
      "comments": [],
      "activity": [],
      "archivedAt": null,
      "version": 3,
      "createdAt": "2026-10-22T07:45:38.342Z",
      "updatedAt": "2026-10-22T07:46:12.000Z"
    }
  ]
}

An imported task additionally carries source: {kind:"session", id, title}. A v1 board is migrated in place on first read. version starts at 1 and increments on every change; stale writes fail with TASK_VERSION_CONFLICT, missing versions with VERSION_REQUIRED. Writes are serialized with .kanban/board.lock and applied by writing board.json.tmp, syncing, then renaming.

UX quality

The web board was audited twice by an independent designer against the dsh-kanban reference, with screenshots and a goodwill meter:

Reports and evidence live in docs/ux-review/. The UI supports keyboard navigation, visible focus, prefers-reduced-motion, and 4.83:1 minimum contrast for metadata.

Known limitations

• Import is a heuristic, not a summary. It uses the thread title and the last user message; a long conversation becomes one Backlog task, and "already finished" is not detected. Triage after import.

• The approval boundary is cooperative, not authenticated. as: "user" and confirmed_by are declarations. An agent that lies, runs the CLI, or edits board.json can bypass them; the real protection is reviewing the diff.

• No realtime collaboration. Two people on one board rely on git; the web server is single-user and loopback-only.

• One repository per board. Projects are workstreams, not a global cross-repo board.

• The in-app visual is not verified end to end. kanban_render writes the HTML and returns a host reference; the Markdown board is the verified path in every client.

• Scale is untested beyond demo boards. Filtering and rendering were checked with a few dozen tasks, not hundreds.

Roadmap

• A global board across repositories, with the same file-per-repo escape hatch.

• Persist the human confirmation with the approval so the audit trail carries the exact words.

• Multi-user awareness (who is viewing, soft locks) without turning the board into a service.

• Optional model-assisted import that summarises a session into several tasks.

Development

git clone https://github.com/SilasSolivagus/codex-kanban.git
cd codex-kanban
node --test

The suite has 300 tests at v0.7.2, uses only node:test, and needs no dependencies. npm test runs the same command.

.agents/plugins/marketplace.json   local marketplace entry
plugin/.codex-plugin/plugin.json   plugin manifest
plugin/.mcp.json                   MCP server configuration
plugin/bin/                       launcher and CLI
plugin/server/                    JSON-RPC stdio server, HTTP API
plugin/src/                       domain, store, rules, renderers, session scanner, web UI
plugin/skills/kanban/SKILL.md     agent-facing workflow
test/                             node:test suites
scripts/                          autostart installers (macOS/Linux/Windows)
docs/ux-review/                   audits, evidence and batch reports

See CONTRIBUTING.md and the human guides: English · 简体中文.

Feedback and ideas

• Bug? Use the bug report template; it asks for the plugin version, Codex client and OS.

• Concrete improvement? The feature template asks for the workflow that hurts, not just the feature name.

• Open-ended prioritisation? Join What should v0.8 build? (Discussions #1).

• Setup or how-to? Use Q&A.

Share usage without an account

node plugin/bin/codex-kanban.mjs stats        # human summary
node plugin/bin/codex-kanban.mjs stats --json # same data as JSON

It prints counts only — projects, tasks by column and status, attention, comments, attachments, links, activity in the last 7 days, plugin/platform versions. No repository path, project names, task titles, labels or session content. There is no network request; paste the output into Discussions if you want it to influence the roadmap.

If the board got in your way, describe the workflow you were in. That is easier to act on than a list of features.

License

MIT © 2026 Silas Solivagus. See LICENSE.