# 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.

- [Workflow YAML & Semantics](https://canban.dev/docs/workflows/): Verified schema 10 Document/Step syntax, all 9 uses: types, condition pointers, admit gates, rework/failure handling, and FIFO Queue Merge.
- [Canban CLI & --human](https://canban.dev/docs/cli/): Core CLI subcommands, compact JSON & server-side --fields shaping, zero-config env injection, request_key idempotency, and --human usage.
- [24 Agent CLIs & Herdr PTYs](https://canban.dev/docs/agents/): All 24 built-in CLI agents, libghostty-vt terminal preservation, canban card adopt, and zero-interference native TUIs/MCPs.
- [Remote Linux Hosts (canband)](https://canban.dev/docs/remote-hosts/): Headless Linux canband daemons, Tailscale direct TCP with bearer auth, SSH bootstrap/fallback, offline cache, and Diagnostics.
- [Install & FAQ](https://canban.dev/install/): Desktop macOS/Linux and headless server installation, Linux GTK4/GStreamer dependencies, and answers to common questions.
- [Changelog](https://canban.dev/changelog/): Published Canban releases, latest versions first, with original release notes.

## 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.](https://canban.dev/screenshots/review-diff.png)

*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](/docs/cli/) guide.
