# Canban (`canban.dev`) — Complete Reference for LLMs > Canban (`canban.dev`, GitHub: `jjyr/canban`, Rust + NSH + `libghostty-vt` + `herdr-core`) is an open-source native macOS and Linux Kanban workbench for AI coding agents. Formula: `Canban = Kanban + Workflow + Herdr`. **Disambiguation**: Canban (`https://canban.dev/`) is a Rust desktop application and daemon (`canband`), distinct from generic Kanban boards or SaaS issue trackers. --- # Canban — Native Kanban Workbench for Coding Agents > Canban = Kanban + Workflow + Herdr Turn Kanban cards into automated coding workflows. Keep using your native agent CLIs, including Claude Code and Codex, while Canban handles task context, isolated Git worktrees, and merging. ## Highlights - **Kanban**: Maintain Human Context — Zero branch collisions: every Card gets its own clean checkout - **Workflow**: Custom Workflow Scheduling — Automatic FIFO rebase merge, upstream push & worktree cleanup - **Herdr**: Native Agent CLI Support — Bring any native Agent CLI inside persistent Herdr TTYs ## Install ```sh curl -fsSL https://canban.dev/install.sh | bash ``` ```sh curl -fsSL https://canban.dev/install.sh | bash -s -- --headless ``` ## Navigation - Install: https://canban.dev/install/ - Docs: https://canban.dev/docs/ - Workflows: https://canban.dev/docs/workflows/ - CLI: https://canban.dev/docs/cli/ - Changelog: https://canban.dev/changelog/ - GitHub: https://github.com/jjyr/canban --- # Install Canban > A native workbench on your desktop. Persistent agents on your server. ![Canban macOS desktop app showing Card #2 in Develop with an isolated Git worktree, activity comments, workflow pipeline status, and a live Herdr @developer terminal running cargo test.](https://canban.dev/screenshots/board-terminal.png) *Canban desktop workbench: Card #2 specification, workflow progress bar, and live @developer Herdr PTY terminal side by side.* ## Before you begin Install Git and your chosen agent CLI, and complete the agent’s authentication. Canban uses Herdr Core (hc) to run persistent terminal sessions and guides you through setup on first launch if it is missing. ## Desktop Run this command to install or update the desktop app. ```sh curl -fsSL https://canban.dev/install.sh | bash ``` - **macOS 13.0+ · Apple Silicon**: Installs Canban.app in /Applications. - **Linux · x86_64 / arm64**: Installs to ~/.local/opt/canban and adds an application launcher. GTK4 and GStreamer runtime libraries are required. ### Linux runtime dependencies ```sh # Ubuntu / Debian sudo apt install libgtk-4-1 libgstreamer1.0-0 libgstreamer-plugins-base1.0-0 # Arch Linux sudo pacman -S gtk4 gstreamer gst-plugins-base # Fedora sudo dnf install gtk4 gstreamer1 gstreamer1-plugins-base ``` ## Headless Linux server Install the CLI and daemon without GTK4 or a desktop session. Connect from the desktop app over SSH or Tailscale. Install Git, Herdr Core, your agent CLI, and project dependencies on the server. ```sh curl -fsSL https://canban.dev/install.sh | bash -s -- --headless ``` ## Updates Run the same installation command again to update an existing installation. The desktop app also provides an update action when a new version is available. ## Build from source For platform build dependencies and source installation instructions, see the GitHub README. (https://github.com/jjyr/canban#build-from-source) ## Frequently asked questions ### What is Canban? Canban is a native Kanban and terminal workbench for AI coding agents. It brings task specifications, agent discussions, progress, and code review together on cards, with workflows that organize development and delivery. ### Which agents can I use? Canban uses Herdr to run agents, so agents supported by Herdr are supported in Canban — including Claude Code, Codex, Antigravity, Cursor CLI, and custom terminal agents. Install and authenticate your chosen agent CLI before using it in Canban. ### Which operating systems are supported? Canban is available for macOS 13.0 or later on Apple Silicon, and Linux on x86_64 and arm64. Linux desktops require GTK4 and GStreamer runtime libraries. Linux servers without a desktop can use headless mode. ### How do I install or update Canban? Use the installation command on this page to install or update Canban. Running agents also requires Git, your chosen agent CLI, and Herdr Core. Canban guides you through Herdr Core setup on first launch if it is missing. See the Changelog for release details. ### Can I run agents on a remote server? Yes. Install Canban in headless mode on a Linux server, then connect from the desktop app over SSH or Tailscale to manage remote tasks and terminals. Install your agent CLI and development dependencies on the remote machine. ### Is Canban free? Canban is free and open source under the Apache-2.0 license. Your chosen agents, model APIs, or other services may have separate costs. --- # 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 (`-/`) 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. --- # Workflow YAML Syntax & Execution Semantics > Canban workflows are declarative YAML 1.2 graphs (`schema: 10`, `CURRENT` in `crates/workflow-engine`) stored in SQLite (`workflow_sources` and immutable `workflow_revisions`). Visual Studio, manual YAML edits, and Edit with agent all compile and validate through the exact same Rust engine. ## Visual Studio, SQLite source of truth & Stage projection Open **Workflows** in any Project header to switch between **Visual Studio**, **YAML Source**, **History**, and **Edit with agent**: - **SQLite Single Source of Truth**: Workflows live inside `canban.sqlite` (`workflow_sources` + immutable `workflow_revisions`) rather than hidden YAML files in `~/.canban`. Each `WorkflowRun` freezes its `definition` and `definition_revision` at creation so publishing new YAML never mutates in-flight runs. - **Linear Schema Migrations (`1..=10`)**: `crates/workflow-engine/src/migrations.rs` sets `BASELINE = 1` and `CURRENT = 10`, sequentially upgrading older YAML documents on parse. - **How Visual Studio Maps Stages (`stages.rs`)**: YAML files do not have a top-level `stages:` block; instead, `canban_workflow_engine::stages` derives one Stage swimlane (`StageView`) per Board column (`column`, `name`, ordered `steps`, `entry_rule`, and `exit` via `card.move` using `column: $next` / `next: $entry` or `Stay`). Each `Step` can set `stage: ` explicitly (or let Studio infer it from `on` column entry rules and `card.move` transitions) and `enabled: false` to skip a step at compile time without breaking links. ![Canban Workflows Visual Studio showing development.yaml with Backlog, Develop (@developer Implement), and Review (External PR check condition, Human approval, and Queue merge) lanes.](https://canban.dev/screenshots/workflow-studio.png) *Visual Studio for development.yaml: Backlog, Develop (@developer), and Review stages with the /card/source_trust == external_pr branch, Human approval gate, and Rebase · Sync Queue merge.* ## Verified YAML structure (schema: 10) Parsing uses `serde_yaml_ng` with `#[serde(deny_unknown_fields)]` on `Document`, `Step`, `WorkflowColumn`, `WorkflowRule`, `EventSelector`, and `ScheduleCardConfig`. Unknown fields are rejected before publication. ### Top-level `Document` keys (`crates/workflow-engine/src/source.rs`) | Key | Type & Default | Purpose | | --- | --- | --- | | `schema` | `u32` (required; `10` is `CURRENT`) | Schema version (`1..=10` accepted and migrated to `10`). | | `id` | `String` (required) | Non-empty workflow identifier (e.g., `delivery:default`). | | `name` | `String` (required) | Display name shown in Studio and Boards. | | `scope` | `project` (default) or `global` | `global` (`__global`) runs host-level schedules/scripts without Board `columns` or `card:` creation rules. | | `enabled` | `bool` (default `true`) | Enables or disables rule matching for this workflow source. | | `columns` | list of `{ id, name }` | Declares Board columns (`id` allows ASCII alphanumeric, `-`, `_`). Defaults to Project columns when omitted. | | `env` | `{ KEY: VALUE }` map | Scalar environment variables inherited by all `agent` and `script` steps. | | `on` | `{ : WorkflowRule }` (non-empty) | Event triggers (`event`, `start_at`, `match`, `enabled`) and cron schedules (`cron`, `timezone`, `overlap`, `card`). Also accepts GitHub Actions `on: { schedule: [{ cron: ... }] }` shorthand. | | `steps` | list of `Step` (1..=256) | Ordered step definitions forming a directed acyclic automatic graph. | | `workspace` | `WorkspaceSettings` | `create_worktree` (default `true`), `base_branch`, `sync_base` (requires `create_worktree: true`), `remote` (default `origin`). | | `max_steps` | `u32` (`1..=1000`, default `100`) | Guardrail cap on total step visits per `WorkflowRun`. | ### `on.` triggers & scheduled rules - **Event triggers**: `event` (`card.column_entered`, `card.column_left`, `card.created`, `card.updated`, `manual`, etc.), `start_at` (target step ID), `match` (`EventSelector`: `column`, `actor`, `origin`, `source_kind`, `reason`, `changed_fields`, `repository`, `subject`, `reply_to`, `include_related`, `include_initial`), and `enabled` (`bool`, default `true`). - **Schedule triggers**: Set `cron` (5-field POSIX cron or `@hourly` / `@daily` / `@weekly` / `@monthly`) to mark a rule as `event: schedule`. Optional `timezone` (`Local` default, `UTC`, fixed offset like `+08:00`, or IANA name), `overlap` (`skip` default, `queue`, `allow`), and `card: { column, title, body }` (with `{{date}}`, `{{datetime}}`, `{{run_number}}`, `{{workflow}}`, `{{rule}}` placeholders; omit `card` for Cardless runs). ### `steps[]` fields - Common keys: `id` (unique non-empty string), `name`, `uses` (optional when top-level `run:` is present), `with`, `next` (defaults to next list item except for `condition` and `complete`; `card.move` may use `$entry`), `stage` (optional column ID), `enabled` (`bool`, default `true`), `on_changes_requested` (top-level rework target on `approval` / `deliver`), `on_failure` (top-level single-use automatic fallback step ID on `script` steps). - `script`-only keys accepted at step top-level or inside `with:` (without conflicting values): `run`, `shell` (default `bash -eo pipefail`, fallback `sh -e`), `working_directory` (relative to Card workspace, no `..`), `timeout_minutes` (`1..=1440`), `timeout_seconds` (`1..=86400`), `continue_on_error` (`bool`, default `false`). - `env`: `{ KEY: VALUE }` map, valid only on `agent` and `script` steps. Precedence order: host & `CANBAN_*` context < workflow `env` < `$CANBAN_ENV` exports < step `env`. ### Canonical `development.yaml` (`default_document`) ```yaml schema: 10 id: delivery:default name: Development enabled: true columns: - id: backlog name: Backlog - id: develop name: Develop - id: review name: Review on: develop: event: card.column_entered start_at: agent:develop match: column: develop review: event: card.column_entered start_at: condition:external_pr match: column: review steps: - id: agent:develop name: Implement uses: agent with: profile: developer next: move:develop - id: move:develop name: Move to Review uses: card.move with: column: review next: condition:external_pr - id: condition:external_pr name: External PR check uses: condition with: pointer: /card/source_trust equals: external_pr then: approval:review otherwise: deliver:review - id: deliver:review name: Queue merge uses: deliver with: sync_upstream: true next: __end on_changes_requested: agent:develop - id: approval:review name: Human approval uses: approval with: title: External PR; human approval is required before merging next: __end on_changes_requested: agent:develop - id: __end uses: complete workspace: create_worktree: true sync_base: true remote: origin ``` ## All 9 step types (uses:) | `uses` | `with` & step fields | Runtime behavior | | --- | --- | --- | | `agent` | `with.profile` (optional Profile ID), `with.instruction` (optional; resolves built-in prompt when omitted), `env`, `next` | Dispatches an Agent PTY in the Card worktree (`waiting_agent`). Advances only on `canban report --state completed`. | | `script` (or `run:`) | `run`, `shell`, `working_directory`, `timeout_minutes`, `timeout_seconds`, `continue_on_error`, `env`, `on_failure`, `next` | Runs via Herdr Core without consuming `scheduler.max_agents`. Reads `$CANBAN_ENV` (`inputs.env`) and `$CANBAN_OUTPUT` (`outputs.`). | | `admit` | `with.agent_slot` (`bool`, default `true`), `with.max_ready` (`1..=100`, optional), `next` | Enters `waiting_capacity`; AppServer releases runs in Board order when capacity is available. | | `card.move` | `with.column` (column ID or `$next`), `next` (step ID or `$entry`) | Moves Card (`origin: "workflow"`) without re-firing duplicate entry triggers; `$entry` jumps to target column's `on` start. | | `condition` | `with.pointer` (JSON Pointer), `with.equals` (JSON value), `with.then` (step ID), `with.otherwise` (step ID) | Evaluates pointer against `{inputs, outputs, card}` and branches immediately. Ignores `next` (compiled `condition` has no `next` field). | | `approval` | `with.title` (non-empty string), `on_changes_requested` (optional rework step ID), `next` | Pauses in `waiting_approval` and sets `Card.human_gate` until approved or sent for rework. | | `deliver` | `with.profile` (default `@merger`), `with.target_branch`, `with.strategy` (`rebase` default, `squash`, `merge`), `with.sync_upstream` (`true` default), `with.batch_size` (`1..=50`, default `5`), `with.test_command`, `with.max_conflict_attempts` (default `3`, `0` disables), `on_changes_requested`, `next` | Enters serialized FIFO Queue Merge (`waiting_delivery`). Pauses in `waiting_approval` immediately if `card.hold_auto_merge` is set. | | `notify` | `with.message`, `next` | Emits `workflow.notified` timeline event and attention notification, then continues to `next`. | | `complete` | *(none)* | Terminal step marking the `WorkflowRun` `completed`. | ## Conditions, source_trust & admit gates ### Condition evaluation (`condition`) During execution (`crates/workflow-engine/src/runtime.rs`), `condition` builds `{ "inputs": run.inputs, "outputs": run.outputs, "card": card }` (with `card.source_trust` populated from `Card::trust_level()` — `"local"`, `"collaborator"` for GitHub Issues, or `"external_pr"` for external GitHub PRs) and resolves `with.pointer` (must be empty or start with `/`): - **Equality rules**: Matches exact JSON equality, string `"true"` / `"false"` against booleans, numeric strings against numbers, and an absent pointer against `null`. - **External PR gate**: `pointer: /card/source_trust` with `equals: external_pr` routes untrusted PRs to `approval:review` while sending trusted branches to `deliver:review`. - **Script output branching**: Any `KEY=VALUE` written to `$CANBAN_OUTPUT` in a prior `script` step is stored at `/outputs//`, e.g., `pointer: /outputs/script:check/gate` with `equals: ok`. ### Capacity & ready-queue gates (`admit`) `admit` validates that at least one of `agent_slot: true` or `max_ready: 1..=100` is enabled (`definition.rs`). Waiting runs enter `waiting_capacity` and are released by AppServer's admission pump (`canban_scheduler::admissions`) strictly in **Board order** within their column: - `agent_slot: true` (default): Holds the Card until a global automatic Agent slot (`scheduler.max_agents`, default `8`) is free. - `max_ready: K`: Caps how many Cards that already passed this gate may remain in that column (for example, gating Backlog planning at `max_ready: 2`). - `canban card adopt`: Claiming a live interactive session via `start_adopted` bypasses `admit` gates so an active user terminal is never queued behind pending capacity. ## Validation, rework loops & failure handling ### Static validation rules (`definition.rs`) Before saving or publishing, `validate_definition` verifies all column IDs, profile IDs, step targets, `sync_base` prerequisites (`create_worktree: true`), relative `working_directory` bounds, and **cycle freedom**: automatic cycles through `next`, `condition.then`, and `condition.otherwise` are rejected. ### Rework & failure edges Loops are only permitted across explicit decision or failure boundaries: - **Human rework (`on_changes_requested`)**: Available on `approval` and `deliver` steps (compiles to `rework`). Requesting changes (`workflow.decide` with `decision: "rework"`) clears `human_gate`, saves optional reviewer notes into `inputs.rework_feedback`, and routes back to the target step (e.g., `agent:develop`). - **Script fallback (`on_failure`)**: When a `script` step fails (`continue_on_error: false`), `fail_script` records exit code and log tail feedback (`rework_origin: "script_failure"`) and jumps to `on_failure` **at most once per run** (`script_failures[step_id] == 0`). A second consecutive failure (or unconfigured `on_failure`) pauses in `waiting_approval` for human Retry, Rework, or Stop. - **Agent reporting & stale detection**: Terminal exit or idle never advances `agent` steps. `canban report --state completed` advances to `next`; `blocked` / `failed` moves the run to `blocked`; `backlog` cancels the run. Modifying Card title/body/content mid-run changes `input_digest` and marks completion `stale` until human rework or stop. ## Serialized FIFO Queue Merge (deliver) Entering `deliver` serializes delivery across parallel Card worktrees so branches never race against the target branch: 1. **Strict FIFO Queue Order**: Drains `waiting_delivery` runs in `(inputs.queued_at, storage_index)` order, grouping up to `batch_size` (`1..=50`, default `5`) compatible queue-head Cards (`target_branch`, `strategy`, `sync_upstream`, `test_command`, and conflict `profile`) into `/worktrees//_merge_queue`. 2. **Agent Turn-Settle Guard**: If an Agent invoked `canban report --state completed` mid-turn while Herdr still reports active work, Canban waits for the turn to settle (bounded by a 3-minute grace window) before integrating. 3. **Integrate & Verify**: Applies `strategy` (`rebase` default, `squash`, or `--first-parent` `merge`), then runs `test_command` once on the integrated batch if configured (skipped when unset). 4. **Fast-Forward, Push & Archive**: Clean batches fast-forward the target branch once, push once when `sync_upstream: true`, and auto-archive merged Cards after saving `refs/canban/cards/`. 5. **Conflict Resolution (`@merger`)**: On batch conflict or test failure, Canban persists `MergeBatch` and `refs/canban/batch//{target,card-}`, marks participating runs `waiting_batch`, and dispatches one Project-scoped `@merger` session in `_merge_queue` (which can fix in place or evict a failing Card via `canban batch report --state completed --evict `). Single-Card deliveries without `test_command` resolve directly in the Card worktree up to `max_conflict_attempts` (default `3`, `0` disables). ## Managing workflows via CLI Inspect, validate, export, and publish workflows from the terminal (or query the live schema contract via `workflow.schema`): ```sh canban call workflow.schema '{}' canban workflow sources --project-id canban workflow export --project-id --name development.yaml --output development.yaml canban workflow submit --project-id --revision --file development.yaml --check canban workflow submit --project-id --revision --file development.yaml canban workflow set-default --project-id ``` See [Canban CLI, Agent Optimization & --human](/docs/cli/) for `--global` workflow flags, `schedule` commands, and `--human` formatting. --- # 24 Built-in Agent CLIs, Herdr PTYs & CLI > Canban runs native coding agent CLIs inside persistent Herdr PTY terminals (`herdr-core`) rendered with `libghostty-vt`, preserving every tool's native TUI, MCP servers, skills, permissions, and conversation resume. ## Zero-interference native TUI, MCP & skill preservation Rather than reimplementing provider chat wrappers or injecting fragile `Stop` hooks, Canban launches your chosen CLI inside a `herdr-core` (`hc`) supervised PTY: - **Native TUIs & Controls**: Interact directly with the agent's own terminal UI via `libghostty-vt` (rendered in native AppKit/CoreText on macOS and GTK4 on Linux, with SGR/pixel mouse reporting, OSC 8 hyperlinks, and 17 dark themes including Monokai). - **MCPs, Skills & Permissions Intact**: Because the real CLI binary executes in the Card worktree with your home configuration, existing MCP servers, custom skills, sandbox flags, and auth logins work unchanged. - **Restart-Safe PTYs & Exact Resume**: Closing Canban, restarting `canband`, or live-upgrading the app leaves running `herdr-core` sessions alive. Finished sessions can resume exact provider conversation IDs (`--resume`, `--session`, or `--conversation`) when supported. - **Global Scheduler Budget**: Automatic workflow steps share a configurable concurrency limit (`scheduler.max_agents`, default `8`), while manual shells and `script` steps run outside the agent budget. ![Canban Card #2 running a native @developer CLI session inside a persistent Herdr PTY terminal alongside card activity, Hold auto-merge, and workflow progress.](https://canban.dev/screenshots/board-terminal.png) *Live @developer Herdr PTY running cargo test inside Card #2's isolated Git worktree (acme-api-f4c9/2), waiting for explicit canban report completion.* ## All 24 built-in CLI agents Canban's catalog (`crates/profiles/src/catalog.rs`) includes 24 official interactive CLI presets matching Herdr's terminal detector and resume planner, plus custom profiles in `config/agents.json` and dynamic `herdr: