Kanbus

Feature

Git-native storage

Every issue is a JSON file in your repository. There is no separate database to run or sync, and your backlog gets history, branches and review from Git.

Kanbus keeps project data where your code already lives. Each issue is one JSON file under project/issues/, each change also writes an event record under project/events/, and configuration lives in .kanbus.yml. Any tool that can read a file can read your backlog, and any change to it is a diff you can review.

Each command writes a JSON file in project/issues, and Git carries it to everyone else.

Just files

When you create an issue, Kanbus writes a file. When you update it, Kanbus rewrites that file. When you delete it, the file goes away.

ls project/issues/
# kanbus-a1b2c3.json  kanbus-d4e5f6.json

cat project/issues/kanbus-a1b2c3.json

{
  "id": "kanbus-a1b2c3",
  "title": "Update docs",
  "type": "task",
  "status": "open",
  "priority": 2,
  "parent": null,
  "labels": [],
  "dependencies": [],
  "comments": []
}

IDs are generated from a hash plus a random nonce rather than a counter, so two people or agents creating issues at the same time do not collide. Agents should still change issues through kbs commands rather than editing the files directly, so that validation, workflow rules and event history apply.

History, branches and review from Git

Because issues are tracked files, Git already gives you an audit trail. git log project/issues/kanbus-a1b2c3.json shows who changed an issue and when. Issues created on a feature branch stay on that branch until it merges, and issue changes show up in pull requests next to the code they describe.

kbs update kanbus-a1b2c3 --status in_progress
kbs commit
git log --oneline -- project/issues/

kbs commit commits pending changes under project/issues/; a normal git add and git commit works just as well.

How merges behave

One file per issue means edits to different issues touch different files, so they never conflict. That is the main difference from formats that keep every issue in a single file.

Read speed does not depend on a database either. The CLI starts a small index daemon on demand to speed up commands like kbs list; it holds only an index derived from the files and can be turned off with KANBUS_NO_DAEMON=1. The optional overlay cache used for realtime updates lives in project/.overlay/, is ignored by Git and is safe to delete.

Learn more