@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.
Files changed (114) hide show
  1. package/CHANGELOG.md +226 -0
  2. package/LICENSE +21 -0
  3. package/README.md +318 -0
  4. package/agents/openkan.md +254 -0
  5. package/bin/install-agent.mjs +63 -0
  6. package/bin/ok.mjs +17 -0
  7. package/bin/openkan.mjs +10 -0
  8. package/dist/.claude/skills/ok-planning/SKILL.md +285 -0
  9. package/dist/.claude/skills/ok-planning/references/integration.md +153 -0
  10. package/dist/.claude/skills/ok-planning/references/schemas.md +270 -0
  11. package/dist/.claude/skills/ok-planning/references/workflows.md +185 -0
  12. package/dist/.claude/skills/ok-planning/scripts/ok-init.sh +14 -0
  13. package/dist/.claude/skills/ok-planning/scripts/ok-resume.sh +38 -0
  14. package/dist/.claude/skills/ok-planning/scripts/ok-status.sh +24 -0
  15. package/dist/agents/openkan.md +254 -0
  16. package/dist/bin/install-agent.mjs +76 -0
  17. package/dist/bin/ok-install.js +58 -0
  18. package/dist/bin/ok.js +138 -0
  19. package/dist/bin/openkan.js +804 -0
  20. package/dist/commands/organize.md +15 -0
  21. package/dist/kanban/agent-profile.js +8 -0
  22. package/dist/kanban/archive.js +49 -0
  23. package/dist/kanban/bizar.js +242 -0
  24. package/dist/kanban/board.js +367 -0
  25. package/dist/kanban/bulk.js +139 -0
  26. package/dist/kanban/changelog.js +186 -0
  27. package/dist/kanban/chat.js +1280 -0
  28. package/dist/kanban/claude-state.js +974 -0
  29. package/dist/kanban/comments.js +80 -0
  30. package/dist/kanban/docs.js +144 -0
  31. package/dist/kanban/fs.js +163 -0
  32. package/dist/kanban/git.js +196 -0
  33. package/dist/kanban/images.js +140 -0
  34. package/dist/kanban/import.js +295 -0
  35. package/dist/kanban/inputs.js +94 -0
  36. package/dist/kanban/insights.js +140 -0
  37. package/dist/kanban/io.js +75 -0
  38. package/dist/kanban/mdx-render.js +348 -0
  39. package/dist/kanban/mdx.js +231 -0
  40. package/dist/kanban/projects.js +545 -0
  41. package/dist/kanban/search.js +121 -0
  42. package/dist/kanban/server.js +3296 -0
  43. package/dist/kanban/tags.js +124 -0
  44. package/dist/kanban/template.js +145 -0
  45. package/dist/kanban/tsx-sandbox.js +187 -0
  46. package/dist/kanban/watcher.js +270 -0
  47. package/dist/ok/commands/goal.js +65 -0
  48. package/dist/ok/commands/index.js +87 -0
  49. package/dist/ok/commands/init.js +15 -0
  50. package/dist/ok/commands/plan.js +155 -0
  51. package/dist/ok/commands/prd.js +202 -0
  52. package/dist/ok/commands/progress.js +31 -0
  53. package/dist/ok/commands/task.js +377 -0
  54. package/dist/ok/ids.js +98 -0
  55. package/dist/ok/lock.js +156 -0
  56. package/dist/ok/migrate.js +197 -0
  57. package/dist/ok/schemas.js +402 -0
  58. package/dist/ok/storage.js +222 -0
  59. package/dist/skills/openkan/SKILL.md +111 -0
  60. package/dist/skills/openkan/agents/openai.yaml +4 -0
  61. package/dist/skills/openkan/examples/simple-task.mdx +34 -0
  62. package/dist/skills/openkan/examples/with-ask.mdx +32 -0
  63. package/dist/skills/openkan/examples/with-choice.mdx +51 -0
  64. package/dist/skills/openkan/examples/with-preview.mdx +54 -0
  65. package/dist/skills/openkan/references/api.md +169 -0
  66. package/dist/skills/openkan/templates/task.mdx +46 -0
  67. package/dist/web/api.js +257 -0
  68. package/dist/web/app.js +4251 -0
  69. package/dist/web/bizar.js +39 -0
  70. package/dist/web/brand/agent-activity-sprite.svg +1 -0
  71. package/dist/web/brand/banner-docs.svg +24 -0
  72. package/dist/web/brand/banner.svg +32 -0
  73. package/dist/web/brand/empty-sessions.svg +17 -0
  74. package/dist/web/brand/empty-tasks.svg +17 -0
  75. package/dist/web/brand/favicon.svg +9 -0
  76. package/dist/web/brand/infinity-loader-animated.svg +220 -0
  77. package/dist/web/brand/infinity-loader-spritesheet.svg +230 -0
  78. package/dist/web/brand/logo-wordmark.svg +10 -0
  79. package/dist/web/brand/logo.svg +9 -0
  80. package/dist/web/brand/pixel-infinity-track.svg +1 -0
  81. package/dist/web/brand/social-card.svg +26 -0
  82. package/dist/web/changelog-view.js +456 -0
  83. package/dist/web/charts.js +269 -0
  84. package/dist/web/chat-sidebar.js +2397 -0
  85. package/dist/web/chat-status-motion.js +154 -0
  86. package/dist/web/claude-pane.js +820 -0
  87. package/dist/web/command-palette.js +381 -0
  88. package/dist/web/contributors-view.js +317 -0
  89. package/dist/web/cross-tab.js +102 -0
  90. package/dist/web/docs-view.js +168 -0
  91. package/dist/web/experience.css +165 -0
  92. package/dist/web/goals-view.js +45 -0
  93. package/dist/web/home-view.js +113 -0
  94. package/dist/web/images.js +311 -0
  95. package/dist/web/index.html +485 -0
  96. package/dist/web/insights.js +217 -0
  97. package/dist/web/keyboard.js +446 -0
  98. package/dist/web/mdx-viewer.js +600 -0
  99. package/dist/web/path-picker.js +787 -0
  100. package/dist/web/preview-frame.html +187 -0
  101. package/dist/web/settings.js +582 -0
  102. package/dist/web/style.css +8545 -0
  103. package/dist/web/task-view.js +1759 -0
  104. package/dist/web/vendor/gsap.min.js +11 -0
  105. package/dist/web/workspace.css +1513 -0
  106. package/package.json +71 -0
  107. package/skills/openkan/SKILL.md +111 -0
  108. package/skills/openkan/agents/openai.yaml +4 -0
  109. package/skills/openkan/examples/simple-task.mdx +34 -0
  110. package/skills/openkan/examples/with-ask.mdx +32 -0
  111. package/skills/openkan/examples/with-choice.mdx +51 -0
  112. package/skills/openkan/examples/with-preview.mdx +54 -0
  113. package/skills/openkan/references/api.md +169 -0
  114. 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).