Kanbus

Feature

Beads compatibility

Use the Kanbus CLI and board on an existing Beads project without converting it, and migrate to one file per issue when you are ready.

Kanbus is a successor to Beads, and it can work directly with a Beads project's .beads/issues.jsonl file. In Beads compatibility mode, the Kanbus CLI and console read and write that file, so you can try Kanbus on real data while your existing Beads tooling keeps working. When you want Kanbus's own storage, a migration command converts the data.

Turn it on

Compatibility mode is opt in. Use the --beads flag for a single command:

kbs --beads list
kbs --beads show bdx-epic
kbs --beads create "New issue" --parent bdx-epic

Or turn it on for the project in .kanbus.yml, so plain commands and the console use the Beads file:

beads_compatibility: true

The core commands work in this mode: list, ready, show, create, update, delete and dep. Lifecycle hooks run too. Some newer features need native storage: local task filters such as --no-local are not supported, and agent provenance flags are rejected.

Why switch to native storage

Beads keeps every issue in one JSONL file, which means two people or agents editing different issues still touch the same file and can conflict. Kanbus stores one JSON file per issue under project/issues/, so edits to different issues never conflict. There is also no SQLite index or daemon to keep in sync: Kanbus reads the files directly.

In the project's own benchmark on the 836-issue Beads repository, the Rust CLI listed every issue from the Beads JSONL in about 10 to 12 ms, compared with about 200 ms for the Beads CLI on a cold start. Native storage brings the Kanbus features that Beads mode lacks, such as local tasks and agent provenance.

Migrate when you are ready

There is no deadline. When you want to move, the migration command converts the Beads data into project/issues/:

kbs migrate
kbs validate

kbs migrate --into-existing imports Beads issues into a project that is already initialized and is safe to re-run. Migration validates strictly, so issues with missing parents, unknown types or statuses outside your workflow must be fixed, or the configuration extended, before they import.

Learn more