local-kanban

local-kanban

A local kanban board built for working in tandem with Claude Code: the human plans and accepts tasks, Claude takes them from the queue, does the work and reports back — all through a token-efficient CLI called kb. Optionally mirrors everything to GitHub (issues + Projects v2).

Русская версия — README.ru.md.

How you use it

• Write the task in the project's Backlog — a title is enough, the description can come later.
• Move it to To do once it is ready to be picked up. That column is the queue.
• Press the copy button on the To do column ("Copy the tasks as a job for Claude") and paste what it copied into Claude Code — the chat or the terminal, either works.
• Claude takes it from there. It reads the task, does the work, leaves comments as it goes, commits and pushes, deploys if the project has a deploy skill, ties the commit to a GitHub issue if sync is on — and stops at Review. It never marks anything done.
• You accept. Look at what came out and move the card to Done, or send it back with a note. That note is the first thing Claude reads when it picks the task up again.

A trick worth knowing. Let Review pile up — ten, twenty, thirty cards. Then add one more task to the board: go through everything in Review, try to break it, move what survives to Done. Claude will take the whole column in one pass, and it saves a lot of clicking. Do that one in a fresh chat: the session that just wrote the code is the worst judge of it, because it remembers what it meant rather than what it actually shipped.

Why

• A queue for Claude, not just a board. Statuses model the real loop: backlog → todo → prep → doing → deploy → review → done. Claude pulls the next task with kb take, works, and stops at review — accepting is always the human's call.
• Local-first. Everything lives in a single SQLite file on your machine. GitHub sync is optional and off until you configure it.
• Honest metrics. Work time is measured only while Claude actually works; the dashboard shows streaks, cycle time and what's waiting for you.

Security model — read this first

The server listens on 127.0.0.1 only and has no authentication. The board is strictly local: your machine is the trust boundary. Never expose the port to the network (no reverse proxies, no 0.0.0.0, no port forwarding). Third-party integrations should run on the same machine and talk to 127.0.0.1 (see docs/API.md).

The board holds no credentials. A project can name an SSH host to deploy to, but neither a key nor a password is ever entered here: the board simply runs ssh <host>, and who you are, on which port and with which key is decided by your own ~/.ssh/config — the same file your terminal uses. A password will not work at all, because the board connects without prompts, so key-based access is required. The short test: if ssh <host> works in your terminal, it works here.

Requirements

• Node.js ≥ 22 (macOS or Linux) — 24 LTS or newer is what most people have
• Optional, only for GitHub sync: gh CLI authenticated with the project scope: gh auth login && gh auth refresh -s project

Install

npm install -g local-kanban
local-kanban            # setup wizard
local-kanban start      # board at http://localhost:3100

The wizard asks for the port, the data directory, whether you want GitHub sync, and whether to install the two Claude Code skills — the board's own and the deploy one — into ~/.claude/skills. Every question has a default, so Enter-Enter-Enter is enough. It also writes ecosystem.config.cjs for autostart under pm2.

local-kanban start takes --port <N> and --data <dir>. Data lives in ~/.local-kanban by default, outside the package directory, so updating the package never touches your board.

From source:

git clone <repo-url> local-kanban && cd local-kanban
npm install
npx local-kanban     # setup wizard (optional)
npm start            # board at http://localhost:3100

To get the kb command globally: npm link (or npm install -g .).

First launch shows an empty dashboard with an optional demo project — one click creates it, one click removes it.

Let Claude finish the setup

