convez.ai
MCP ServerProdutividadeIntermediário
up2jj

kbrd – Kanban em Terminal

up2jj/kbrd

Kanban keyboard-driven 100% em arquivos para terminal e agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Um servidor MCP que expõe um Kanban board baseado em arquivos, operável via teclado direto do terminal. Armazena tudo como plain text (diretórios são colunas, Markdown são cards), permitindo versionamento com git, edição em qualquer editor e automação via Lua ou shell commands. Ideal para quem quer gerenciar projetos sem deixar o CLI.

Instalação

$npx convez-ai up2jj/kbrd

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
v0.24.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Gerenciamento de tarefas e projetos via CLI sem banco de dados
  • Integração com agentes IA para automação de fluxos de trabalho
  • Versionamento de boards com git e sincronização cross-device
  • Extensão com scripts Lua e custom shell commands

Veredito

kbrd é um MCP server robusto para Kanban minimalista, ideal para desenvolvedores e agents que precisam de gerenciamento de tarefas agnóstico e versionável. A abordagem 100% baseada em arquivos elimina lock-in e oferece flexibilidade rara nesta categoria.

README

A tradução para o português deste README ainda está na fila.

kbrd

A terminal-based, keyboard-driven Kanban board for the command line

Go Bubble Tea Lua MCP Version

Your board is just a folder. Columns are directories. Cards are Markdown files.


kbrd stores everything as plain files on disk — there is no database and no lock-in. A board is a directory, each column is a sub-directory, and each card is a Markdown (.md) file. Because the board is the filesystem, you can edit it with any editor, version it with git, sync it with your usual tools, and let kbrd render it as a live, navigable board.

Built with Bubble Tea and friends, kbrd adds git integration, fuzzy board switching, cross-board search, an embedded Lua scripting engine, custom shell commands, and a built-in MCP server for LLM/agent tooling.


Table of contents


Features

A quick, scannable rundown of everything kbrd does:

  • Plain-files storage — directories are columns, .md files are cards, zero database.
  • Live reload — the board updates instantly when files change on disk (fsnotify).
  • Fully keyboard-driven — every action has a binding; mouse optional.
  • Create cards — in the current column (n) or the first column (N).
  • Card templates — create pre-structured cards from per-column or board-wide templates with a multi-step form (t); see TEMPLATES.md.
  • Card frontmatter — YAML metadata on a card sets its accent color, icon, meta line, and filterable #tags; custom keys flow into Lua commands as ctx.data.
  • Peek — rendered Markdown preview in a scrollable viewport (space).
  • Edit inline — with undo/redo and an expand toggle, or open in $EDITOR (o).
  • Append / prepend — add content to existing cards (a / p).
  • Journal entries — append timestamped notes to a card (J).
  • Copy / paste — move text between cards, persists across sessions (c / v).
  • Pin cards — float important cards to the top of a column (!).
  • Move cards — to the next column (m) or back to the first (M).
  • Rename & delete — cards (r / d) and columns (R), with confirmation on delete.
  • Global search — fuzzy full-text search across all recent boards via ripgrep (f).
  • Board switcher — fuzzy switch, pin favorites, and remove boards (Ctrl+P).
  • Git panel — diff, commit, log, sync (pull+push), and add remotes in-app (g).
  • Auto-sync — reconciles with the remote when the board opens (and optionally on an interval), with automatic upstream setup; it resolves divergence on its own, setting aside a conflict copy only when two machines edit the same lines (never blocking the sync). A header cell shows the sync state.
  • README generation — optionally regenerate README.md from the board before commits.
  • Themes — toggle light / dark palettes on the fly (quick command . → t).
  • Help overlay — discover every shortcut without leaving the app (?).
  • In-app config menu — open or scaffold config & command files (,).
  • Custom shell commands — run templated shell commands against any card (x).
  • Zellij integration — inside a zellij session, open a card in a floating or tiled editor pane, or a shell scoped to the board (z); the tab is named after the board.
  • Lua scripting — extend kbrd with commands, event hooks, timers, and async tasks.
  • Virtual columns — Lua-driven columns showing a computed view (e.g. open tasks across boards); tab switches into them, with script-declared item actions (example).
  • Built-in MCP server — let external tools and LLM agents operate on your boards.

