Realtime Collaboration

Federated realtime updates for agents and humans. Gossip messaging for instant visibility, with an overlay cache for speculative reads between pulls.

~❯kbs updateMQTT

Architecture

Realtime is additive: gossip adds visibility without changing your Git workflow.

Every change still writes to your working tree first: issue JSON plus an append-only event file. Realtime collaboration adds a pub/sub notification channel and a disposable overlay cache so other tools can react immediately before a pull lands.

Realtime Collaboration architecture diagram

The overlay never resolves conflicts. Git remains the only conflict mechanism.

What You Get

Instant awareness without changing your Git workflow.

Immediate visibility

Watchers learn about changes immediately, without waiting for a git pull. This is notification, not dispatch.

Speculative reads

The overlay cache can temporarily override reads so the UI can show updates learned via gossip before Git history catches up.

Gossip Layer

Small pub/sub messages with deterministic semantics.

Best-effort publishing

Mutations never depend on the broker. A command can succeed even if publishing fails. Receivers dedupe notifications and ignore self-produced messages.

Overlay Cache

Disposable snapshots and tombstones that never change Git’s role.

Merge rule: base + overlay

Watchers write issue snapshots to project/.overlay/issues/. Deletes are explicit tombstones inproject/.overlay/tombstones/. Reads merge Git-backed base with overlay when the overlay is newer.

Overlay entries are self-pruning and safe to delete wholesale.

Transports

UDS locally, MQTT for LAN and cloud.

UDS (local)

Run a lightweight local broker on a Unix domain socket for same-machine collaboration between tools.

Terminal
kbs gossip broker
kbs gossip watch

MQTT (LAN / cloud)

Use Mosquitto locally or a managed MQTT broker later. Kanbus can autostart a local Mosquitto when configured.

Terminal
kbs gossip watch --transport mqtt --broker auto

What It Is Not

Realtime coordination without changing the conflict model.

  • No automatic commit, push, or pull.
  • No gossip authority: your repository files are always the truth.
  • No conflict resolution beyond Git conflicts.
  • No exclusive task claiming (dispatch belongs elsewhere).

Learn More

Quickstart and full technical details.

Quickstart
# Terminal 1 (UDS broker)
kbs gossip broker

# Terminal 2 (watch + overlay)
kbs gossip watch
Read the summary →Read docs (source) →

Tip: set GATSBY_MKDOCS_BASE_URL to link to your deployed MkDocs site.