The last step of the first-run wizard shows a ready-made prompt (in the board's language). Paste it into Claude Code and it will walk you through the rest — check that kb works, ask whether you want the GitHub mirror, register your first projects with their paths and deploys, and verify the result. The same prompt lives in Settings → About, so you can come back to it later.

Claude Code skills

The repo ships two skills for Claude Code in skills/:

• skills/kanban — teaches Claude the task workflow (kb take → work → kb review);
• skills/deploy — a generic deploy flow driven by the project registry (kb info).

Install by symlink or copy:

ln -s "$(pwd)/skills/kanban" ~/.claude/skills/kanban
ln -s "$(pwd)/skills/deploy" ~/.claude/skills/deploy

GitHub sync (optional)

Set the owner and issues repo in Settings → Sync on the board (or env KB_GH_OWNER / KB_GH_REPO). Without them the board runs in local-only mode: no queue, no warnings. With them, every task becomes an issue and every project gets a kb: <slug> GitHub Project with matching columns. Sync is one-way (board → GitHub) and runs in the background.

One repository holds the issues for the whole board, not one per project, and you create it yourself before filling the fields. Make it private: titles, descriptions and comments are copied there in full, and this is the only feature that sends anything off your machine. The gh CLI has to be signed in with the project scope (gh auth login && gh auth refresh -s project) - without that scope the issue is still created, but the card never appears on the Projects board, which is a confusing way to find out.

Updating

From npm:

The board checks for a new version itself and offers a button in Settings → About — it installs the update the way the board was installed and, under a process manager, restarts and reloads the page on its own. Started by hand, it says the update is in place and waits for you to start it again.

By hand, from an npm install:

npm install -g local-kanban@latest
local-kanban skills          # refresh the Claude Code skills — they are a copy, not a link

From a clone:

npm run update   # git pull + npm install + pm2 restart (if applicable)

Your data is never touched by updates: data/ is gitignored and schema migrations run automatically on start — with a pre-migration snapshot saved to data/backups/pre-migrate/ before anything changes.

Rollback: stop the server, restore the latest file from data/backups/ (daily) or data/backups/pre-migrate/ over data/kanban.db, then git checkout <previous tag> and start again.

Releases live in main (stable, tagged); day-to-day development happens in dev.

Environment variables

Variable	Default	Meaning
PORT	3100	HTTP port (bound to 127.0.0.1)
KB_DATA_DIR	./data	data directory (SQLite, attachments, backups)
KB_LOCAL_ROOT	~/claude-projects	root folder scanned for local projects
KB_URL	http://127.0.0.1:3100	board URL for the kb CLI
KB_GH_OWNER / KB_GH_REPO	—	GitHub sync target; empty = sync off (can also be set in Settings)
KB_PANEL_URL	—	custom HTTP source of service statuses; empty = local pm2 jlist
KB_PANEL_INFO	—	optional path to an external panel's info.json for category sync
KB_SSE_MAX	20	cap on concurrent SSE connections
KB_SKILLS_EXTRA	—	extra skill root directories, :-separated
KB_GH_BIN	—	path to the gh binary when it is not in a usual place (Homebrew, /usr/bin, ~/.local/bin)

The legacy names PANEL_URL and PANEL_INFO (without the prefix) still work as a fallback.

Metrics and the noclaude label

Tasks done by hand (without Claude) get the noclaude label — they are counted separately on the dashboard and excluded from Claude's metrics (work time, cycle, completion %), which would otherwise be skewed by their zero work time. The label is optional and can be added later. Manual tasks are also allowed to jump straight to review/done.

Extending

The full HTTP API and the SSE event stream are the official extension point — build bots, stats, integrations as separate programs, no plugins inside the page. See docs/API.md.

Development

node --test   # DB isolated via KB_DATA_DIR

See CONTRIBUTING.md for the dev setup, branch flow and the schema-migration rule. The architecture is described in ARCHITECTURE.md, and what changed between versions in CHANGELOG.md.

UI language

English is the source language of the interface; Russian comes as a translation. The board follows your system language and can be switched in Settings → General — a string with no translation yet stays English rather than leaking into the wrong locale.

Using it at work

The board is MIT-licensed and free for everyone: nothing is switched off and there is nothing to activate. If it earns you money — inside a company, or on paid client work — $12 a year per person keeps it maintained. A request, not a rule: docs/COMMERCIAL.md.

What's planned

Not promises — the direction the project is heading:

• More interface languages. English and Russian are in. The dictionary is a single file, so a translation is a pull request rather than a project.
• Working with Codex the way it works with Claude Code. The kb CLI and the status model are not Claude-specific; only the skills are.
• Plugins, done properly — a manifest with declared permissions and a sandboxed frame, not a checkbox that trusts whatever you installed. A plugin that can read your tasks and reach the network has to say so before it runs.
• A board a team can share — over one local network to start with, without turning a local-first tool into a service that needs accounts, a server and someone to run it.
• Attaching a CLI straight to the board, so an agent can be driven from the card instead of from a terminal window next to it.

And the long one: get the dream job at Anthropic and build this for everyone.

License

MIT.