kanban-gui

kanban-gui

A Go web server that renders the file-based kanban skill board in the browser, with live updates — whenever a task file changes on disk, every open browser tab refreshes itself over a WebSocket.

• HTML rendered with a-h/templ
• File watching with fsnotify (inotify on Linux)
• Live reload over gorilla/websocket
• Markdown (PRDs, epic docs, task discussions) rendered with goldmark (GitHub-flavored)

Screenshots

Board — every milestone's tasks in status columns, each card showing type, priority and Actions/DoD progress.	Task — Actions & Definition-of-Done checklists ([ ]/[x]/[!]) and the dated Discussion log, opened in a slide-in drawer over the board.	PRD — a milestone's product brief rendered from Markdown in the same drawer.

Install

Download a prebuilt binary (recommended)

Grab the archive for your OS/arch from the latest release, extract it, and put kanban-gui on your PATH:

# Linux / macOS — pick the asset matching your platform
curl -sSfL https://github.com/JLugagne/kanban-gui/releases/latest/download/kanban-gui_linux_amd64.tar.gz | tar -xz
sudo mv kanban-gui /usr/local/bin/

Assets are named kanban-gui_<os>_<arch>.tar.gz (.zip on Windows) — e.g. kanban-gui_darwin_arm64.tar.gz, kanban-gui_windows_amd64.zip.

With Go

go install github.com/JLugagne/kanban-gui@latest

From source

go build -o kanban-gui .

The generated *_templ.go files are committed, so a plain go build works without any extra tooling. If you edit a .templ file, regenerate with:

go generate ./...
# or: go tool templ generate   (templ is registered as a module tool dependency)

Upgrading

A prebuilt binary can update itself in place to the latest GitHub release:

kanban-gui upgrade

It detects the latest release for your OS/arch, and replaces the running executable (no-op if you are already up to date). Check the current version with:

kanban-gui version

Builds installed via go install or built from source report version dev; use prebuilt release binaries for self-update.

Usage

Run it from a project directory that has a .tasks/ folder:

kanban-gui

It prints the URL on startup and serves on http://localhost:9888 by default:

  kanban-gui
  tasks:  /path/to/project/.tasks
  url:    http://localhost:9888/
  watching for changes — press Ctrl+C to stop

Flags

kanban-gui -tasks ../other-project/.tasks -port 8080

When -port is not given and the default port is already in use, the server tries the next port (9889, 9890, …) until it finds a free one. If you pin -port explicitly, it fails fast instead.

Commands

What you can view

• Board — all milestones, or a single milestone, as status columns (backlog → todo → in progress → blocked → done → cancelled). Cards show type, priority, blockers, and Actions/DoD progress bars.
• Task detail — front matter, Actions and Definition of Done checklists (with [ ] / [x] / [!] states), and the Discussion log rendered as markdown.
• PRD — each milestone's PRD.md, rendered.
• Epic — each epic's doc.md plus a board of that epic's tasks.

The board is read-only: it reflects the files on disk. Edit task files with your editor (or the kanban skill) and the UI updates instantly.

Layout it expects

.tasks/
├── M1-<slug>/
│   ├── PRD.md
│   └── <epic-slug>/
│       ├── doc.md
│       └── TASK-001.md
└── M2-<slug>/
    └── ...

If .tasks/ doesn't exist yet, the server still starts and shows an empty state — it picks up the directory as soon as it's created.