kb

A fast, local-first kanban board for your terminal.
Use the same tasks from the TUI, CLI, scripts, and AI agents.

kb is one executable with no hosted account, remote mode, or build step. Your board lives in local SQLite—no signup and no service to keep running. Open it full-screen, automate it from the command line, connect a local MCP client over stdio, or view it in a browser. Only kb web opens a TCP listener; it binds to 127.0.0.1 by default, and no other command listens on a port.

Why kb

• Terminal-native: keyboard and mouse controls, responsive columns, forms, filters, Markdown, comments, checklists, and blocker links.
• Local-only: TUI, CLI, MCP, and the web UI all use the same SQLite database.
• Scriptable: stable task numbers, JSON output on supported commands, and a focused task CLI.
• Agent-ready: 12 MCP tools plus optional AI-assisted drafting and imports.
• Safe task flow: completion guards catch open checklist items and blockers; cancellation stays reversible until you explicitly delete a task.

Get started

Install with Go

Go 1.26.5 or newer is required. Use the local toolchain so Go does not download another version during installation:

GOTOOLCHAIN=local go install github.com/RandomCodeSpace/kb@latest
kb version

Install a release binary

CGO-free binaries for Linux amd64/arm64, macOS amd64/arm64, and Windows amd64 are attached to the latest release. Download the matching binary and SHA256SUMS, then verify it before installing:

grep ' kb-linux-amd64$' SHA256SUMS | sha256sum -c -

On macOS, use shasum -a 256 -c -. On Windows, compare Get-FileHash -Algorithm SHA256 with the matching manifest entry.

Linux example after verification:

mkdir -p "$HOME/.local/bin"
install -m 0755 kb-linux-amd64 "$HOME/.local/bin/kb"

Make sure $HOME/.local/bin is on your PATH.

Create your first board

kb project use personal
kb add "Write launch notes" --prio high --tag docs
kb list
kb

That is the whole setup. A fresh task needs a project, so the first command saves personal as your default. A bare kb opens the TUI when run in an interactive terminal.

Data is stored in $KB_DATA or ~/.local/share/kb. To use another location:

kb tui --data /path/to/kb-data

Use the board

The footer always shows actions available in the current view. These are the keys worth learning first:

Editors use Tab and Shift+Tab between fields and Ctrl+S or Ctrl+Enter to save. The TUI asks before discarding changed forms. Local CLI changes appear without restarting the board.

Use the CLI

A normal task lifecycle stays pleasantly boring:

kb add "Ship the docs" -p web --prio high --tag release
kb list --tag project::web
# kb add prints the new task number; #12 is an example
kb view 12
kb move 12 doing
kb comment add 12 "Ready for review"
kb done 12

Tasks receive stable per-board numbers such as #12. Use bare 12, quoted '#12', a full UUID, or a unique UUID prefix anywhere a task reference is expected.

Useful commands:

add  list  view  update  move  done  cancel  restore  rm
project  users  comment  link  unlink

Run kb help for task-command syntax and flags. Moving to Done is refused while a task is blocked, has an incomplete checklist, or has an open linked blocker. Use --force only when you mean to bypass that guard. cancel is reversible; rm ID --yes is permanent.

Work with projects

Projects are simple views inside one board:

kb project use web          # save the default project
kb project current
kb project list
kb add "Ship the docs"      # goes to web
kb add "Fix auth" -p api    # one-command override
kb update 12 -p api         # move task #12 to api

Resolution order is -p/--project, KB_PROJECT, then the saved default. Tasks from older kb versions without a project are placed in inbox when a local mode opens the store.

Use the web UI

The web UI is an optional browser view of the same board. It starts only when you ask for it:

kb web                                  # pick a free loopback port, open the browser
kb web --no-open --addr 127.0.0.1:8321  # fixed port, print the URL only

The web UI has no authentication. A non-loopback --addr is refused unless --unsafe-listen is also given, and with it anyone who can reach the address can read and change your board. Keep the default loopback bind unless you have a firewall or tunnel in front of it.

TUI, CLI, MCP, and the web UI share one SQLite database; changes made in any of them appear in the others without a restart.

Use AI and agents

AI is optional. Press s in the TUI to configure an OpenAI-compatible Chat Completions endpoint, model, and API key. The endpoint must support tool calls. Drafting, ADR splitting, and forge import show proposals for review before creating tasks.

Built-in skills:

• story-draft turns rough notes into one card;
• adr-split turns an ADR into reviewable cards;
• import-transform turns GitHub or GitLab issues into reviewable cards.

Add or replace skills with direct-child Markdown files in <data>/skills. Provider and forge credentials are encrypted in the local SQLite database.

Connect an MCP client

kb mcp exposes the local board over stdio. It opens no network listener.

[mcp_servers.kb]
command = "kb"
args = ["mcp"]

The MCP process exposes task listing, creation, updates, moves, reversible cancellation, explicit permanent deletion, similarity and duplicate checks, task details, comments, and blocker links. It registers 12 tools and no MCP resources.

list_tasks        add_task          update_task       move_task
delete_task       search_similar    duplicate_check   get_task
add_comment       list_comments     link_tasks        unlink_tasks

Keep your data safe

Important files in the data directory:

Back up

1. Quit the TUI and stop any CLI scripts or MCP clients that may be writing.
2. Copy the entire data directory as one unit—not just kb.db. This keeps the database, any SQLite sidecars, the generated secret, preferences, and custom skills together. Copy to a fresh destination, not over an existing one.
3. If you set KB_SECRET outside the data directory, preserve that exact value with the backup. It is part of the backup even though it is stored elsewhere.

Restore

1. Stop every kb process that uses the destination data directory.
2. Restore the complete directory to an empty directory. Use the original generated secret file or the exact external KB_SECRET value.
3. Open the restored directory first with the same kb version or a newer one.
4. Start kb normally. It validates the database schema before migration and refuses an existing database when its generated secret is missing, instead of silently creating a key that cannot decrypt the stored credentials.

Losing the generated or external key makes stored credentials unreadable. Task content remains in SQLite, but the complete directory plus the matching secret is the supported recovery unit.

Unsupported

Do not:

• Back up live copies of the directory while kb is running anywhere.
• Copy only kb.db without the rest of the directory.
• Overlay a restored backup onto an existing directory.
• Store the data directory on network filesystems or synced folders (Dropbox, iCloud, OneDrive, and similar).
• Use the same data directory from multiple hosts.
• Downgrade to an older kb version with an existing database.

Legacy <user>.md boards in the data directory are considered for one-time import when that owner has no tasks. Use default.md for the board visible to local modes. Source Markdown files are not deleted.

Build and contribute

Build the local binary:

CGO_ENABLED=0 go build -o kb .

Run the test for the package or contract you changed. After committing, the repository-owned impact calculator shows the same scope GitHub Quality will use:

base=$(git merge-base origin/main HEAD)
sh scripts/ci/impact.sh --base "$base" --head HEAD

Every pull request still reports the same nine Quality jobs. Unaffected jobs say not affected; affected jobs run only the owning packages and mapped contracts. Changes to shared migrations, terminal performance, CI, docs, or release behavior select their focused gate automatically. Node is used only by the repository's CI monitor and is not an application build or runtime dependency.

When Go, release, or CI behavior changes, a native smoke matrix builds and exercises the local task flow on Linux, macOS, and Windows.

Use conventional commit subjects and target pull requests at main.

Current release notes are in docs/releases/v1.7.2.md.

License

kb is available under the MIT License.