Screenshots


Installation

Homebrew (macOS)

brew install up2jj/tap/kbrd

This installs a prebuilt binary onto your PATH. Upgrade later with brew upgrade kbrd.

From source

Requires Go 1.26+:

git clone https://github.com/up2jj/kbrd.git
cd kbrd
go build -o kbrd ./

Move the resulting kbrd binary somewhere on your PATH. See Development for the test/build workflow.

Runtime dependencies

  • git — for the git panel and sync features.
  • Optional: ripgrep (rg) — required for global search.
  • Optional: difft or diff-so-fancy — nicer diffs (falls back to git).
  • Optional: zellij — enables the z actions menu (editor/shell panes) when kbrd runs inside a zellij session.

Getting started

Run kbrd from any directory you want to use as a board:

./kbrd

On first run kbrd sets up default columns. Press ? at any time for the full shortcut overlay. To scaffold configuration files:

./kbrd init            # write a kbrd.toml template into the current directory
./kbrd init --global   # write the global config template to ~/.config/kbrd/

Commands

CommandDescription
kbrdOpen the current directory as a board (default).
kbrd init [--global]Write a config template — local kbrd.toml by default, or the global template under ~/.config/kbrd/ with --global.
kbrd clone <repo-url> [dir]Clone a board repository and open it. dir defaults to the repo name; pass --no-open to clone without launching the TUI.
kbrd serve eject [--dir]Write the default web templates and static assets into .kbrd_web_templates/ for customizing (see Web server).

Flags

FlagDescription
--mcpStart the built-in MCP server for this run (off by default).
--mcp-addr <addr>Override the MCP listen address (default 127.0.0.1:7777).
--safeDisable all board-supplied code — Lua scripting, event hooks, and template {{shell}} exec — overriding config. Use when opening a board you don't fully trust.

Keyboard shortcuts

All bindings below are the defaults from the in-app help (?).

Board view

Navigation

