RepoKanban

A drag-and-drop kanban board backed by a KANBAN.md file in your git repo.

No accounts, no cloud — just a markdown file you can commit, diff, and merge.

Install

npm install -g repokanban

Or run directly without installing:

npx repokanban

Usage

Getting started

Navigate to any git repository in your terminal and run:

repokanban

If no KANBAN.md exists, you'll be prompted to create one. A background server starts and your board opens in the browser.

Editing your board

• Add tasks using the input at the bottom of each column
• Drag and drop tasks between columns or reorder within a column
• Click a task to edit its title, description, and priority
• Move tasks using the arrow buttons on each card

Changes auto-save to KANBAN.md on disk within 1 second. The sync indicator in the header shows the save status.

Committing changes

RepoKanban never creates git commits — it only reads and writes the KANBAN.md file. Commit it as part of your normal workflow:

git add KANBAN.md
git commit -m "Update kanban board"

Multiple boards

Run repokanban in a second project directory and it registers with the existing server — no duplicate processes. A dropdown in the header lets you switch between boards:

cd ~/projects/frontend
repokanban

cd ~/projects/backend
repokanban        # adds to existing server, opens same browser tab

Board history

RepoKanban remembers every repository you've used. Previously used boards appear greyed out in the dropdown. Click one to reactivate it — no need to go back to the terminal.

If a KANBAN.md file is deleted from a previously tracked repository, it is automatically removed from the history the next time RepoKanban starts.

Live reload

If KANBAN.md is modified outside the app (e.g., after git pull, or editing in a text editor), the board updates in the browser automatically via server-sent events.

Background operation

The server runs in the background and survives terminal closure. It automatically shuts down when:

• You close all browser tabs connected to RepoKanban (after a 10-second grace period)
• You click the Stop button (power icon) in the header

CLI options

repokanban                # start server, open browser
repokanban --port 8080    # use a specific port
repokanban --no-open      # start server without opening browser
repokanban --version      # print version
repokanban --help         # show help

KANBAN.md format

# Kanban

## To Do
- ⚪ Design landing page `high`
  > Simple single-page site for repokanban.com
- ⚪ Write tests `medium`

## In Progress
- 🟡 Set up CI pipeline `high`

## Complete
- 🟢 Initialize repository

Task markers

| Column | Marker | |---|---| | To Do | ⚪ | | In Progress | 🟡 | | Complete | 🟢 |

Priorities

paused, low, medium, high, urgent — written as backtick-wrapped tags after the task title.

Descriptions

Add indented blockquotes below a task for descriptions:

- ⚪ My task `high`
  > This is the description
  > It can span multiple lines

How it works

RepoKanban runs a local Node.js server that reads and writes your KANBAN.md file directly on disk. The browser UI communicates with the server over HTTP and SSE (server-sent events). No GitHub API calls, no authentication, no cloud services.

The server coordinates multiple CLI invocations via a lockfile at ~/.repokanban/server.json and persists your board history at ~/.repokanban/boards.json.

Requirements

Node.js 18+

License

MIT