@polderlabs/openkan 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +226 -0
- package/LICENSE +21 -0
- package/README.md +318 -0
- package/agents/openkan.md +254 -0
- package/bin/install-agent.mjs +63 -0
- package/bin/ok.mjs +17 -0
- package/bin/openkan.mjs +10 -0
- package/dist/.claude/skills/ok-planning/SKILL.md +285 -0
- package/dist/.claude/skills/ok-planning/references/integration.md +153 -0
- package/dist/.claude/skills/ok-planning/references/schemas.md +270 -0
- package/dist/.claude/skills/ok-planning/references/workflows.md +185 -0
- package/dist/.claude/skills/ok-planning/scripts/ok-init.sh +14 -0
- package/dist/.claude/skills/ok-planning/scripts/ok-resume.sh +38 -0
- package/dist/.claude/skills/ok-planning/scripts/ok-status.sh +24 -0
- package/dist/agents/openkan.md +254 -0
- package/dist/bin/install-agent.mjs +76 -0
- package/dist/bin/ok-install.js +58 -0
- package/dist/bin/ok.js +138 -0
- package/dist/bin/openkan.js +804 -0
- package/dist/commands/organize.md +15 -0
- package/dist/kanban/agent-profile.js +8 -0
- package/dist/kanban/archive.js +49 -0
- package/dist/kanban/bizar.js +242 -0
- package/dist/kanban/board.js +367 -0
- package/dist/kanban/bulk.js +139 -0
- package/dist/kanban/changelog.js +186 -0
- package/dist/kanban/chat.js +1280 -0
- package/dist/kanban/claude-state.js +974 -0
- package/dist/kanban/comments.js +80 -0
- package/dist/kanban/docs.js +144 -0
- package/dist/kanban/fs.js +163 -0
- package/dist/kanban/git.js +196 -0
- package/dist/kanban/images.js +140 -0
- package/dist/kanban/import.js +295 -0
- package/dist/kanban/inputs.js +94 -0
- package/dist/kanban/insights.js +140 -0
- package/dist/kanban/io.js +75 -0
- package/dist/kanban/mdx-render.js +348 -0
- package/dist/kanban/mdx.js +231 -0
- package/dist/kanban/projects.js +545 -0
- package/dist/kanban/search.js +121 -0
- package/dist/kanban/server.js +3296 -0
- package/dist/kanban/tags.js +124 -0
- package/dist/kanban/template.js +145 -0
- package/dist/kanban/tsx-sandbox.js +187 -0
- package/dist/kanban/watcher.js +270 -0
- package/dist/ok/commands/goal.js +65 -0
- package/dist/ok/commands/index.js +87 -0
- package/dist/ok/commands/init.js +15 -0
- package/dist/ok/commands/plan.js +155 -0
- package/dist/ok/commands/prd.js +202 -0
- package/dist/ok/commands/progress.js +31 -0
- package/dist/ok/commands/task.js +377 -0
- package/dist/ok/ids.js +98 -0
- package/dist/ok/lock.js +156 -0
- package/dist/ok/migrate.js +197 -0
- package/dist/ok/schemas.js +402 -0
- package/dist/ok/storage.js +222 -0
- package/dist/skills/openkan/SKILL.md +111 -0
- package/dist/skills/openkan/agents/openai.yaml +4 -0
- package/dist/skills/openkan/examples/simple-task.mdx +34 -0
- package/dist/skills/openkan/examples/with-ask.mdx +32 -0
- package/dist/skills/openkan/examples/with-choice.mdx +51 -0
- package/dist/skills/openkan/examples/with-preview.mdx +54 -0
- package/dist/skills/openkan/references/api.md +169 -0
- package/dist/skills/openkan/templates/task.mdx +46 -0
- package/dist/web/api.js +257 -0
- package/dist/web/app.js +4251 -0
- package/dist/web/bizar.js +39 -0
- package/dist/web/brand/agent-activity-sprite.svg +1 -0
- package/dist/web/brand/banner-docs.svg +24 -0
- package/dist/web/brand/banner.svg +32 -0
- package/dist/web/brand/empty-sessions.svg +17 -0
- package/dist/web/brand/empty-tasks.svg +17 -0
- package/dist/web/brand/favicon.svg +9 -0
- package/dist/web/brand/infinity-loader-animated.svg +220 -0
- package/dist/web/brand/infinity-loader-spritesheet.svg +230 -0
- package/dist/web/brand/logo-wordmark.svg +10 -0
- package/dist/web/brand/logo.svg +9 -0
- package/dist/web/brand/pixel-infinity-track.svg +1 -0
- package/dist/web/brand/social-card.svg +26 -0
- package/dist/web/changelog-view.js +456 -0
- package/dist/web/charts.js +269 -0
- package/dist/web/chat-sidebar.js +2397 -0
- package/dist/web/chat-status-motion.js +154 -0
- package/dist/web/claude-pane.js +820 -0
- package/dist/web/command-palette.js +381 -0
- package/dist/web/contributors-view.js +317 -0
- package/dist/web/cross-tab.js +102 -0
- package/dist/web/docs-view.js +168 -0
- package/dist/web/experience.css +165 -0
- package/dist/web/goals-view.js +45 -0
- package/dist/web/home-view.js +113 -0
- package/dist/web/images.js +311 -0
- package/dist/web/index.html +485 -0
- package/dist/web/insights.js +217 -0
- package/dist/web/keyboard.js +446 -0
- package/dist/web/mdx-viewer.js +600 -0
- package/dist/web/path-picker.js +787 -0
- package/dist/web/preview-frame.html +187 -0
- package/dist/web/settings.js +582 -0
- package/dist/web/style.css +8545 -0
- package/dist/web/task-view.js +1759 -0
- package/dist/web/vendor/gsap.min.js +11 -0
- package/dist/web/workspace.css +1513 -0
- package/package.json +71 -0
- package/skills/openkan/SKILL.md +111 -0
- package/skills/openkan/agents/openai.yaml +4 -0
- package/skills/openkan/examples/simple-task.mdx +34 -0
- package/skills/openkan/examples/with-ask.mdx +32 -0
- package/skills/openkan/examples/with-choice.mdx +51 -0
- package/skills/openkan/examples/with-preview.mdx +54 -0
- package/skills/openkan/references/api.md +169 -0
- package/skills/openkan/templates/task.mdx +46 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.4.0] - 2026-09-05
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Bundled OpenKan Claude agent, automatic installation that preserves customized
|
|
15
|
+
profiles, and an explicit `openkan agent install` command.
|
|
16
|
+
- Chat agent selection with OpenKan as the default and installed custom profiles
|
|
17
|
+
available alongside the general-purpose Claude Code agent.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- Improved chat drafts, send recovery, transcript navigation, and responsive
|
|
22
|
+
composer controls.
|
|
23
|
+
- Streamlined task creation with optional settings, retained drafts, accessible
|
|
24
|
+
errors, and duplicate-submission protection.
|
|
25
|
+
- Improved project recency handling and refreshed the installation guide.
|
|
26
|
+
|
|
27
|
+
## [0.3.0]
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- Public npm distribution with compiled JavaScript, both `openkan` and `ok`
|
|
33
|
+
executables, bundled UI, explicit skill installation, and isolated package
|
|
34
|
+
installation/server smoke tests.
|
|
35
|
+
- Offline `openkan task`, `plan`, `prd`, `goal`, and `progress` commands;
|
|
36
|
+
command-first board collaboration and project selection without handwritten
|
|
37
|
+
HTTP requests. Planning commands locate an existing parent `.ok/` workspace.
|
|
38
|
+
- CI package verification on Node 22 and 24.
|
|
39
|
+
|
|
40
|
+
### Changed
|
|
41
|
+
|
|
42
|
+
- The dashboard now uses a cohesive responsive workspace design with a compact
|
|
43
|
+
navigation shell, board health summary, progressive filters, denser task
|
|
44
|
+
cards, mobile column snapping, and a redesigned task workspace.
|
|
45
|
+
- Changelog and contributor views now include clear page-level context, and
|
|
46
|
+
switching tabs from task detail closes the detail view instead of leaving it
|
|
47
|
+
over the newly selected section.
|
|
48
|
+
- `DESIGN.md` is now the durable product and accessibility contract for
|
|
49
|
+
frontend work.
|
|
50
|
+
- The installer now keeps the OpenKan workflow skill synchronized for Codex,
|
|
51
|
+
Claude Code, and shared agent skill discovery.
|
|
52
|
+
- The OpenKan skill now requires agents to claim durable tasks, keep task
|
|
53
|
+
workspaces current, avoid overlapping active work, and record verification
|
|
54
|
+
evidence before completion.
|
|
55
|
+
- The installer now owns a dedicated application directory at
|
|
56
|
+
`${XDG_DATA_HOME:-$HOME/.local/share}/openkan` and updates it atomically.
|
|
57
|
+
- A single hosted `install.sh` can now bootstrap the complete source archive
|
|
58
|
+
when piped directly to Bash.
|
|
59
|
+
- Production dependencies are installed inside the OpenKan application
|
|
60
|
+
directory instead of being merged into another application's package.
|
|
61
|
+
- The `openkan` command is linked from a configurable `OPENKAN_BIN_DIR`,
|
|
62
|
+
defaulting to `~/.local/bin`.
|
|
63
|
+
|
|
64
|
+
### Removed
|
|
65
|
+
|
|
66
|
+
- The retired host-specific plugin adapter and its SDK dependency.
|
|
67
|
+
- Legacy host branding from source, documentation, examples, and templates.
|
|
68
|
+
|
|
69
|
+
## [0.3.0] — 2026-07-30
|
|
70
|
+
|
|
71
|
+
### Added (Bizar control plane)
|
|
72
|
+
|
|
73
|
+
- **Bizar workspace:** OpenKan now surfaces Bizar agents, durable tasks,
|
|
74
|
+
background sessions, feature status, progress, and message history in one
|
|
75
|
+
dedicated management view.
|
|
76
|
+
- **Agent and session controls:** start named Bizar agents, send messages to
|
|
77
|
+
running sessions, stop sessions, and receive live state updates.
|
|
78
|
+
- **Durable task controls:** create, claim, heartbeat, complete, and cancel
|
|
79
|
+
Bizar tasks without bypassing Bizar's CLI and storage contracts.
|
|
80
|
+
- **REST and WebSocket bridge:** the OpenKan server delegates mutations to
|
|
81
|
+
`bizar control` through a JSON CLI boundary and streams snapshots to the UI
|
|
82
|
+
over a loopback-only WebSocket endpoint.
|
|
83
|
+
- **Cross-project verification:** `npm run e2e` starts the real OpenKan server
|
|
84
|
+
and verifies Bizar state through REST, WebSocket, and browser assets.
|
|
85
|
+
|
|
86
|
+
### Added (Docs tab + Multi-project + Comment authorship)
|
|
87
|
+
|
|
88
|
+
- **Docs tab (4th tab)**: full file browser for the project's `docs/`
|
|
89
|
+
folder. Recursive collapsible tree on the left (4-level deep); rendered
|
|
90
|
+
MDX/MD viewer on the right with the same nice typography as the artifact
|
|
91
|
+
viewer. URL hash `#tab=docs&doc=milestones/M7.mdx` for shareable links.
|
|
92
|
+
- **Multi-project support**: registry at `~/.config/openkan/projects.json`,
|
|
93
|
+
one entry per project (id, name, root, addedAt, active).
|
|
94
|
+
`GET /api/projects`, `POST /api/projects`, `DELETE /api/projects/:id`,
|
|
95
|
+
`PATCH /api/projects/:id/active`. CLI flag `--project /abs/path` switches
|
|
96
|
+
at start time. Web UI project switcher in topbar (chip with dropdown).
|
|
97
|
+
- **Comment authorship**: every comment now stores `author` (git user
|
|
98
|
+
name or "agent:<name>"), `createdAt`, `resolvedBy`, `resolvedAt`.
|
|
99
|
+
Comments panel shows avatar + name + relative time + resolved footer.
|
|
100
|
+
POST `/api/tasks/:id/comments` requires `author` in the body.
|
|
101
|
+
- **File-tree safer**: paths containing `..` or escaping the docs root are
|
|
102
|
+
rejected with 400. Tree walks capped at 4 levels of depth.
|
|
103
|
+
- **REST endpoints added**: `GET /api/docs`, `GET /api/docs/<path>?raw=0/1`,
|
|
104
|
+
`GET /api/projects`, plus the multi-project CRUD endpoints above.
|
|
105
|
+
- **Comment composer fix**: ensure clicks on MDX blocks open the composer
|
|
106
|
+
reliably; POST includes `author`; the new comments appear in the panel.
|
|
107
|
+
|
|
108
|
+
### Added (Inline editing + Settings sidebar + UX consistency pass)
|
|
109
|
+
|
|
110
|
+
- **Inline editing on tasks.** Clicking the title or description in the
|
|
111
|
+
task view makes them contenteditable. Save on Enter / blur / Save
|
|
112
|
+
button. PATCH `/api/tasks/:id` with title/description; tags re-derive
|
|
113
|
+
automatically. The popup Edit modal is still in the footer as a fallback.
|
|
114
|
+
- **Settings dialog reorganized.** Sidebar with section nav (Project,
|
|
115
|
+
Server, UI, Sandbox, Import, Contributors, Advanced). Each section's
|
|
116
|
+
fields render in the right panel and persist via
|
|
117
|
+
`PATCH /api/config-sections/:sectionId`.
|
|
118
|
+
- **Docs viewer fixed.** `GET /api/docs/<path>` now returns both `html`
|
|
119
|
+
and `rendered` keys (alias) — fixes the "no content" rendering bug.
|
|
120
|
+
- **Project selector dropdown** now closes on outside click, Escape, or
|
|
121
|
+
after a selection — was staying open.
|
|
122
|
+
- **Right-click context menu actions** debugged and stabilized: flatten
|
|
123
|
+
submenus, drop capture-phase trickery, log every click for visibility.
|
|
124
|
+
Comments composer (with author field) is now wired correctly.
|
|
125
|
+
- **Archived items by default hidden** instead of crossed-out in the
|
|
126
|
+
board. The "Archived" filter toggle still exposes them when needed.
|
|
127
|
+
- **Full UI/UX consistency pass.** All buttons, chips, fields, transitions,
|
|
128
|
+
focus rings, typography, and spacing now use the unified design tokens
|
|
129
|
+
at the top of `web/style.css`. Spacing rhythm 4/8/12/16/24/32; radii
|
|
130
|
+
4/6/8/999; transitions 120ms; system-ui font stack.
|
|
131
|
+
- **Right-click context menu in the task view** with Copy / Copy as
|
|
132
|
+
Markdown / Open in new tab / Add comment here / Copy line / Copy block
|
|
133
|
+
hash.
|
|
134
|
+
- **Comment composer reliability.** `console.debug` markers on every
|
|
135
|
+
composer step so a failure is visible. Send `author` (from
|
|
136
|
+
`/api/me`) on POST.
|
|
137
|
+
- **New API endpoints:** `GET /api/config-sections`,
|
|
138
|
+
`PATCH /api/config-sections/:sectionId`.
|
|
139
|
+
|
|
140
|
+
## [0.2.0] — 2026-07-06
|
|
141
|
+
|
|
142
|
+
Released as **v0.2.0**.
|
|
143
|
+
|
|
144
|
+
- M2 shipped — Source link on every task.
|
|
145
|
+
- M3 shipped — Drift detection.
|
|
146
|
+
- M6 shipped — Sanity check script.
|
|
147
|
+
- M18 shipped — Final UI overhaul pass.
|
|
148
|
+
|
|
149
|
+
### Added (M2 — Source link on every task)
|
|
150
|
+
|
|
151
|
+
- Tasks imported from project docs via `kanban_import` now render a Source
|
|
152
|
+
field in the task MDX: `> 📄 Source: docs/roadmap.mdx:42 (imported from line 42)`.
|
|
153
|
+
- The web UI shows a clickable source chip on every imported task card and in
|
|
154
|
+
the task view's metadata panel. Clicking opens the source file at the
|
|
155
|
+
given line in a new tab.
|
|
156
|
+
|
|
157
|
+
### Added (M3 — Drift detection)
|
|
158
|
+
|
|
159
|
+
- Imported tasks now store a `sourceHash` (sha256 of the source file at
|
|
160
|
+
import time). The kanban server runs `fs.watch` on `.ok/` and
|
|
161
|
+
re-checks the hash on every file change; if the file's content hash
|
|
162
|
+
diverges, the task's `stale: true` flag flips on.
|
|
163
|
+
- The web UI shows a "Stale" badge on stale cards and a "Re-derive tags"
|
|
164
|
+
button in the task view to clear the flag.
|
|
165
|
+
|
|
166
|
+
### Added (M6 — Sanity check script)
|
|
167
|
+
|
|
168
|
+
- `npm run check` (or `node --experimental-strip-types scripts/sanity-check.ts`)
|
|
169
|
+
validates the active project's `.ok/` state. Catches: duplicate
|
|
170
|
+
task IDs, missing source paths, stale tasks in `done` column, and
|
|
171
|
+
orphaned per-task files. Exits non-zero on errors.
|
|
172
|
+
|
|
173
|
+
### Added (Dashboard polish)
|
|
174
|
+
|
|
175
|
+
- Source link chip on every task card and in the task view's metadata.
|
|
176
|
+
- Stale indicator (badge + button) for tasks whose source has changed.
|
|
177
|
+
- Full UI overhaul: tightened spacing rhythm (4/8/12/16/24/32),
|
|
178
|
+
unified button/checkbox/pill treatments, redesigned toasts, modal
|
|
179
|
+
animations, glassy topbar with `backdrop-filter: blur(12px) saturate(140%)`,
|
|
180
|
+
focus rings, hover/active feedback, ARIA.
|
|
181
|
+
- New `npm run check` script.
|
|
182
|
+
|
|
183
|
+
### Fixed
|
|
184
|
+
|
|
185
|
+
- Right-click context menu actions now fire reliably (flattened submenus,
|
|
186
|
+
removed dead submenu ghost elements that ate clicks, single
|
|
187
|
+
capture-phase dismiss listener).
|
|
188
|
+
- Inline comment composer was silently dropping `author` when the
|
|
189
|
+
/api/me round-trip raced the click; now reads the cached user
|
|
190
|
+
synchronously.
|
|
191
|
+
- Project selector dropdown closes on outside click, Escape, and the
|
|
192
|
+
second click on the trigger.
|
|
193
|
+
- Auto-detect on startup no longer creates duplicate entries (dedup
|
|
194
|
+
by resolved path).
|
|
195
|
+
- Live `changelog.jsonl` no longer commits to git; the per-task
|
|
196
|
+
`comments.json` and `inputs.json` do (for shared authorship).
|
|
197
|
+
- MDX frontmatter is no longer rendered as raw text in the task view;
|
|
198
|
+
stripped before `marked()` rendering. `metadata.description` on the
|
|
199
|
+
GET response is the frontmatter-stripped body text.
|
|
200
|
+
|
|
201
|
+
### Changed
|
|
202
|
+
|
|
203
|
+
- `package.json` adds `"check"` script.
|
|
204
|
+
- `install.sh` updated to deploy the new directories (`bin/`, `command/`,
|
|
205
|
+
`skill/`) and bumps the install message to mention four tabs.
|
|
206
|
+
|
|
207
|
+
## [0.1.0] — 2026-07-06
|
|
208
|
+
|
|
209
|
+
### Added
|
|
210
|
+
|
|
211
|
+
- Initial plugin release — openkan v0.1.
|
|
212
|
+
- Five-column kanban board (Backlog, To Do, In Progress, Review, Done) served
|
|
213
|
+
at `http://127.0.0.1:7777/`.
|
|
214
|
+
- Live UI updates over Server-Sent Events with polling fallback.
|
|
215
|
+
- Drag-and-drop between columns with optimistic UI and revert on error.
|
|
216
|
+
- Four initial agent tools: `kanban_add`, `kanban_move`, `kanban_start`,
|
|
217
|
+
`kanban_view`.
|
|
218
|
+
- Per-task actions: Start (dispatches the agent), Abort, Delete, View Artifact.
|
|
219
|
+
- MDX artifact mirror under `.ok/tasks/` and `.ok/sessions/`.
|
|
220
|
+
- Initial host-integrated installer.
|
|
221
|
+
|
|
222
|
+
[Unreleased]: https://github.com/PolderLabsVOF/openkan/compare/v0.3.0...HEAD
|
|
223
|
+
[0.3.0]: https://github.com/PolderLabsVOF/openkan/compare/v0.2.1...v0.3.0
|
|
224
|
+
[0.2.1]: https://github.com/PolderLabsVOF/openkan/releases/tag/v0.2.1
|
|
225
|
+
[0.2.0]: https://github.com/PolderLabsVOF/openkan/compare/v0.1.0...v0.2.0
|
|
226
|
+
[0.1.0]: https://github.com/PolderLabsVOF/openkan/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 PolderLabs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/PolderLabsVOF/openkan/main/web/brand/banner.svg" alt="OpenKan — local-first project management for people and coding agents" width="960">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">OpenKan</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
Tasks, goals, docs, and agent activity. In your repository.
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://www.npmjs.com/package/@polderlabs/openkan"><img src="https://img.shields.io/npm/v/%40drb0rk%2Fopenkan?color=6366f1" alt="npm version"></a>
|
|
13
|
+
<a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-339933" alt="Node.js 22 or newer"></a>
|
|
14
|
+
<a href="https://github.com/PolderLabsVOF/openkan/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-64748b" alt="MIT license"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#quick-start">Quick start</a> ·
|
|
19
|
+
<a href="#workspace">Workspace</a> ·
|
|
20
|
+
<a href="#agent-workflow">Agent workflow</a> ·
|
|
21
|
+
<a href="#development">Development</a> ·
|
|
22
|
+
<a href="https://github.com/PolderLabsVOF/openkan/issues">Report an issue</a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
OpenKan combines a local kanban dashboard with command-line planning for coding
|
|
26
|
+
agents. Manage work in the browser, record goals and completion evidence from the
|
|
27
|
+
terminal, and follow Claude Code activity without leaving the project. Project
|
|
28
|
+
records live in `.ok/`; the board and planning CLI need no hosted service.
|
|
29
|
+
|
|
30
|
+
## Quick start
|
|
31
|
+
|
|
32
|
+
**Requires Node.js 22 or newer and npm.** The npm package includes compiled
|
|
33
|
+
JavaScript, so installation needs neither TypeScript nor a build step. Claude Code
|
|
34
|
+
is optional and only needed for Claude-powered features.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm install -g @polderlabs/openkan
|
|
38
|
+
|
|
39
|
+
cd /path/to/your/project
|
|
40
|
+
openkan init
|
|
41
|
+
openkan start
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Installation adds the OpenKan Claude agent and skill, preserving locally edited
|
|
45
|
+
files. Chat selects OpenKan by default; use the agent picker for Claude Code or
|
|
46
|
+
another installed profile. To skip automatic installation, set
|
|
47
|
+
`OPENKAN_SKIP_AGENT_INSTALL=1`. If npm scripts are disabled, run
|
|
48
|
+
`openkan agent install` later. Use `--target DIR` for a custom Claude configuration
|
|
49
|
+
directory; `--force` explicitly replaces customized files.
|
|
50
|
+
|
|
51
|
+
Open [localhost:7777](http://127.0.0.1:7777/) if your browser does not open
|
|
52
|
+
automatically. Keep the server process running while using the dashboard.
|
|
53
|
+
`openkan init` is safe to run again in an existing workspace.
|
|
54
|
+
|
|
55
|
+
<details>
|
|
56
|
+
<summary><strong>Run without a global install</strong></summary>
|
|
57
|
+
|
|
58
|
+
Run these commands from your project directory:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npx --package @polderlabs/openkan openkan init
|
|
62
|
+
npx --package @polderlabs/openkan openkan start
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
</details>
|
|
66
|
+
|
|
67
|
+
<details>
|
|
68
|
+
<summary><strong>Update an existing installation</strong></summary>
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
openkan stop
|
|
72
|
+
npm install -g @polderlabs/openkan@latest
|
|
73
|
+
openkan start
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
If you installed the agent skill, refresh it separately:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
openkan skill install --agent all --force
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The package name is **`@polderlabs/openkan`**. Its executables are **`openkan`** and
|
|
83
|
+
**`ok`**; use the scoped name when installing or updating.
|
|
84
|
+
|
|
85
|
+
</details>
|
|
86
|
+
|
|
87
|
+
## Workspace
|
|
88
|
+
|
|
89
|
+
| Area | What you can do |
|
|
90
|
+
| --- | --- |
|
|
91
|
+
| **Home** | See registered projects, activity, and workspace statistics. |
|
|
92
|
+
| **Tasks** | Organize cards across Backlog, To Do, In Progress, Review, and Done. Search, filter, drag, archive, and manage subtasks. |
|
|
93
|
+
| **Chat** | Stream agent responses, mention tasks by dropping cards into the composer, and inspect expandable activity details. Sessions are scoped to their project. |
|
|
94
|
+
| **Docs** | Browse a folder tree, edit Markdown/MDX, preview documents, and generate drafts with the configured agent. |
|
|
95
|
+
| **Goals** | Track PRD goals alongside plans, tasks, and progress. |
|
|
96
|
+
| **Agents** | Explore a connected canvas of sessions, agents, subagents, and tasks, including discoverable Claude sessions started outside OpenKan for the current project. |
|
|
97
|
+
|
|
98
|
+
**Task mode** keeps the board central with a resizable chat panel on the left.
|
|
99
|
+
**Chat mode** gives the conversation the main workspace, with project tools on the
|
|
100
|
+
right. The navbar stays available in both modes. Changelog, contributors, and
|
|
101
|
+
insights are available through the workspace menu.
|
|
102
|
+
|
|
103
|
+
### Claude Code integration
|
|
104
|
+
|
|
105
|
+
Install and authenticate [Claude Code](https://code.claude.com/docs/en/setup)
|
|
106
|
+
separately, then configure the agent, model, effort, and permissions in OpenKan.
|
|
107
|
+
The board, docs, and offline planning commands remain usable without Claude Code.
|
|
108
|
+
|
|
109
|
+
OpenKan reads local Claude configuration and session activity and launches Claude
|
|
110
|
+
Code for chat turns and agent work. The chat activity view presents available file
|
|
111
|
+
operations, commands, tool calls, and subagent events. Visibility depends on the
|
|
112
|
+
events and local session data Claude exposes; OpenKan cannot display activity it
|
|
113
|
+
does not receive.
|
|
114
|
+
|
|
115
|
+
> **Local storage does not mean offline AI.** Agent requests use the configured
|
|
116
|
+
> provider and may send project content to that provider. Review permission settings
|
|
117
|
+
> before allowing an agent to run commands or change files.
|
|
118
|
+
|
|
119
|
+
## Agent workflow
|
|
120
|
+
|
|
121
|
+
Install the bundled skill so your coding agent can discover and use OpenKan's
|
|
122
|
+
commands instead of constructing HTTP requests:
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
openkan skill install --agent all
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Use `--agent claude` or `--agent codex` to install for one tool, or `--target DIR`
|
|
129
|
+
for a custom skill directory. npm installation does not change agent configuration;
|
|
130
|
+
skill installation is explicit.
|
|
131
|
+
|
|
132
|
+
### Track tasks without a server
|
|
133
|
+
|
|
134
|
+
Planning commands work directly with `.ok/`. From a project subdirectory, they find
|
|
135
|
+
the nearest existing `.ok/` workspace. `ok` is the shorter planning-only command:
|
|
136
|
+
`ok task list --json` and `openkan task list --json` use the same records.
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
openkan task add "Add a regression test" --owner codex --priority p1
|
|
140
|
+
openkan task list --json
|
|
141
|
+
|
|
142
|
+
# Replace TASK_ID with the ID printed by task add.
|
|
143
|
+
openkan task claim TASK_ID --owner codex
|
|
144
|
+
openkan task update TASK_ID --status review
|
|
145
|
+
openkan task complete TASK_ID --owner codex --evidence "npm test passed"
|
|
146
|
+
|
|
147
|
+
openkan progress --json
|
|
148
|
+
openkan doctor
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Claims default to a one-hour lease. Use `openkan task heartbeat TASK_ID --owner
|
|
152
|
+
codex` during longer work. Complete tasks only after verification, with evidence
|
|
153
|
+
of what passed.
|
|
154
|
+
|
|
155
|
+
### Connect goals, plans, and tasks
|
|
156
|
+
|
|
157
|
+
Goals belong to a **PRD**: a product requirements document describing the intended
|
|
158
|
+
outcome. Plans organize delivery; tasks record individual work items.
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
openkan prd add "First release" --vision "A tested, installable CLI" --goals "Ship package|Verify install"
|
|
162
|
+
|
|
163
|
+
# Replace PRD_ID and PLAN_ID with the IDs printed by the preceding commands.
|
|
164
|
+
openkan prd update PRD_ID --status active
|
|
165
|
+
openkan plan add "Release preparation" --prd PRD_ID --summary "Package and verify"
|
|
166
|
+
openkan task add "Test a clean installation" --prd PRD_ID --plan PLAN_ID --owner codex
|
|
167
|
+
|
|
168
|
+
openkan goal list --prd PRD_ID --json
|
|
169
|
+
openkan goal update PRD_ID g1 --status in_progress
|
|
170
|
+
openkan progress --prd PRD_ID --json
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Mark a goal `met` when its outcome is verified. Progress reports counts and
|
|
174
|
+
completion percentages; it does not automatically finish goals or plans.
|
|
175
|
+
|
|
176
|
+
### Work with dashboard cards
|
|
177
|
+
|
|
178
|
+
**Planning tasks and dashboard cards are related but distinct.** Creating a task
|
|
179
|
+
with `openkan task add` does not automatically create a visible board card. Use
|
|
180
|
+
`openkan board` for dashboard work, with the server running:
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
openkan project list
|
|
184
|
+
openkan project use PROJECT_ID
|
|
185
|
+
openkan board add "Test a clean installation" --column todo
|
|
186
|
+
openkan board list
|
|
187
|
+
openkan board move BOARD_TASK_ID doing
|
|
188
|
+
openkan board comment BOARD_TASK_ID "Clean installation verified" --author agent:codex
|
|
189
|
+
openkan board move BOARD_TASK_ID done
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Replace the example IDs with actual project and card IDs. Board commands check
|
|
193
|
+
that the selected dashboard project matches your current repository. If you track
|
|
194
|
+
both surfaces, include the planning task ID in the card description.
|
|
195
|
+
|
|
196
|
+
### Command reference
|
|
197
|
+
|
|
198
|
+
| Command | Purpose | Server needed |
|
|
199
|
+
| --- | --- | --- |
|
|
200
|
+
| `openkan task`, `plan`, `prd`, `goal` | Create and maintain planning records | No |
|
|
201
|
+
| `openkan progress --json` | Report planning status and ready tasks | No |
|
|
202
|
+
| `openkan doctor` | Validate the planning store | No |
|
|
203
|
+
| `openkan board` | Manage dashboard cards and comments | Yes |
|
|
204
|
+
| `openkan project list`, `project use ID` | Inspect or switch the dashboard project | Yes |
|
|
205
|
+
| `openkan agent capabilities` | Discover the agent command surface | No |
|
|
206
|
+
| `openkan agent context` | Read the active workspace context | Yes |
|
|
207
|
+
| `openkan agent start ID`, `agent abort ID` | Start or stop agent work for a card | Yes |
|
|
208
|
+
|
|
209
|
+
Use `openkan --help` and `ok help` for command syntax. Planning list/show commands
|
|
210
|
+
support `--json`; do not assume all mutation commands return JSON. For advanced
|
|
211
|
+
features, use `openkan api` or `openkan agent call`, as documented in the
|
|
212
|
+
[agent API reference](https://github.com/PolderLabsVOF/openkan/blob/main/skills/openkan/references/api.md).
|
|
213
|
+
These target the dashboard's selected project, which may differ from your shell's
|
|
214
|
+
current directory.
|
|
215
|
+
|
|
216
|
+
## Project data and privacy
|
|
217
|
+
|
|
218
|
+
OpenKan uses **`.ok/`**, not the legacy `.openkan/` directory. Important paths are:
|
|
219
|
+
|
|
220
|
+
```text
|
|
221
|
+
.ok/
|
|
222
|
+
├── openkan.json # Dashboard/runtime settings
|
|
223
|
+
├── config.json # Planning configuration
|
|
224
|
+
├── board.json # Canonical dashboard board
|
|
225
|
+
├── board.mdx # Rendered board document
|
|
226
|
+
├── tasks/ # Planning JSON records and board task workspaces
|
|
227
|
+
├── prds/ # PRDs, including their goals
|
|
228
|
+
├── plans/ # Delivery plans
|
|
229
|
+
├── sessions/ # Project chat/session records
|
|
230
|
+
├── index.json # Planning lookup index
|
|
231
|
+
└── locks/ # Task claims and leases
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Additional files appear as you use features. Keep task and planning records in
|
|
235
|
+
version control when you want a shared work history. Review `.gitignore` before
|
|
236
|
+
committing: sessions and runtime files can contain prompts, local paths, command
|
|
237
|
+
output, and other sensitive information.
|
|
238
|
+
|
|
239
|
+
The dashboard binds to `127.0.0.1:7777` by default and has no login layer. **Do not
|
|
240
|
+
expose it to an untrusted network or public reverse proxy.** It can launch agents
|
|
241
|
+
and modify project files. Use only trusted projects and review agent permissions.
|
|
242
|
+
|
|
243
|
+
## Server and troubleshooting
|
|
244
|
+
|
|
245
|
+
```sh
|
|
246
|
+
openkan status
|
|
247
|
+
openkan logs --tail 100
|
|
248
|
+
openkan config list
|
|
249
|
+
openkan start --no-open --project /absolute/path/to/project
|
|
250
|
+
openkan stop
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
| Problem | Check |
|
|
254
|
+
| --- | --- |
|
|
255
|
+
| `openkan: command not found` | Ensure your npm global executable directory is on `PATH`. Check `npm prefix -g` and reopen your terminal after changing your shell configuration. |
|
|
256
|
+
| An old install runs after updating | Check `command -v openkan` on macOS/Linux or `where openkan` on Windows. An earlier source install may appear before npm's executable on `PATH`. |
|
|
257
|
+
| Port 7777 is occupied | Stop the existing OpenKan server, or start with `--port 7788`. Use the same `--port` for server-backed CLI commands. |
|
|
258
|
+
| Board commands report a project mismatch | Run `openkan project list`, then `openkan project use PROJECT_ID` for the repository you are working in. |
|
|
259
|
+
| Claude chat does not respond | Confirm Claude Code works in your terminal, check the configured provider/model and permissions, then inspect `openkan logs --tail 100`. |
|
|
260
|
+
| Planning records fail validation | Run `openkan doctor` and inspect its reported files before editing or resetting data. |
|
|
261
|
+
|
|
262
|
+
## Development
|
|
263
|
+
|
|
264
|
+
Use **Node.js 22.6 or newer** for source development; source commands use Node's
|
|
265
|
+
experimental type-stripping support. Git is required to clone the repository.
|
|
266
|
+
|
|
267
|
+
```sh
|
|
268
|
+
git clone https://github.com/PolderLabsVOF/openkan.git
|
|
269
|
+
cd openkan
|
|
270
|
+
npm ci
|
|
271
|
+
|
|
272
|
+
npm run openkan -- init
|
|
273
|
+
npm run openkan -- start --no-open
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Run verification in another terminal:
|
|
277
|
+
|
|
278
|
+
```sh
|
|
279
|
+
npm test # Unit and integration tests
|
|
280
|
+
npm run typecheck # TypeScript checks
|
|
281
|
+
npm run check # Repository sanity checks
|
|
282
|
+
npm run test:package # Build, pack, install, and smoke-test the npm artifact
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
`npm run build` generates `dist/`. The npm launchers use that compiled output when
|
|
286
|
+
present; use `npm run openkan -- ...` to run directly from edited source rather
|
|
287
|
+
than an older build.
|
|
288
|
+
|
|
289
|
+
<details>
|
|
290
|
+
<summary><strong>Alternative source installer (macOS/Linux)</strong></summary>
|
|
291
|
+
|
|
292
|
+
For a dedicated source installation rather than the published npm package, run
|
|
293
|
+
this from a reviewed checkout. It requires Bash, Node.js 22.6+, and npm:
|
|
294
|
+
|
|
295
|
+
```sh
|
|
296
|
+
bash install.sh
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The installer defaults to `~/.local/share/openkan` on Linux (respecting
|
|
300
|
+
`XDG_DATA_HOME`) and `~/Library/Application Support/OpenKan` on macOS. It links
|
|
301
|
+
`openkan` in `~/.local/bin`, which must be on `PATH`.
|
|
302
|
+
|
|
303
|
+
Override locations with `OPENKAN_HOME` and `OPENKAN_BIN_DIR`. This installer additionally installs skills for Codex and shared agents; set `OPENKAN_SKIP_AGENT_SKILLS=1` to
|
|
304
|
+
skip that step. Use the same installation method for subsequent updates to avoid
|
|
305
|
+
competing command paths.
|
|
306
|
+
|
|
307
|
+
</details>
|
|
308
|
+
|
|
309
|
+
## Documentation and contributing
|
|
310
|
+
|
|
311
|
+
- [Planning guide](https://github.com/PolderLabsVOF/openkan/blob/main/docs/OK-PLANNING.md)
|
|
312
|
+
- [Agent skill and workflow](https://github.com/PolderLabsVOF/openkan/blob/main/skills/openkan/SKILL.md)
|
|
313
|
+
- [Agent API reference](https://github.com/PolderLabsVOF/openkan/blob/main/skills/openkan/references/api.md)
|
|
314
|
+
- [Claude integration](https://github.com/PolderLabsVOF/openkan/blob/main/docs/CLAUDE-NATIVE.md)
|
|
315
|
+
- [Contributing](https://github.com/PolderLabsVOF/openkan/blob/main/CONTRIBUTING.md)
|
|
316
|
+
- [Changelog](https://github.com/PolderLabsVOF/openkan/blob/main/CHANGELOG.md)
|
|
317
|
+
|
|
318
|
+
OpenKan is [MIT licensed](https://github.com/PolderLabsVOF/openkan/blob/main/LICENSE).
|