KeysAction
→ / tab / ]Next column
← / shift+tab / [Previous column
j / kMove within a column
H / LPan columns left / right
/Filter cards in the current column

Item

KeysAction
spacePeek (rendered Markdown)
eEdit
a / pAppend / prepend content
JJournal entry
c / vCopy / paste
oOpen in $EDITOR
!Pin / unpin
m / MMove to next column / first column
rRename item
dDelete
xCustom commands menu

Create & command

KeysAction
nNew item in current column
NNew item in first column
tNew item from template
.Quick command

Column

KeysAction
RRename column

Global

KeysAction
F5Refresh
Ctrl+PSwitch board
fSearch across boards
gGit panel
zZellij actions menu (only inside a zellij session)
,Config menu
?Toggle help
Ctrl+CQuit

Inline editor

KeysAction
ctrl+s / enterSave / confirm
ctrl+z / ctrl+yUndo / redo
ctrl+eToggle expanded view
escCancel

Peek

KeysAction
j / k (↓ / ↑)Scroll down / up
enter / space / pgdnPage down
g / home, G / endTop / bottom
q / escClose

Template form (t)

KeysAction
↑ / ↓, enterPick a template
tab / enterNext field / step
shift+tabPrevious field / step
esc escCancel (first esc arms, second confirms)

Board switcher (Ctrl+P)

KeysAction
↑ / ↓Previous / next board
enterSwitch
tabPin / unpin
esc / ctrl+pCancel

Global search (f)

KeysAction
↑ / ↓Previous / next result
enterOpen result
escCancel

Git panel (g)

KeysAction
dDiff selected file
cCommit
sSync (pull + push)
SCommit + sync
lView log
aAdd remote
tabToggle pane focus
q / escClose

Config menu (,)

KeysAction
cOpen or create local kbrd.toml
COpen or create global ~/.config/kbrd/config.toml
xOpen or create local .kbrd_commands.yml
mCreate local .mcp.json
aCreate local AGENTS.md

Zellij actions (z)

Only available inside a zellij session.

KeysAction
fOpen the card in a floating editor pane
eOpen the card in a new tiled pane
sOpen a shell in the board directory
q / escClose

Configuration

kbrd reads two TOML files, with the folder-local one overriding the global one:

  • Global: ~/.config/kbrd/config.toml
  • Folder-local: <board>/kbrd.toml

Generate templates with kbrd init / kbrd init --global, or from the config menu (,).

[display]
column_width  = 32          # width of each column
preview_lines = 3           # lines shown in a card preview
title_from_heading = false  # use the first "# " heading as the card title
theme         = "dark"      # "light" | "dark"

[notify]
backend = "auto"            # auto | osascript | osc9 | osc777 | none

[board]
name = ""                   # optional label shown in the board switcher

[git]
diff_tool          = "auto"     # auto | difft | diff-so-fancy | git
auto_sync_interval = ""         # empty / "0" disables; e.g. "30s", "5m", "1h"
generate_readme    = false      # regenerate README.md from the board before each commit
manual_sync_mode   = "attended" # attended (ff-only, fail loud) | auto (merge + conflict copy)
sync_on_startup    = true       # reconcile with the remote when the board opens (no-op without a remote)
auto_commit        = false      # TUI: commit pending edits before each auto-sync (self-sync while editing)

[scripting]
enabled            = true     # master switch for the Lua VM
command_timeout_ms = 2000     # timeout for command callbacks
hook_timeout_ms    = 500      # timeout for event hooks and timers
instruction_limit  = 10000000 # CPU backstop per script run
error_threshold    = 3        # auto-disable a failing hook/timer after N errors (0 = never)

[mcp]
enabled = false             # built-in MCP server; off by default (start with --mcp or enabled = true)
addr    = "127.0.0.1:7777"  # Streamable HTTP listen address

Zellij integration

When kbrd detects it is running inside a zellij session (via the ZELLIJ environment variable), it names the current tab after the board on startup and adds a z actions menu so you can jump into a card without leaving the board:

KeyAction
fOpen the card in a floating editor pane
eOpen the card in a new tiled pane
sOpen a shell in the board directory

Editor panes use $VISUAL → $EDITOR → vi. Reopening a card you already have open focuses the existing pane instead of spawning a duplicate. The z binding and its help entry appear only inside zellij; everywhere else it does nothing. Outside zellij, use o to open a card in your $EDITOR as usual.

Extending zellij usage with custom commands

The built-in menu covers the common cases; for anything else, kbrd's custom shell commands already give you the whole zellij CLI. Because commands run inside the session with the board template variables, you can script any pane / tab / layout behavior and run it from the x menu — no kbrd config required:

commands:
  - name: Edit in big floating pane
    id: zellij-edit-big
    command: zellij edit -f --width 80% --height 80% --cwd "{{.boardPath}}" "{{.filePath}}"

  - name: Lazygit in the card's column
    id: zellij-lazygit
    command: zellij run --cwd "{{.columnPath}}" -- lazygit

  - name: Tail the card's log
    id: zellij-tail-log
    command: zellij run --name logs -- tail -f "{{.fileDir}}/run.log"

Card templates

Press t in a column to create a card from a template instead of starting blank. A template is a Markdown file whose YAML frontmatter declares a multi-step form (text inputs, selects, multi-selects, confirms — rendered with huh); the body is a Go text/template that receives your answers plus the standard board variables.

---
name: Task
filename: "{{slug .title}}"
steps:
  - title: Task
    fields:
      - {key: title, type: input, title: Title, required: true}
      - {key: priority, type: select, title: Priority, options: [low, normal, high], default: normal}
---
# {{.title}}

- Priority: {{.priority}}

Templates live in <board>/.kbrd_templates/ (every column) and <board>/<column>/.kbrd_templates/ (column-only; shadows board templates with the same name). Created cards fire the normal item_created event, so hooks apply.

See TEMPLATES.md for the full format reference and examples/templates/ for worked examples.


Card frontmatter

A card may open with a YAML frontmatter block; kbrd parses it for display metadata and keeps it out of the card preview:

---
accent: "#e06c75"       # color for the card title
icon: "🔥"              # glyph shown before the title
meta: due tomorrow      # replaces the modified/size/git meta line
tags: [urgent, backend] # rendered as #tag chips; matched by the column filter
assignee: kuba          # custom keys are allowed
---
# Card title
Body text…

All keys are optional and parsing is always on. tags accepts a list or a single string, and tag names participate in the column filter (/). The full frontmatter map — including custom keys like assignee — is exposed to Lua custom commands as ctx.data, so scripts can act on it. Malformed YAML never breaks a card: it loads without metadata and shows a ⚠ yaml badge on its meta line so the mistake is visible.


Extensibility

kbrd is extensible at three levels: simple shell commands, full Lua scripting, and an MCP server for external tools.

⚠️ Security: A board is just a folder, and opening one runs any folder-local .kbrd.lua and .kbrd_commands.yml it contains — automatically, with no prompt. Cloning or syncing a board authored by someone else executes their code with your privileges. Only open boards you trust, or disable scripting for untrusted ones. See SECURITY.md for the trust model and mitigations.

Custom shell commands

Define shell commands that run against the selected card, column, or board. Press x on a card to open the menu and fuzzy-search by name (example).

  • Global: ~/.config/kbrd/commands.yml
  • Folder-local: <board>/.kbrd_commands.yml (overrides global commands with the same id)
commands:
  - name: Edit in vim
    id: edit-vim
    description: Open file in vim
    command: vim "{{.filePath}}"

  - name: Reveal in Finder
    id: reveal-finder
    description: Open the column folder in Finder
    command: open "{{.columnPath}}"

Template variables

VariableMeaning
{{.filePath}}Absolute path to the selected file
{{.fileName}}Base name without .md
{{.fileDir}}Directory containing the file
{{.boardPath}}Board root path
{{.boardName}}Board name from config
{{.columnPath}}Column folder path
{{.columnName}}Column folder name
{{env "VAR"}}Value of environment variable VAR (empty string if unset)

Quote variables to handle paths with spaces. Reload by re-opening the board.

The rendered command also runs in a shell, so plain $VAR works too — use {{env "VAR"}} only when you need kbrd to substitute the value before the shell sees it (e.g. to build the command itself rather than have the shell expand it).

Lua scripting

kbrd embeds a Lua 5.1 VM (gopher-lua). Scripts are loaded at startup from:

  • Global: ~/.config/kbrd/init.lua
  • Folder-local: <board>/.kbrd.lua

The API surface includes:

  • kbrd.command(...) — register a custom command (appears in the x menu; shadows a shell command with the same id).
  • kbrd.on(event, fn) — hook lifecycle events (board_load, board_refresh, item_select, column_change, item_open, item_saved, item_changed, item_created, item_renamed, item_deleted, item_moved, git_sync_done), plus the column_items transform hook to sort/filter/group a column's cards (e.g. by a priority frontmatter key), and the serve-only http_request/http_response middleware hooks to gate, redirect, or rewrite web requests.
  • kbrd.board.move / create / rename / delete / refresh / createColumn — board operations.
  • kbrd.board.templates / createFromTemplate — list card templates and create cards from them (TEMPLATES.md).
  • kbrd.ui.pick / prompt / confirm — interactive dialogs (commands only, not hooks/timers).
  • kbrd.fs.read / write / exists / mkdir / glob — filesystem helpers (paths resolve against the board root).
  • kbrd.async.run / cancel — run shell commands on a worker goroutine.
  • kbrd.timer.every / after / cancel — schedule recurring or one-shot callbacks.
  • kbrd.notify(msg, level) / kbrd.status(...) — toasts and status line.

Scripting can be disabled and tuned via the [scripting] config section. See SCRIPTING.md for the full API reference, examples, and safety model.

MCP server

kbrd can run a built-in Model Context Protocol server over Streamable HTTP, letting external tools and LLM agents operate on your boards headlessly. It is off by default — start it with --mcp for a single run, or set enabled = true in the [mcp] config section to opt a board in permanently. It listens on 127.0.0.1:7777 (override with --mcp-addr or [mcp].addr). The header strip shows its state: ◆ mcp (green) when running, ✕ mcp (red) when it was requested but couldn't bind — e.g. the port is already in use — and ◇ mcp (muted) when off. Its scope covers boards in your recents plus any folder-local .mcp.json.

Tools exposed

ToolPurpose
list_boardsList known boards and their friendly names
list_foldersList the columns in a board
list_filesList the cards in a column
add_file_to_boardCreate a card in a board/column, with optional content
list_custom_commandsList available shell custom commands
run_custom_commandRun a shell custom command with full context

Create a local AGENTS.md (config menu → a) to give agents orientation about a board, and a local .mcp.json (config menu → m) for per-board MCP configuration. Note that a folder-local .mcp.json can point the MCP server at external processes, so it carries the same trust caveat as folder-local scripts — see SECURITY.md.

Note: the MCP server sees shell custom commands only — Lua-registered commands are not visible to or runnable via MCP.

Theming

Toggle between light and dark palettes with t, or set a default with display.theme.


Web server (headless)

kbrd serve runs the board as a mobile-first web app — no TUI, no JavaScript build step (plain HTML + htmx, vendored). View columns and cards; create, edit, and delete cards from a phone. Every mutation becomes a git commit and is pushed immediately, so the git remote stays the source of truth and the server is disposable.

# Local: plain HTTP on :8080 (no TLS, no git remote needed — "no sync" banner)
KBRD_TOKEN=$(openssl rand -base64 24) kbrd serve --dir ~/boards/work

Dockerized — clones the board repo on first boot, serves it over Let's Encrypt TLS:

cp .env.example .env   # set KBRD_TOKEN, GIT_TOKEN, KBRD_DOMAIN, and the GIT_URL repo
docker compose up -d

Flags / env (flag wins): --addr/KBRD_ADDR (default :8080), --domain/KBRD_DOMAIN (enables Let's Encrypt on :443+:80; needs public reachability under that domain), --token/KBRD_TOKEN (required, ≥12 chars), --git-url/GIT_URL (clone when --dir is missing/empty), --pull-interval/KBRD_PULL_INTERVAL (default 60s, 0 disables). Commit author comes from GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL.

Security notes:

  • The web token and the git credential are separate secrets; use a fine-grained PAT scoped to the single board repo (contents read/write) embedded in GIT_URL.
  • Login is a single shared token behind a rate limiter; sessions are HMAC cookies that all invalidate on restart. For LAN/Tailscale-only use, omit --domain and terminate TLS yourself (e.g. tailscale serve).
  • Web mode is safe by default: folder-local Lua, hooks, and template exec do not run, so serving an untrusted board cannot execute its code. The one opt-in is serve --scripting, which runs the board's init.lua/.kbrd.lua — its timers and the http_request/http_response request-middleware hooks (custom auth, redirects, header/response rewriting). Enable it only for boards you trust.

Conflict stance: each mutation commits locally first, then pushes. When the push is rejected (the remote moved ahead) the server reconciles with fetch → merge → push — no rebase, no force. Non-overlapping edits to a card auto-merge; a true line conflict keeps your local version as the card and writes the incoming version to a sibling <card> (conflict <name|timestamp>).md, so sync never halts and nothing is lost — the set-aside edit propagates back to every machine on the next push. All automatic flows (the web daemon and the TUI auto-sync) self-heal this way; the manual TUI sync follows git.manual_sync_mode (attended fails loud on divergence, auto reconciles like the rest). The TUI auto-sync only runs on a clean tree (a merge can't run over uncommitted edits); set git.auto_commit = true to have it commit pending edits first and keep itself synced while you work. Edits carry a content hash, so a card changed upstream mid-edit is flagged instead of silently overwritten.

Customizing the web UI

The HTML templates and static assets (style.css, the vendored htmx) are baked into the binary, but a .kbrd_web_templates/ folder inside the board overrides them file-by-file, mirroring the embedded layout:

<board>/.kbrd_web_templates/
  templates/   *.html — shadow the embedded template of the same name
  static/      style.css, htmx.min.js, or any new file

Scaffold the defaults to edit from with:

kbrd serve eject --dir ~/boards/work   # writes .kbrd_web_templates/ (never clobbers existing files)

Overrides hot-reload on save — a saved template re-parses live (a syntax error is logged and the last-good markup keeps serving), and static files are read straight from disk. The folder is committed and pulled with the board like any other content. Note the Content-Security-Policy is default-src 'self', so custom styles must be served from static/ (or inlined) — external stylesheet/script URLs are blocked.


Limitations & known gaps

  • Several scripting helpers are planned but not yet available: synchronous shell capture (kbrd.shell.run/exec), kbrd.git.*, kbrd.log.*, kbrd.config.get/all, kbrd.inspect, bundled require("json"|"re"|"http"), and a lua/?.lua require path.
  • The git_post_commit event is reserved but not yet emitted.
  • kbrd.ui.* dialogs cannot be called from hooks or timers (no coroutine context), and new commands/hooks/timers cannot be registered from inside a timer callback or hook.
  • The MCP server cannot run Lua-registered commands — only shell custom commands.
  • Global search requires ripgrep to be installed.

Project layout

DirectoryRole
commands/CLI command tree (cobra): root/default, init, clone, serve (+ eject), and their run logic
board/Headless board semantics: discovery, column/item enumeration, name sanitizing
template/Card templates: discovery, frontmatter schema, validation, rendering
config/TOML config + custom-command loading and templates
events/Event bus that feeds the scripting hooks
fs/Filesystem and git CLI helpers, plus the file watcher
mcp/MCP server: protocol, tools, command bridge, agents template
web/Headless web frontend (kbrd serve): handlers, templates, auth, git sync
model/The Bubble Tea TUI — board state, dialogs, git panel, search, switcher, theming, keys
recents/Persisted list of recent/pinned boards
script/Lua VM host and the kbrd.* API bindings
main.goEntry point — calls commands.NewRootCmd().Execute()

Development

go build -o kbrd ./   # build
go test ./...         # run the test suite

Common tasks are wrapped in a justfile (install with brew install just):

just              # list all recipes
just build        # build ./kbrd
just test         # run the test suite
just hooks        # install git hooks via prek
just snapshot     # build a local release into ./dist (no publish)
just check        # validate the GoReleaser config
just release 0.2.0  # tag v0.2.0 and push, triggering the release workflow

Git hooks are managed with prek (brew install prek), configured in prek.toml. Install them once with just hooks — commits then run gofmt, go vet, a go mod tidy check, and file hygiene checks; pushes additionally run the full test suite. Run all hooks manually with prek run --all-files.

Releases are automated with GoReleaser (see .goreleaser.yaml). Pushing a v* tag runs .github/workflows/release.yml, which builds the macOS binaries, publishes a GitHub Release, and updates the Homebrew cask in up2jj/homebrew-tap.

The CLI command tree lives in commands/ (one file per command), the TUI in model/, keybindings are declared in model/keys.go, configuration in config/, and the Lua API in script/ (documented in SCRIPTING.md).

Ver o original no GitHub

Bom para

Relacionados