Kanbus

Feature

Realtime collaboration

An optional notification layer that tells boards, agents and watchers about changes as they happen, before a git pull, while Git stays the source of truth.

Git moves changes between clones when someone pulls. That is often too slow when several agents and people work at once. Kanbus adds a small publish and subscribe channel: every change publishes a short message, and anything listening learns about it right away. Your repository files remain the only record of truth; the realtime layer only makes changes visible sooner.

A change made in one terminal shows up on the board without a pull or a reload.

How it works

Each command still writes the issue file and an event file to your working tree first. After a successful write, Kanbus publishes a message with the issue snapshot. Watchers receive it and write a speculative copy into a local overlay cache under project/.overlay/, which the console reads on top of the Git-backed files until Git catches up.

Best effort

Publishing never blocks a write. A command succeeds even if no broker is reachable.

Disposable overlay

The overlay is ignored by Git, prunes itself and is safe to delete at any time.

Git resolves conflicts

The overlay never merges or resolves anything. Conflicts are handled by Git as usual.

It is notification, not coordination. There is no automatic commit, push or pull, and no exclusive task claiming. For dispatching agent work with claims and leases, see the Issue router.

On one machine

The console server kbsc starts a local broker on a Unix domain socket and subscribes to it, so CLI changes in any terminal reach the board immediately.

# Terminal 1
kbsc

# Terminal 2
kbs create "Realtime task"
kbs update kanbus-a1b2c3 --status in_progress

To see the raw messages, run a watcher that prints each one:

kbs gossip watch --print

Across machines with MQTT

For a team or a fleet of agents on several machines, point Kanbus at an MQTT broker such as Mosquitto or a managed service. Set the transport and broker once per machine:

kbs setup env KANBUS_REALTIME_TRANSPORT --value mqtt
kbs setup env KANBUS_REALTIME_BROKER --value mqtt://127.0.0.1:1883

With --broker auto, Kanbus can also start a local Mosquitto for you if one is installed and no broker is reachable. Messages use the topic projects/{project}/events, where {project} is the project key.

Learn more