k0-board
v0.13.0
Published
A board of sticky notes that drives your Claude Code sessions
Maintainers
Readme
k0
A board of sticky notes that drives your Claude Code sessions. One column per project, one story per piece of work. From a story you open a real terminal, and on the story you see at a glance whether the session is working, has finished, is asking you something, or has a plan waiting for your approval.
It exists because of one specific moment: four terminals open, and no way to tell which one is waiting for you without clicking through all four.
If you have used a kanban board, an infinite canvas like Miro, and a wall of paper sticky notes, you have already seen the three pieces k0 is made of: stories standing in columns, a board that pans and zooms instead of scrolling, and notes that sit at their own slightly crooked angle. What is different is what those things are underneath. A column is a repository, not a stage — the stories reorder themselves by who is waiting for you, rather than being pushed along a pipeline. (One switch in the top bar lays the same stories out as a list instead, for the days you are planning rather than working.) A story drives real Claude Code sessions — it opens a terminal, it knows what that session is doing, and it goes on saying so while you are looking somewhere else. A story may have had several over its life, one at a time, and it keeps all of them.

Contents · Install · k0 Cloud · How it is used · The backlog · The ChangeLog · What's New · The files of a session · What it costs · Filling the board with what you have already done · The statuses · The four modes · Shift+Enter starts a new line · Pasting into the terminal · How it is put together · Security · What is not here yet · Contributing · License
Install
npx k0-boardThat is the whole thing. It tells you everything it is about to change, asks, and only then does
it — and when it is finished it opens the board in your browser, so there is no address to write
down anywhere. k0-board uninstall undoes all of it.
k0 is published on npm as k0-board: one package, no
dependencies, nothing to compile. npx fetches it, runs the installer once and leaves nothing
behind — what stays on the machine is the copy the installer puts in ~/.k0/app, not an npx
cache that could be swept away under a running service. Installing it globally with
npm install -g k0-board works too, if you would rather have the command on your PATH.
To update it, run the installer again with npx k0-board@latest: it replaces the copy and
restarts the service. Your board is never in the way — it lives in ~/.k0/k0.db, outside
everything the installer touches, and uninstall leaves it there as well.
Every release is published by GitHub Actions with a signed provenance statement: proof, which
npm audit signatures will check for you, that the tarball was built from a particular commit of
this repository rather than uploaded by somebody who happened to have a password. (0.1.0 predates
that and went out from a laptop.)
The commands
| | |
|---|---|
| k0-board install | install and start it — this is what npx k0-board runs |
| k0-board uninstall | undo everything install did; your board stays |
| k0-board start | run the server in the foreground, installing nothing |
| k0-board restart | restart the service |
| k0-board status | is it running? exits 0 if it is, 1 if it is not |
| k0-board doctor | what this machine can and cannot do, and why — and where k0 Cloud stands |
| k0-board skills | copy the /k0-* commands into ~/.claude/skills/, or bring the ones already there up to date — the installer's question, on its own |
| k0-board login | sign in to k0 Cloud with GitHub or Google: opens the board, where the buttons are |
| k0-board logout | sign out; the board stays on this machine and stops syncing |
--yes does not ask. --from-source points the service at the directory you are in instead of
copying it, which is what you want while working on k0 itself. --no-open finishes without
opening a browser, which is what you want over SSH. --no-<name> skips one optional change —
--no-lid-sleep, --no-shift-enter. K0_PORT moves the board off 4319.
From a clone, if you would rather look first:
git clone https://github.com/alessio-ragni/k0-board.git
cd k0-board
node bin/k0-board.js startThat runs the server in the foreground and opens the board. Nothing is installed and nothing outside the directory is touched.
The board lives at http://k0.localhost:4319, which is the address both install and start
open for you. If that name does not resolve on your machine — which happens on Windows, because
only browsers are obliged to know that .localhost means this computer — k0 opens
http://127.0.0.1:4319 instead, and says so.
Requirements
- Node 24 or newer. k0 keeps the board in SQLite through
node:sqlite, which is built into Node — there is nothing to install and there are no npm dependencies at all. - Claude Code, obviously.
- git, for the mark on each story that says whether your work is safe.
- macOS: Xcode Command Line Tools, to build the menu bar icon. Nothing else.
- Linux: tmux, which is how k0 drives terminals there. Optionally
xdotoolfor window placement, andpython3with PyGObject for the tray icon. - Windows: PowerShell, which is already there. Windows Terminal is recommended.
Which platforms this really works on
| | macOS | Linux | Windows | |---|---|---|---| | Open a terminal and run Claude Code in it | ✅ | ✅ tmux | ✅ | | Read the terminal to know when it is ready | ✅ | ✅ | ❌ waits a fixed moment instead | | Leave your prompt in place, unsent | ✅ needs Accessibility | ✅ | ✅ | | Rename a running session when its title changes | ✅ needs Accessibility | ❌ when it ends | ❌ when it ends | | Place, resize and raise windows | ✅ | ✅ X11 only | ✅ | | Large text in terminals for driving mode | ✅ | ❌ | ❌ | | Keep the machine awake | ✅ | ✅ | ✅ | | Keep working with the lid closed | ✅ | ❌ system setting | ❌ system setting | | Tray icon and notifications | ✅ | ✅ GNOME/KDE | ✅ | | Clicking a notification takes you to that terminal | ✅ needs the permission | ✅ if the desktop honours actions | ✅ |
macOS is the only platform the author has. Linux and Windows are written from the documentation and reviewed carefully, and the logic they share with macOS is tested on all three in CI — but nobody has yet sat in front of a Linux desktop or a Windows machine and watched k0 open a terminal on it. If you are the first, please say what happened, including the parts that worked.
k0-board doctor prints this same table for your actual machine, with a sentence explaining
every ❌.
What installing it changes
Nothing on this list happens before you have seen it and said yes. Everything on it is undone by
k0-board uninstall, and any single item can be skipped with --no-<name>.
| What | Where | Why |
|---|---|---|
| A copy of k0 | ~/.k0/app | so the service does not point at a temporary npx cache |
| Your board, settings, logs and cache | ~/.k0/ | %LOCALAPPDATA%\k0 on Windows |
| A service that starts at login | LaunchAgents · systemd user unit · Task Scheduler | so k0 is simply there |
| macOS only — one administrator rule | /etc/sudoers.d/k0-pmset | to keep the Mac awake with the lid closed. Asks for your password once, and grants exactly two command lines |
| macOS only — one key binding | your Terminal profile (backed up first) | so Shift+Enter starts a new line |
| macOS only — Accessibility for node | you grant it by hand, in System Settings | so k0 can place a prompt without sending it |
| The commands, and the k0-links mod, if you want them | ~/.claude/skills/ | Claude Code looks there and in the repository you have open, and nowhere else. Asked once; installing again brings the copies up to date without asking |
That last one deserves a sentence of its own: a process with the Accessibility permission can
send keystrokes to any application, and here it is granted to your node, not to a signed k0
app. Skipping it breaks nothing — the prompt gets typed and the session starts by itself.
k0 needs an account, and it talks to exactly three places, the third only if you ask. You sign in with GitHub or Google, and your board is kept in sync with k0 Cloud — k0's own database, on Supabase, in the EU — so it survives a lost laptop and can be read from a browser. The board you work on is still the copy on this machine: without a connection k0 keeps working, and catches up when the connection is back.
The second place is the public npm registry. Once a day k0 asks it what the newest version of
k0-board is, so the board can mention that there is one. The package name is in the address and
nothing else is in the request: not the version you are running, not your repositories, not your
commits, not your board, not an identifier of any kind. Nothing is downloaded and nothing is run —
k0 cannot update itself. Set "updateCheck": false in ~/.k0/config.json and that socket is never
opened.
The third place is there only for the dictation trial, on a Mac with macOS 26: when you press
Download the model on its page, and only if no copy is on the Mac already, k0 fetches the
Whisper speech model from https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin,
once, into ~/.k0/dictate/models/. The model comes here; nothing you say goes there. Everything
else stays as it was: no fonts fetched, no telemetry, no analytics, no git fetch, and the models
still run here, through your own Claude Code.
k0 Cloud
Your board lives on your machine and keeps working with no network at all. k0 Cloud holds a copy
of it, so it survives a lost laptop, reaches your other machines, and — coming with the site — can
be read from a browser at k0-board.com/app/.
Who owns which piece of it, where the keys live and how somebody is let in: docs/cloud.md.
Signing in
The first time you open the board it shows Connect your account, with a button for GitHub and
one for Google. Those are the only two ways in; there is no password of k0's own. The browser goes
to the provider, you say yes there, and it comes back to the board on this machine —
http://k0.localhost:4319/auth/callback — which finishes the sign-in by itself. k0 never sees a
password, and the one-time code that comes back is worth nothing on its own: it only works
together with a secret this machine made before sending the browser off (PKCE).
What keeps you signed in is written to ~/.k0/cloud.json, readable by you and nobody else.
k0-board login from a terminal does the same thing: it opens the board, which is where the
buttons are, or says who is already signed in.
The screen only stands in front of the board when there is a way past it. If the cloud has no sign-in switched on yet, the board simply opens: blocking it for something you cannot do anything about would be k0's failure passed off as yours. Offline on the very first start, the screen says the cloud cannot be reached instead of offering buttons that would not work.
Early access
Signing in is not the same as being let in. k0 is in early access: an account opens once it has been approved, by hand. Until then the board says You are on the list, nothing is sent anywhere, and the board goes on working exactly as before. It notices the approval by itself — no restart, no second sign-in. Use another account on that screen signs out and starts again.
(Approving accounts is done from an admin page that is coming with the site.)
What goes up, and what never leaves the machine
Every few seconds, while you are signed in and let in, k0 sends what changed and fetches what your
other machines changed: epics, stories, tasks, decisions, rounds, checklists, dependencies, the
Log, and the sessions a story has had. A repository is named in the cloud by its origin remote,
cleaned of any password and of the difference between git@ and https://, so the same
repository checked out on two machines is one column; a repository with no remote stays a name
known only to this machine.
What never leaves: which terminal window a session is in, the folder it is working in, and the commit it started at. Nothing from your repositories either — not files, not diffs, not commits.
Sessions go up but do not come down. A session is a terminal on the machine that opened it; the other machine has nothing to attach it to, so it would only be a ghost there. The cloud keeps their status so the web board can show it.
When the same thing was changed in two places, a change made here and not yet sent wins over one arriving from the cloud — it is what the person at this machine just did — and in the cloud a later change wins over an older one that arrives late, so a laptop coming back after a day away does not put yesterday's version over this morning's.
Offline, and keys with a ~
A key is one number for your whole account: K150 is the same story whichever repository it is in
and whichever machine is looking at it. So the number comes from the cloud, which is the only place
two machines can agree on what comes next. k0 asks for it the moment you create a story or an
epic, and waits at most two and a half seconds.
When the cloud does not answer, the story is made anyway, with a provisional key: K~3. It
works everywhere a key does. As soon as the cloud is back the sync gives it its real number, oldest
first, and renames its file in .k0/. Nothing is reserved in advance, so the numbers still run in
the order the stories were made.
Moving a board you already had
A board that existed before you signed in was numbered on this machine — per repository, if it is
older than k0 Cloud — and the cloud's counter starts somewhere else. Using the cloud's numbers
straight away would give your next story a K1 the board already has. So the first time an
account is linked on a machine whose board has stories, nothing is sent and no number is taken
from the cloud until the board has been moved.
The board offers it: Move your board to k0 Cloud. Show me the new numbers lists every story and epic, repository by repository, with its old key beside its new one, and says how many pieces of text — a plan, a prompt, a decision — mention a key and will be updated with it. Nothing has changed yet at that point. Move it then:
- copies the whole database to
~/.k0/backups/k0-before-cloud-<time>.db, in one consistent file; - renumbers every story and epic once, in the order they were made, starting from the cloud's next number;
- rewrites the keys written inside the text — plans, prompts, bodies, decisions, rounds, the Log,
the checklist — within the same repository, since that is the only place a bare
K12ever meant anything; - renames the files in
.k0/; - writes
~/.k0/backups/k0-before-cloud-<time>.keys.json, every old key beside its new one; - moves the cloud's counter past the board, and sends the whole board up.
When it is done the board says how many it moved, from which number, and where the two files are, and stays on that page until you close it.
Not now means not now: the board keeps its old numbers and keeps working, and the offer comes back the next time the board is opened.
The account chip
At the end of the top bar, once you are signed in: your picture, and a dot. Green, everything is in the cloud. Amber, changes are waiting to go up — or a story still has a provisional key. Grey, the cloud cannot be reached and the board is carrying on by itself. Click it for who is signed in, Sync now, and Sign out.
Signing out
Sign out in that menu, or k0-board logout. The board stays on this machine exactly as it is;
it stops syncing, keys are counted on this machine again, and nothing is queued for later.
k0-board doctor has a k0 Cloud section: who is signed in, whether they have been let in,
whether the board still has to be moved, whether the cloud answers, and how many changes are
waiting.
Switching it off
K0_CLOUD=off in the server's environment switches the cloud off entirely: no sign-in screen, no
chip, no socket. It is meant for working on k0 itself and for the tests. Without an account, keys
are still one counter for the whole board rather than one per repository, kept on this machine.
How it is used
The board
A note at rest is small on purpose: the story's key and how long it has been in its state on the top line, the title — always whole, on as many lines as it takes — and one thin line under it — session closed, the mark that says it waits on something, and the arrow, sun and flag at its right end. The repository's name is not on it: it is written at the top of the column the note stands in. That is what lets a column hold twice the notes it used to.
Stop the pointer on a note and it opens: what it is about (its notes and the prompt), its epic and its buttons come out, and the notes below move down to make room. It stays open for as long as the pointer is in that column — move down to the next note and the first one stays as it is, so the column does not bounce under you — and every note in the column closes when the pointer leaves it. Passing over a note in a hurry does not open it, and nothing opens while an arrow is being drawn, so the note it is aimed at does not slide away from it. The keyboard opens a note too, when one of its buttons has the focus.
+ — at the left, next to k0, and next to every repository name on the board: that one opens a story with the repository already chosen. Two fields and no more: the repository and a title. Nothing is asked about what the story is for, because both ways out of the dialog open a terminal and you say it there. (With a backlog behind the board the
+at the left is a menu of two — a story typed here, or an epic told to a terminal — the dialog gains a field for the story's epic, and the two buttons are Discuss and Quick Start. Editing a story that exists adds a list of notes, which sit on the post-it for you to read and are never sent to Claude Code. It is written out below.)The repository has to be picked from the list (searchable, most used at the top; arrow keys to move, Enter takes the highlighted row): a name typed by hand does not count. On leaving the field, if what you typed identifies exactly one repository it takes that one; otherwise the field empties — either you select one or there is nothing.
At the bottom there are Save and Start: Start saves and launches the session immediately. The X at the top closes without saving.
The title normalises as you type: a capital at the start of every word, dashes instead of spaces, and the capitals you typed stay where you put them —
fix apibecomesFix-Api, whileFix APIstaysFix-API. What you see in the field is exactly the name the session will have, behind the story's key:K1136-Fix-API. With a dozen sessions open, the key is what ties a terminal window, or a line ofclaude --resume, back to its note. A story made offline, while its key is still provisional (K~3), names its session by the title alone, and the key goes in front the moment the cloud hands out the real number. A title that already begins with its own key does not get it twice. The title on the note stays as you typed it, without the key.the pencil (top right of a story) — the only way to open the editor: clicking the story itself does nothing. On a story that is already finished, where there is nothing left to edit, the bin takes its place.
Changing the title — only the title; the prompt has nothing to do with it — or the key renames every session the story has had, the older ones too, in three places at three moments. The window's title bar, immediately, session running or not. The session itself, if it is still running, the first time you look at it: when that window is the one in front of you and Claude Code is sitting idle with nothing under the cursor, k0 types
/renamewith the new name into it and presses Enter — you will see the command go by. It never brings the window up to do that: the keyboard is yours, and a terminal jumping up while you type somewhere else would take your next words. And the list of sessions you can resume, when the session ends — while the process is alive the transcript already has an owner, and it would write the old name back over ours. On Linux and Windows the second of the three is missing, andk0-board doctorsays so: there the name catches up when the session ends. The same happens when a skill changes the title through the API.Start — opens a new terminal window, runs
claudein the right repository under the story's name, and puts the prompt in it. You press Enter.The session is born in plan mode, always. On the board the story turns Planning as soon as it gets to work, and amber Needs approval when the plan is ready. If you need something else, shift+tab as usual. Resume forces nothing: that session already had a mode, and it comes back as it was.
In exchange, once the plan is approved it asks for confirmations: starting inside a plan and never asking anything are two things Claude Code does not do together — the why is further down.
Every session, new or resumed, is also born with Claude Code's task list switched on. On a newer model Claude Code leaves it off unless it is told otherwise, and the commands that plan, work and check keep a task per step — so without it they would be asking for a tool that is not there.
The window is born centred on the screen you are using, at 90% of the free space, in every mode: the same margin on all four sides, never under a menu bar or a dock. Open more than one and they stack in the middle — double click brings the one underneath back.
If the screen changes — you plug a monitor in or out, or change resolution — the windows put themselves back: all of them centred on the main screen, at their usual size, without asking and without bringing the terminal to the front.
double click — brings that session's terminal back to the front, even if you had minimised it. It is what stops you losing track of which window is which.
Resume — appears once the terminal has been closed, by you or by k0 after a long silence: it reopens the same conversation exactly where it was. The story's prompt is not put back in — that conversation answered it hours ago, and typing it in again would be at best something stale in the way.
Done — closes the work and its terminal, with no questions: undo it with Reopen, and pick the conversation up again with Resume. Resume on a finished story — on its card, or on its row in ⌘K — reopens it too: a terminal at work on a story the board has put away is one nobody can see. If that story's terminal is somehow still open, it is brought up front rather than opened a second time. On a story that has never been started there is no terminal to close, and the button is there anyway as long as there is a backlog behind the board — a story planned here and then worked on in a terminal you opened yourself has to be closable, and
Doneis the only thing in k0 that closes one. With the backlog switched off it is not drawn on those stories at all.The session is stopped first and only then is the window closed. Closing a window with
claudestill inside it makes macOS put up the "terminate running processes" dialog, and the window does not close at all.Close — a link at the end of the row, quieter than the buttons because it is the one you reach for least: it closes the terminal and not the work. The session is stopped, its window goes, and the machine gets the memory back; the story stays exactly where it is, with the colour it had — the one asking you something stays red, the one holding a plan up stays amber, the one at your turn stays yellow — and Resume takes it from there. It is what a dozen windows open and a computer running out of air are answered with.
It is not there while the session is working: stopping one mid-thought is not memory saved, it is work lost. Wait for it to come back to you, and then close it.
The only thing that asks for confirmation is throwing a story away.
Stories reorder themselves inside a column: first the ones waiting for you, then the ones grinding away, backlog at the bottom, and among equals the most recent first.
Moving around
There are no scrollbars. With a dozen repositories open the board is wider than the screen, and to turn it you bring the pointer near an edge: from there it moves that way by itself — right, left, up, down, and diagonally in the corners — faster the closer you are, and it stops where the board ends. The thin shadow along one side says there is still something over there. Holding a mouse button keeps the board still, so a click near the edge lands.
Bottom right there is the zoom: + and − move it ten per cent at a time — 90%, 80%, 70% and so on, between 30% and 200% — and the percentage between them, clicked, goes back to 100%. The button next to it shrinks just enough to fit the whole board on the screen. On a trackpad, two fingers move the view and a pinch zooms to anything in between; the next click of + or − picks the nearest step from there. Where you were is still there after a reload.
The pills at the top are both legend and filter: click one and that status leaves the board. They stay as you left them.
The board keeps itself down to what you are working on. A repository you have not touched
since the day before your last piece of work folds away by itself: its column leaves the board
and its name appears in Old, over on the right. There is nothing to switch on and nothing to
tidy up — with a dozen repositories open, you arrive in the morning and the three or four you are
actually on are the ones standing there, side by side.
The day is counted back from your last piece of work, not from the clock, and that is what makes it survive a weekend: on Monday the freshest thing on the board is Friday evening, so what you find is Friday — not an empty board on the one morning you most need to see where you left off. The moment you start something on Monday the line moves with you.
Two things never fold. A column with something going on in it — working, planning, asking you something, holding a plan up for approval — stays where it is however old it is: hiding the one that is waiting for you is the opposite of what the board is for. A terminal simply left open at Your turn is not one of those: it is the resting state of every window you have not closed, and a session you finished with three weeks ago would otherwise hold its column at full width for ever. It folds like anything else — and folding closes nothing, so the terminal is still open and the story is still exactly where you left it. And nothing folds while you are looking at it: within one visit the set of columns can only grow, and the board tidies itself on the next reload, so a column never disappears out from under your hands.
The last two columns on the right are Old and Others, and they are the same list twice
over: a +, a name and the git mark, in alphabetical order. Old is the repositories that have
work on the board, just not lately; Others is the ones that have no column because they have no
stories at all. Click a row in Old and the column comes back at full width for the rest of the
visit — with everything that was in it, which is why the row itself says nothing about how much
that is or how long it has been there. Both columns are also there for the same two things:
getting into the files of a directory you are not working on, and giving birth to the first story
there with the +.
Next to a column's + there is one more button, which puts that column away now instead of
waiting for it to go quiet on its own — for when you are finished with a repository for the day
and would rather not look at it. On a column with something going on in it the button goes faint
and refuses, and says why if you hover it — it does not disappear, because a column runs and goes
back to your turn every few seconds and it would spend the session blinking.
Unlike the automatic fold, this one is remembered across reloads, until you fetch the column back
or something in it wakes up. It closes nothing: no session is stopped and no terminal is
shut. It is the board that gets smaller, not the work — what closes a session is Close or Done
on a story.
Finding a story: ⌘K
⌘K (Ctrl+K on Windows and Linux) opens a box over the board, wherever you are on it. Type a
story's number — 42 or K42, with or without the K — or a word of its title or of its notes,
and the stories that match come up underneath, best first. Half a word is enough, and so are
scattered letters: expo finds Export, qfind finds Quick find. Several words narrow it
down, because every one of them has to be there.
Every row has two buttons. Terminal takes you into the work, exactly as a double click on the note does: its terminal up front if one is running, the conversation it left behind if it was closed, a new session if there was never one. Open opens the story to edit it. Enter — or a double click on the row — is Terminal, ⌘Enter is Open, the arrows move, Esc shuts it.
Finished stories are in the list too, after everything still open and in grey. Enter and the double click open them, since a finished story is rarely where you meant to go; their button says Resume instead of Terminal, and pressing it reopens the story and puts it back on the board with its terminal — Start for one that never had a session. With the backlog on, repositories come up as well: choosing one filters the board on it, the same as the repository menu on the bar. With nothing typed the box lists the open stories you touched last, so ⌘K and Enter is the way back to whatever you were just on.
It searches what the board already has in front of it, so typing asks the server nothing — and a story in a column that has folded away, or behind a filter, is found all the same.
The git mark
On every story, next to the repository name, and next to every column name, one symbol says whether the work is safe: a dot with how many files, if there is work that is nowhere yet; an up arrow with how many commits, if it is committed but not pushed; a faded tick, if everything is saved. Hover to read it in full — branch, files, commits, and how many of those commits belong to that session. Click it and the files open.
A story running in an isolated worktree has a working tree of its own, so the mark is really
its own. A story working in the base repository shares the working tree with everybody — there the
dot belongs to the repository, and the only thing that belongs to the session is the commits made
since it started, which k0 counts by remembering where HEAD was at that moment.
k0 never runs git fetch. It only looks at what your git already knows about the remotes. For
"did I push this?" that is exact and instant, because pushing updates the remote reference by
itself; a push made by somebody else does not show until you fetch. On a repository with no
remote, pushing is not mentioned at all.
The globe: is the site up
Last on a column's heading, after the git mark, a small globe says whether that repository's dev server is running. Grey is off, green is up, and it breathes while it is coming up. Red means it was started and did not come up — hover it for the reason and the log.
One click switches it on or off. Two restart it. And when it is green the repository's name is underlined with a green dashed line and becomes a link: click it and the site opens in another tab, on the port it is really listening on. The line is the same green as the globe and stays for as long as the server does, so a repository that is up is one you can tell apart at a glance, from across the board, without going near it. Hover the globe to read the rest — the port, the command it was started with, and where its log is.
A repository gets a globe when its package.json has a dev script, or failing that a
serve one. Nothing to configure and nothing to fill in. start is deliberately not on that
list: by convention it runs what has been built, which is not what this is for.
Three things are worth knowing, because they are the point.
The server outlives the session. k0 starts it detached and owned by nobody. Close the session that asked for it, close every session, restart k0 itself — the server stays up and the globe stays green. This is the whole reason it exists: a dev server started inside a session belongs to that session, and dies with it.
k0 never asks the server whether it is up. Nothing here opens a socket to it — k0 talks to its own cloud and to npm, and to nothing it finds running on your machine. "Up" means the process is alive and the operating system says it is holding a TCP port open. That is stronger evidence than a reply would be, and it is where the port in the tooltip comes from — k0 never guesses a port, it reads the one your server actually chose.
A server you started yourself is recognised. Start one by hand in a terminal and the globe goes green on its own within a few seconds, with the right port, and switches it off if you ask it to. A globe that only knew about its own servers would sit grey next to a site that is plainly running, which is worse than no globe at all. On Windows this one part is missing — nothing there can read another process's working directory — and k0 says so rather than showing those servers as off.
The backlog
A post-it used to be a name and a prompt. That is enough to start a session and nothing like
enough to remember why you started it: three weeks later the title says Fix-Invoicing, and the
half hour that decided what fixed meant has scrolled off the top of a terminal you have since
closed.
The backlog is the rest of it. Same board, same notes, same gestures — what is added is what the work is about: what it belongs to, what was settled while you were talking about it, what has to be true before it can be called finished, and a check that holds the finished thing up against all of that before you are allowed to tick it off.
The board is the menu; the commands are the engine. Every story says what the one next thing to do with it is — Discuss, Plan, Work — and pressing that opens a terminal with the command already in it. The work happens there, in Claude Code, and you do not come back to the board until it is finished. Almost nothing here is typed into a form.
If you want the argument rather than the manual — why a decision has to be an object, what a round of questions is for, what the counter-check is really checking — it is in docs/method.md, and it is a shorter read than this section.
Before anything else: the commands have to be on your machine
Everything below runs on ten commands you type at Claude Code, and Claude Code looks for a
command in exactly two places: the repository you have open, and your own
~/.claude/skills/. Neither of those is where npm puts k0. So a command that was not copied out
is a command that does not exist, however carefully it was written — and every button on the board
that offers to run one leads nowhere.
Copying them out is one question, asked by the installer, right after it starts the service:
/k0-epic — an epic, discussed in rounds, then a tree of stories
/k0-story — one story, straight onto the board
…
Install 11 commands and the mod for Claude Code? (Y/n)Say yes and they are there in every repository you ever open. k0-board skills asks the same
question by itself, without touching the service: it is how the commands are brought up to date
after an upgrade, and how one written this morning reaches a k0 that runs from its own source. It is worth saying plainly what
happens if you do not, because it is what happened to this feature the first time round: the
commands were written and they worked — inside a clone of k0, and nowhere else on the machine.
From any other repository the board offered Discuss, the terminal opened, and Claude Code had
never heard of /k0-discuss. The whole backlog was invisible for want of one copy step.
If you are not sure you said yes, run npx k0-board@latest again. It asks only about the ones
that are missing, so somebody who already has them is not asked at all, and somebody who said no
in a hurry gets the question back. ls ~/.claude/skills answers it too.
If you cloned this repository rather than installing the package, they are already in its
.claude/skills/ and there is nothing to do — but only while you are working in this clone.
Copy them out anyway if you use them anywhere else.
A day with it
You open the board. Every story that has something to do carries one button, first in the row, saying what that is: Discuss, Plan, Work — in that order, because that is the order the work goes in — or Resume, when a terminal was opened on it and then closed. Hover it and it says why this and not something else: It has been discussed and has no plan yet. There is one button and never a menu, and there are three words on the list and no more.
There is also a story that carries no button, and that is an answer too. A session that is running needs nothing suggested about it — the terminal is where the work is, and a double click on the note goes there. A story waiting for you to look it over is waiting for a person. A story that is finished is finished. Filling any of those in with a command would be k0 inventing work.
k0 works that out and the page never does. It is the same reasoning /k0-next does, in the same
place, so the button on the note and the answer the command gives can never drift apart.
You press it. A terminal opens in that repository and /k0-plan K42 — the line you would have
typed yourself — goes in with it, already sent: k0 wrote that line out of a button you pressed, so
there is nothing on it for you to read over first, and a prompt left sitting unsent under the
cursor is a window that did nothing.
Or you take the short way in. Quick Start is the other road out of a story and it is not the same road: it opens a terminal on that repository with nothing in it and leaves the typing to you. That is the whole of it — no discussion, no plan, no command. It sits at the end of the row as a quiet link on a story that has a suggestion, and it is the plain button on one that has not.
Only /k0-work counts as the work having begun. Press Discuss or Plan and the story stays
where it was until the discussion or the plan moves it itself — otherwise walking away from a
discussion half way through would leave a story sitting in Working with nothing worked on.
You work in the terminal, and only in the terminal. The discussion asks its rounds and writes
each one down as it is answered; the plan comes back for your approval with the standing decisions
written into it as constraints, and its last question is whether to carry it out straight away — say
yes and the same session stores the plan and goes on into the work, with nothing planned twice;
/k0-work opens a worktree, does the work, keeps the log, and
merges it back; /k0-verify walks the result past every decision one at a time. None of that
needs the board. You can leave the tab open and watch the rounds land — it follows a live
discussion once a second — but nothing asks you to.
You come back, and the button has moved on. A story you discussed now says Plan. One you planned says Work. One whose terminal you closed says Resume, and picks the conversation up where it was rather than starting a second one beside it.
Double click the note to go where the work is. Its terminal if one is running; the conversation it left behind if the terminal was closed; a fresh session if there was never one. It is the same gesture on every note, which is what makes it worth having — and if the window has been closed by hand while the session is still thinking, k0 goes and looks for it by name before it tells you anything, and offers to open it again when there is really nothing left to find.
Done is yours and nothing else's. No command sets it and no gesture sets it: when the work is
really finished you press Done on the note, and it closes the terminal with it. A story that
came through its counter-check clean is offered no command at all — there is nothing left for one
to do, and the only thing in front of it is you pressing Done. /k0-verify and /k0-split are
still there and still do what they always did: they are commands you type, on the days you want
them, rather than advice the board pushes at you.
Things arrive during the day, and they do not interrupt this. Something you already know you
want is /k0-story in whatever terminal you have open — you say it, it lands on the board with a
key of its own, and adding and start it opens the session in the same breath. Something big
enough that you do not yet know what it is made of is /k0-epic: ten minutes of questions in
rounds, everything settled written down as it is settled, and only at the end a tree of stories
proposed for your approval — it creates none of them until you have said yes. Both are on the
board's + as well, which is a small menu now: Story opens the dialog you know, with one
field added for its epic; Epic asks which repository and then opens a terminal running
/k0-epic, because an epic is told, not typed.
The two views
The switch in the top bar, in among the filters, says Kanban or List. It changes the shape of what you are looking at and never what you are looking at: the state pills, the repository and the epic lane apply to both, so switching back and forth is free and nothing appears or vanishes under you.
Kanban is for working. It is the board you already know — one column per repository, notes that reorder themselves by who is waiting for you. With a backlog behind it a note grows four marks and no more: its key, on the top line; the epic it belongs to, as a small label in the epic's own colour, worked out from the key so there is nothing to choose and nothing to keep in step — it comes out with the rest of the detail when the note is opened; a flag in the bottom corner; and a warning when something it waits on is not finished.
The flag is put on and taken off from the note itself — it is the mark and the target both, and it mirrors the pencil at the other corner. It is invisible until the pointer is on the note, because an outline sitting on every note all the time is a mark that is everywhere and therefore marks nothing. Once it is on it stays on, and the note takes a border and its key and title take the flag's colour with it: the point of flagging something is finding it again from across the room, and a fifteen-pixel glyph cannot be seen from there.
Next to the flag sits a sun, on every note whether or not there is a backlog: always active, the one note k0 never closes for sitting idle — a session that never goes to rest, so the sun is lit, its disc filled, once it is on. It has its own paragraph where the closing is explained, under And the ones you forget, k0 closes for you.
And left of the sun, an arrow. Stories are joined to each other more often than a board of
separate notes admits — a handover that needs a fix in another repository, a release that waits on
three pieces of work — and the arrow is how you say so. Press it, drag onto another note and let
go: the arrow is drawn from the note that waits to the note it waits on, and it may cross from
one repository's column into another's. The board slides when the pointer nears an edge, so a note
three columns away is reached by dragging towards it; a note that is not on the board — filtered
out, or folded into Old — has to be brought back before anything can be joined to it.
- Let go over a repository instead of a note — the
+at the head of its column, or its name, or the same on its row inOldorOthers— and the story at the other end does not exist yet: the header lights up, and on release the usual new-story dialog opens on that repository, titled New story — K42 will wait on it. Write the title, press Quick Start or Discuss, and the arrow is already there. Close the dialog instead and nothing is left behind, neither story nor arrow. It is the quick way when finishing one story shows it waits on work in another repository that nobody has written down. - The board at rest shows no arrows. A note that has any keeps its arrow mark lit, with the count beside it. Put the pointer on such a note and the whole chain it belongs to is drawn — every arrow that can be reached from it, either way, with the notes outlined — and goes again when the pointer leaves. Click the mark and it stays until you click somewhere else.
- Click an arrow and two words appear on it: Flip, which turns it round, and Remove.
- An arrow means "waits on", so it is the same fact as the warning in the foot of the note:
while what a story waits on is not
Donethe note carries the chain mark, and starting it asks once. It is a note to yourself and not a lock. - An arrow that would close a ring is refused, with a sentence that names the stories — K12 already waits on K7 — because two stories waiting on each other wait for ever.
- A finished story keeps its arrows, faded. An arrow is drawn when both its notes are on the
board, so with
Donehidden the arrows into finished work are not there. A deleted story takes its arrows with it. - Close and Done ask, on the note the arrows leave. If the stories it waits on still have a
session open, Close offers to close them too; if they are not finished, Done offers to
mark them
Doneas well. Only this one is always the other answer. It follows the arrows the way they point and never back up them; a story that is working is left alone, and so is one the counter-check found broken, and the board says which.
The list draws no arrows: there the same fact is the line waits on … and is waited on by … in
the panel beside a row. In a terminal it is /k0-arrows.
Click an epic's label and the board becomes that epic. A strip appears under the top bar with
its key, its title, its repository, a progress bar and 4 of 11 done, and the way back out. Inside
the lane the label is not drawn on the notes — everything in here belongs to the same epic, and
saying so eleven times says nothing. The lane survives a reload: going into an epic is a decision
about where you are working, and a page that forgets it every time you press F5 is a page you stop
going into. The progress is counted over the epic's stories, not over the notes a filter left on
screen, and it is not weighted: eleven stories with one done is 1 of 11, however big the one was.
Anything else is an estimate, and an estimate here is a lie with a progress bar drawn round it.
List is for planning. The same stories as rows, three levels deep and every repository at once: a thin heading per repository, an epic that opens and closes with its progress bar — and, while a discussion is running on it, which round that is on — and under it its stories, with tasks indented beneath the story they were cut from. Stories belonging to no epic are grouped at the end. A row carries key, title, state, flag, how many decisions are still standing, how much of the checklist has passed, and the same next-step button. Which epics you left open is remembered.
Click a row and the story opens beside it, not underneath: the counter-check first, then why it exists, the rounds with their questions and answers, the decisions with the verdict each one got, the plan, the checklist and the log — with a line under the title saying both what it waits for and what is waiting for it, each key a way into that story. Beside rather than below, because the point of a list is to run down it, and a panel that pushes the rows off the bottom of the page loses the thing you were comparing against. Click an epic and the epic opens the same way — the rounds it was argued out in, and the decisions every story under it is held to. That is the only place that conversation can be watched, because it happens before a single story of it exists.
Two things in this view write rather than read, and they are the two you do while looking at a backlog rather than while working on one: the next step, started from the end of a row, and a checklist line you have just watched work with your own eyes — ticked in the panel, and recorded as yours rather than the model's, which is the difference the checklist exists to keep.
Dragging a row moves it. Up and down to change the order, onto another epic's heading to move
it there, onto No epic to take it out of one. That is the whole of it: dragging never changes
state. A state is a road the work walks, and walking it by dropping a piece of paper somewhere
was always the wrong gesture — states move from the terminal, and from the Done button.
The ten commands
Eleven you type, and the installer offers twelve — these eleven plus
/k0-import — and one more thing that is not a
command at all, the k0-links mod. /k0-whatsnew and
/k0-changelog are deliberately not on that list: k0 runs those two itself, out of its own
directory, and you never type them.
| | |
|---|---|
| /k0-story | one story, straight onto the board — the fast door |
| /k0-epic | the long way in: rounds, decisions, then a tree of stories you approve |
| /k0-discuss | the same rounds against a story that already exists |
| /k0-split | a story that will not close, cut into tasks that inherit its decisions |
| /k0-plan | plan mode, with the standing decisions written into the plan as constraints |
| /k0-work | the worktree, the work, the log as it goes, and the merge back |
| /k0-ultracode | a whole epic driven by a conductor, a window per story; one story with agents under it |
| /k0-verify | the counter-check |
| /k0-next | what to pick up now, and why |
| /k0-order | priority and dependencies, dictated: K51 to the top, K42 waits on K37, flag K19 |
| /k0-arrows | what a story is joined to, in this repository or any other — where each one stands and what its Log last said — and the arrows themselves: draw one, remove it, turn it round |
The first ten are also the only ten a button on the board may start; /k0-arrows is only ever
typed. They are written out by name in
the server and checked against that list before anything reaches a command line — and it is a list
and not a directory listing on purpose: a folder arriving in your skills directory, from a clone or
a package or an installer, must not thereby become something a web page can ask k0 to run.
/k0-next is worth one sentence of its own, because the answer is not the model's. k0 works out
what to pick up — a live session first, then something in Review and the one that has been
sitting there longest, then what is not waiting on unfinished work, then the flag, then how far
along it is, then the order you put the board in — and hands over the story with the sentence that
says why. Ask twice and you get the same answer, which is not true of anything a model reasons out
each time.
Dependencies are a note, not a lock. Nothing refuses to start a story that is waiting on
another one: the note is marked, the button that starts the work asks you once and then goes
ahead, and the story sinks down /k0-next. A backlog that will not let you work on what you want
is a backlog you stop using.
An epic, a story, a task
A story is one post-it, and it is the thing you work on. Everything the board already does it still does: a story opens a terminal, drives the session in it, and says what that session is doing.
An epic is a reason with several stories under it — an area, a feature, a rewrite. It lives in exactly one repository, because a piece of work that spans two of them is two pieces of work with a wish in the middle.
A task is a story that was cut out of another one. It is not a different kind of thing: same table, same rules, same key — a story that turned out too big to close gets split, not turned into another species. A task takes its parent's epic unless you give it one of its own, because a task planned outside the epic its parent sits in would be planned blind to every decision that shaped the whole thing.
The key, and where it sits
Every epic, story and task gets a key: K plus a number, K42. It is one number for your
whole account — every repository, every machine — shared between epics and stories, and it is
never reused and never reassigned: not when the story moves under another epic, not when you
delete it, not when the repository is renamed, and not when the story moves to another repository,
since there is no other K42 there for it to collide with. The number comes from k0 Cloud's
counter; a story made while the cloud cannot be reached gets a provisional key, K~3, until the
sync gives it its real one — see Offline, and keys with a ~. Without
an account the same single counter is kept on this machine.
Beside it there is a position: 1.12.1. The first epic, its twelfth story, that story's first
task. The position is worked out fresh every time it is shown and never stored, so it cannot
disagree with the tree it describes — move a story and its position moves with it.
The key is the name you say out loud; the position is where the thing is sitting today. When you
say K42 to a command it knows what you mean, whatever the board has been rearranged into since.
Why a story is not a session
This is the one change underneath everything else, and it is worth a paragraph.
A card used to be a session: one note, one conversation, and ticking the note off ended both. So a piece of work you came back to twice was two notes, and the first one was a note about a conversation nobody could remember.
Now a story keeps every session it has had, one at a time, over as long as it takes. And it carries two different clocks, which used to be one column fighting itself:
- the story's state —
Backlog·Discussed·Planned·Working·Review·Done— which is where the work is; - the session's status — working, planning, holding a plan up, asking you something, your turn — which is what a terminal is doing this second.
No transition is required. Any state may follow any other, and Backlog straight to Done is a
legal thing to do that nothing will warn you about — a backlog that argues with you about the road
is a backlog you route around. Working sets itself when a session goes live. Review is where
/k0-verify puts a story when it starts checking it. Done is only ever yours: nothing in k0
sets it, and the Done button on the note is still what confirms it.
The post-it itself still draws one word and one colour, exactly as before — the two clocks put back together. Nothing about the board you know got louder.
Rounds, and why they say how many are left
A round is one small group of questions — four at the most — with your answers written down before the next one is asked.
Each round opens by saying where it is: "Round 3 of about 8". The number comes from counting the things where a different answer would produce different work, and it is recalculated after every answer, because answers both close questions and open them. When it moves, it says so in the same breath — round 4 of about 6, two of the questions answered themselves — and never drifts in silence. A count that quietly becomes twelve after promising eight is a count you stop believing, and once you stop believing it you start answering to get it over with.
It stops when no remaining question would change the work, which is stricter than it sounds and is the only test being applied: a question worth asking is one whose two answers lead to two different builds. There is a hard ceiling of fifteen rounds. At fifteen it stops wherever it is, shows you the list of what it never got to in your own words, and says the story is recorded as it stands and can be picked up whenever you like. A discussion that reaches fifteen is telling you the story is really two, and it says that as well.
Every round is written to k0 before the next question is asked. Not at the end, not on a save. A terminal that dies at round three does not take the first three with it, and neither does a session that runs out of context in the middle — which is the one that actually happens, and the one nobody thinks about until the second time.
Decisions
What comes out of the rounds is not a summary. It is a row of decisions, one complete sentence
each, numbered — D1, D2 — and written in your language, about behaviour rather than about
implementation. A decision that names a function is one you cannot check without opening the code,
and six months from now you will not open the code.
A decision is never rewritten. When you change your mind, the new decision supersedes the old one and both stay, the old one crossed through and pointing at what replaced it. This is the whole reason they are objects and not paragraphs: the point is to hold the work up against what was actually said at the time, and prose you can edit afterwards proves nothing.
An epic's decisions belong to the epic, and every story under it inherits them rather than being
handed a copy. They are shown with the epic's key in front — K7·D3 — so it is obvious a rule came
down from above and applies to everything in the lane. Inheriting rather than copying is what makes
changing your mind work: supersede K7·D3 on the epic and it is superseded for all eleven stories
at once, where eleven copies would have forked the first time one of them was touched.
An epic is discussed and decided before a single story of it exists, which is why its decisions have to be able to live on the epic. That is not a detail: it is the main way anybody uses this.
And when something you say now contradicts something you settled earlier, the discussion stops there and asks — naming the decision it clashes with, saying which of the two it thinks should stand, and why. Writing both down and carrying on is how you end up with two rules that disagree and no way of knowing which one the work followed.
The counter-check
Here is what this is for.
You explain a piece of work to a model, properly, for half an hour. It asks good questions — some of the answers surprise you, because you did not know what you wanted until it asked. It says it has understood, and it has: the summary it gives back is better than the one you would have written. Then it builds something that quietly contradicts half of it. Not all of it, and not obviously. One thing you settled at minute twenty is simply not there, and something you ruled out is there instead. You notice three days later, and by then you cannot even prove you said it.
That half hour did not merely fail to help. It cost you the half hour and it bought a false confidence that the thing was understood, which is worse than knowing it was not, because you stopped watching.
/k0-verify is the thing that was missing. When the work is done it takes the decisions one at a
time — the story's own and the ones it inherited — and records a verdict for each: kept,
violated, or not applicable, with the evidence. A file and a line, or a sentence saying why
the decision does not apply here. Never a summary standing in for the row, because a summary is
where the one that was broken goes to hide.
Three rules make it worth something rather than a ceremony:
- A run is the whole set or it is not a run. One that answers nine decisions of ten is refused
and told which one it passed over.
nais a verdict; silence is not. A check that reports a clean sweep of whatever it happened to look at is worse than no check. - A run never overwrites the one before it. Runs are numbered and they all stay, so you can see that something was broken, then fixed, rather than only that it is fine now.
- A story cannot be marked
Donewhile a decision a run found broken has not been answered since. It is read decision by decision and not run by run: a later run that finds the same decision kept closes it, and a later run that says nothing about it, or says it does not apply, leaves it exactly where it was. This is the only refusal in the whole feature, and it applies to whatever is asking: the Done button on the note, the one at the end of a row in the list, a command. It comes back as a sentence saying which decision, from which run, and what to do about it — opening with the fact that it is the counter-check in the way and not an arrow. When a story it waits on has been finished since that run, the sentence names it and says to run the counter-check again: work handed elsewhere and since done is the usual reason a broken decision no longer is. It only says so; the refusal stands until a run finds the decision kept.
There are exactly two ways to answer it, and both are honest: put the work right and run the counter-check again, or supersede the decision if it turns out the decision was the thing that was wrong. What you cannot do is talk past it: a story with a broken decision is drawn on the board so that it cannot be scrolled past, and pressing Done on it comes back with the sentence rather than the story closed.
There is also a checklist on the story — what has to be true for it to be finished. /k0-verify
does itself everything a machine can do, runs the project's tests, drives the browser when the thing
is a web application, and leaves you only the lines that genuinely need a person.
/k0-work and the worktree
/k0-work gives the session a working copy of its own: a git worktree under
<repo>/.claude/worktrees/, on a branch named after the story, opened from the branch you are
standing on — not from main, not from origin. You keep working in the repository, the session
works next door, and at the end its branch comes back in as one merge commit and the copy is
destroyed. The folder is kept out of git's way through .git/info/exclude, never by writing in
your .gitignore.
Everything the board starts opens in the story's own repository, never in a worktree. /k0-work
makes one when it needs one, and it is the only command here that does: the others talk about the
story rather than change it, and a discussion held inside somebody else's working copy is a
discussion about a copy.
Uncommitted work in the repository does not stop it. Other sessions are usually busy in the same
checkout, and in a repository that commits .k0/ the board has just rewritten a story's file there
— so the worktree opens anyway, from the last commit, and names the files it will not see. k0's own
.k0/ files are never counted. The merge at the end goes through over pending work too, and stops
only when the story changed one of those same files: then it names them, merges nothing and leaves
the worktree standing. When a worktree cannot be opened at all, the session says why and stops; it
never falls back to working in your repository
