k0-links

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-board

That 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 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 start

That 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 xdotool for window placement, and python3 with 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 two places. 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. 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:

1. copies the whole database to ~/.k0/backups/k0-before-cloud-<time>.db, in one consistent file;
2. renumbers every story and epic once, in the order they were made, starting from the cloud's next number;
3. 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 K12 ever meant anything;
4. renames the files in .k0/;
5. writes ~/.k0/backups/k0-before-cloud-<time>.keys.json, every old key beside its new one;
6. 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

• + — 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 api becomes Fix-Api, while Fix API stays Fix-API. What you see in the field is exactly the name the session will have.

• 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 — renames the session 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 /rename with 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, and k0-board doctor says 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 claude in 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. 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 Done is 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 claude still 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.

Botto