CANBAN

CANBAN // DOCS

Canban Documentation

Canban (canban.dev) unifies Kanban cards for Human Context, declarative schema 10 Workflows, an Agent-first CLI, and Herdr persistent PTY terminals for native AI coding agent CLIs.

System architecture

Canban is built in Rust with native UI (longbridge/nsh — AppKit/Metal on macOS 13.0+ Apple Silicon, GTK4 on Linux x86_64 / arm64) and libghostty-vt for terminal emulation.

  • Canban UI (canban-ui): Connects over Unix socket (~/.canban/app.sock) to local AppServer, and simultaneously over Tailscale TCP or SSH tunnels to remote canband hosts.
  • AppServer (canban serve / canband): Owns SQLite WAL storage, Cards, the Workflow Engine, Scheduler, Git worktree management, and Merge Queue coordination. Closing the desktop window leaves background scheduling active.
  • Herdr Core (hc): Persistent PTY session supervisor running native Agent CLIs (claude, codex, agy, gemini, opencode, cursor-agent, etc.) so running agent sessions survive UI restarts and upgrades.

Why Canban = Kanban + Workflow + Herdr

  1. Kanban maintains Human Context: Feature specs, pasted screenshots, #Card and GitHub Issue/PR references, @Agent discussions, structured reports, and diffs stay together on each Card.
  2. Workflow automates worktrees and delivery: Dragging a Card into Develop allocates an isolated Git worktree (<dir>-<proj4>/<card-number>) and runs your workflow graph; Review integrates changes through a serialized FIFO Queue Merge.
  3. Herdr runs native Agent CLIs without interference: Keep your CLI's native TUI, MCP servers, skills, permissions, and exact-ID session resume intact.
Canban Git diff inspector for Card #1 worktree showing commit history, changed Rust files, inline diff lines, Copy Markdown, and the Review & Send to @Agent button.
Built-in worktree diff review in Canban: inspect commits and inline hunks, add line comments, and hand off findings directly with Review & Send to @Agent.

Core CLI quickstart

Inside any Canban-launched terminal or scheduled agent session, Canban injects CANBAN_CLI, CANBAN_ENDPOINT, CANBAN_CARD, CANBAN_PROJECT, and CANBAN_RUN_DIR. Add --human for pretty-printed JSON without fetching extra fields.

sh
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
"$CANBAN_CLI" card adopt --stage develop
"$CANBAN_CLI" report --state completed --message 'Implemented and verified tests' --file "$CANBAN_RUN_DIR/report.md"
canban --human --fields number,title,stage card show

See the full Canban CLI, Agent Optimization & --human guide.