Local files

The board is a folder of JSON files in your repository. Install the CLI, initialize the project and commit the board with your code.

How it works

kbs init adds a project/ folder and a .kanbus.yml file to your repository. Each issue is one JSON file in project/issues/. The CLI reads and writes those files directly, with no database or server in between, and kbsc serves a realtime board over the same folder, on port 5174 unless you choose another.

Because the board is part of the repository, it travels with branches, shows up in pull requests and has the same history as your code. An agent working in a checkout already has everything it needs.

Set it up

Install the CLI. The Rust tools are kbs and the board server kbsc; the Python package installs the same commands as kanbus, without the board server. Both read and write the same files, and the examples below use kbs.
```
pip install kanbus        # the kanbus command
cargo install kanbus      # the kbs and kbsc commands
```
Initialize the repository. Run this at the root of a git repository.
```
kbs init
```
Choose a project key and a console port. Every new board starts with the key kanbus. Change it in .kanbus.yml before you create issues, so ids from different boards cannot be confused, and give each repository its own port.
```
project_key: acme
console_port: 4311
```

Create and move work. kbs create prints the new issue's id; use it in the commands that follow.

kbs create "Write the sign-in form" --type task
kbs update acme-a1b2c3 --status in_progress --assignee you@example.com
kbs comment acme-a1b2c3 "Validation runs on blur now"
kbs close acme-a1b2c3

Open the board. Leave it running while you or your agents work; it updates as the files change.
```
kbsc
```
Commit the board with your code. kbs commit stages and commits the issue files, so board changes land in the same history as the work they describe.
```
kbs commit
git push
```
Tell your agents how to use it. This writes the Kanbus section of AGENTS.md and keeps it in step with your configuration.
```
kbs setup agents
```

Follow the full walkthrough

Good to know

Two repositories that keep the default key kanbus share a realtime channel when a board is open, which is why the key is worth changing on day one.
If two people change the same issue on different branches, git reports a conflict in that issue's file. Resolve it like any other conflict before running the next command.
kbs commit commits project/issues/ only. Kanbus never commits on its own, so make it part of every agent's finishing routine.