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

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

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

*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:` profiles:
| ID | Agent | Binary | Exact Resume | Model / Effort Args |
| --- | --- | --- | --- | --- |
| `codex` | Codex | `codex` | Yes (`resume`) | `-m`, reasoning effort |
| `claude` | Claude Code | `claude` | Yes (`--resume`) | `--model`, `--effort` |
| `agy` | Antigravity | `agy` | Yes (`--conversation`) | `--model`, `--effort` |
| `gemini` | Gemini CLI | `gemini` | Yes (`--resume`) | `-m` |
| `opencode` | OpenCode | `opencode` | Yes (`--session`) | `-m`, `--variant` |
| `cursor` | Cursor Agent | `cursor-agent` | Yes (`--resume`) | `--model` |
| `pi` | Pi | `pi` | Yes (`--session`) | `--model`, `--thinking` |
| `omp` | Omp | `omp` | Yes (`--resume=`) | `--model` |
| `copilot` | GitHub Copilot | `copilot` | Yes (`--resume=`) | `--model` |
| `droid` | Droid | `droid` | Yes (`--resume`) | `-m` |
| `amp` | Amp | `amp` | Fresh launch | — |
| `kimi` | Kimi | `kimi` | Yes (`--session`) | `--model` |
| `kiro` | Kiro | `kiro-cli` | Fresh launch | `--model` |
| `qwen` | Qwen Code | `qwen` | Yes (`--resume`) | `-m` |
| `devin` | Devin | `devin` | Yes (`--resume`) | — |
| `cline` | Cline | `cline` | Fresh launch | — |
| `grok` | Grok | `grok` | Yes (`--resume`) | `-m` |
| `hermes` | Hermes | `hermes` | Yes (`--resume`) | `-m` |
| `kilo` | Kilo | `kilo` | Yes (`--session`) | `-m` |
| `qodercli` | Qoder | `qodercli` | Yes (`--resume`) | `--model` |
| `letta` | Letta | `letta` | Yes (`--conversation`) | `-m` |
| `mastracode` | Mastra Code | `mastracode` | Yes (`--thread`) | `--model` |
| `maki` | Maki | `maki` | Fresh launch | — |
| `muse` | Muse | `muse` | Fresh launch | — |
## Interactive takeover with canban card adopt
When you start exploring a `Backlog` Card in an interactive terminal or `@mention` session and decide to move ahead with implementation in that same conversation, the agent does not need to lose its context or spawn a duplicate session:
```sh
"$CANBAN_CLI" card update --file "$CANBAN_RUN_DIR/card.md"
"$CANBAN_CLI" card adopt --stage develop
```
- `card adopt` automatically passes inherited `HC_TERMINAL_ID` and `HC_SESSION` context to `AppServer`.
- `AppServer` verifies the Core, machine, live PTY, Profile, and Card workspace, transitions the Card to `develop` (`reason: "agent_adopted_stage"`) without launching a second Agent, and binds the existing live PTY directly to the `WorkflowRun` step.
- When the agent later runs `canban report --state completed`, the workflow proceeds seamlessly to `Review` and `Queue Merge`.
## Injected canban CLI reference
Canban injects `CANBAN_CLI`, `CANBAN_ENDPOINT`, `CANBAN_HOME`, `CANBAN_CARD`, `CARD_ID`, `CANBAN_PROJECT`, `CANBAN_PROFILE_ID`, and `CANBAN_RUN_DIR` into every launched session:
```sh
# Inspect or update the current Card
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
"$CANBAN_CLI" card update [--title 'Updated title'] --file "$CANBAN_RUN_DIR/card.md"
# Report execution outcome (completed | backlog | blocked | failed | working)
"$CANBAN_CLI" report --state completed --message 'Summary' --file "$CANBAN_RUN_DIR/report.md"
# Reply to a follow-up question without ending the active task
"$CANBAN_CLI" reply --to --file "$CANBAN_RUN_DIR/reply.md"
# Stage local diff review comments without publishing directly to GitHub
"$CANBAN_CLI" review draft --file "$CANBAN_RUN_DIR/review_draft.json"
# Call any AppServer JSON-RPC method
"$CANBAN_CLI" call card.list '{"project_id":"","stage":"develop","limit":50}'
```
For the full command matrix, Agent-first `--fields` / `request_key` contract, and `--human` examples, see [Canban CLI, Agent Optimization & --human](/docs/cli/).
---
# Canban CLI, Agent Optimization & --human
> The `canban` binary (`crates/cli/src/main.rs`) talks to the exact same `AppServer` JSON-RPC authority as the native desktop UI. Its response contract is Agent-first by default to minimize context tokens, while `--human` makes the same commands comfortable to read and script interactively.
## Core CLI commands
Global options `--home ` (`CANBAN_HOME`), `--endpoint ` (`CANBAN_ENDPOINT`), `--human`, `--fields `, and `--full` work across subcommands:
| Command | Purpose |
| --- | --- |
| `canban snapshot`, `canban status` | Fetch full `app.snapshot` state or `herdr.status` runtime health. |
| `canban call ''` | Invoke any public `AppServer` JSON-RPC method (pass `@/path/to/params.json` for file payloads). |
| `canban card show`, `card update`, `card adopt` | Inspect the Card, update `--title` / `--file`, or adopt `--stage develop` onto the live PTY without spawning a duplicate Agent. |
| `canban report` | Report execution outcome (`--state`: `completed`, `backlog`, `blocked`, `failed`, `working`; `--message`, `--file`) for a Card or `--schedule-run-id`. |
| `canban reply` | Answer a follow-up question (`--to --file `) without ending the active task. |
| `canban bind-session` | Bind provider `--session-id ` onto the active Card, schedule run, merge batch, or configuration session. |
| `canban review draft`, `review clear` | Stage or discard local unpublished diff review JSON (`{ summary, verdict, comments }`) for the Card Diff UI. |
| `canban workflow sources`, `export`, `submit`, `set-default` | Manage SQLite-backed `workflow_sources` (`--project-id` or `--global`, `--check` dry-run, and global defaults). |
| `canban schedule` | `list`, `runs`, `create`, `trigger`, `toggle` (`--on` / `--off`), `delete`, and `artifact` for Global or Project cron workflows. |
| `canban worktree gc` | Clean up merged clean worktrees (`--merged-before 7d`, `--dry-run`, `--env-dirty`, `--fail-on-dirty`). |
| `canban batch report` | Report `_merge_queue` `@merger` resolution (`--state`, `--evict `). |
| `canban serve`, `pair`, `service` | Run headless `AppServer` (`--tailscale`, `--port 7680`, `--listen`), print `canban://` pairing URIs, or manage `systemd` / `launchd` services. |
| `canban skill`, `--skill`, `build-info` | Print bundled `SKILL.md` or immutable release build metadata without opening application data. |
## Agent-first optimizations
Canban designs its CLI and RPC layer (`crates/app-server/src/representation.rs`) specifically to prevent wasted tokens, stale writes, and fragile lifecycle heuristics:
- **Compact single-line JSON default**: Every query and mutation prints a single compact JSON line to stdout regardless of whether stdout is a terminal, and emits structured `{"error":{"message":...}}` on stderr with a non-zero exit code.
- **Server-side response shaping (`--fields` vs. `--full`)**: `card.show`, `card.get`, and `card.list` default to slim summaries (`id`, `number`, `title`, `stage`, `revision`), and writes return small `accepted` receipts without echoing Card bodies. Pass `--fields number,title,body,stage,revision` to project exact top-level `CARD_FIELDS` / `EVENT_FIELDS` on the server, or `--full` (`view: "full"`) for the complete business view. Invalid field names fail pre-dispatch validation before any mutation runs.
- **Bounded keyset pagination**: `card.list` (`limit` 1..500, default 50) uses an opaque `cursor` with `cursor_stale` / `cursor_scope_mismatch` guards; `timeline.list` filters `kinds` in SQL, normalizes comment text once into `body`, and exposes `next_cursor`, `last_sequence`, and `highwater`.
- **Zero-config environment injection**: Launched sessions automatically receive `CANBAN_CLI`, `CANBAN_ENDPOINT`, `CANBAN_HOME`, `CANBAN_CARD`, `CARD_ID`, `CANBAN_PROJECT`, `CANBAN_PROFILE_ID`, and `CANBAN_RUN_DIR` (plus `CANBAN_SCHEDULE_RUN_ID`, `CANBAN_SCHEDULE_ID`, and `CANBAN_BATCH_ID` when applicable), and infer `project_id` from the worktree CWD when omitted.
- **`request_key` idempotency & updater handoff**: Mutating CLI commands attach a `request_key` (or accept `--request-key` for safe retries, unaffected by `--fields` / `--full`). During live daemon restarts, `report`, `batch report`, and `reply` queue via `canban_updater::handoff` and emit `{"queued":true,"request_key":...}`.
- **Explicit `report --state` gates**: Terminal exit or idle never advances workflow steps; agents advance only by declaring `completed`, `blocked`, `failed`, `backlog`, or `working`.
- **Bundled `canban skill` (`SKILL.md`)**: `canban skill` / `canban --skill` prints the binary-locked `skills/canban/SKILL.md` instructions directly, while `AppServer::open` materializes `/skills/canban/SKILL.md`.
- **Local unpublished `review draft`**: `canban review draft --file "$CANBAN_RUN_DIR/review_draft.json"` stores inline review findings locally in SQLite so humans inspect and publish from the Diff UI rather than letting agents post directly to GitHub.
## Human usage (--human)
Humans can inspect, debug, and script the exact same CLI comfortably using the global `--human` flag. As verified in `crates/cli/src/main.rs` (`Output::encode`), `--human` **only** pretty-prints (`serde_json::to_string_pretty`) the response—it never triggers extra RPC fields or alters server-side selection:
```sh
# Pretty-print the full Board snapshot for inspection
canban --human snapshot
# Pretty-print only the selected Card fields (no wasted payload)
canban --human --fields number,title,stage card show
# Call any JSON-RPC method interactively with readable formatting
canban --human call project.list '{}'
# Combine with --card / --full or pipe compact JSON into jq
canban --human --full card show --card 42
canban call card.list '{"stage":"develop","limit":20}' | jq '.items[] | [.number, .title]'
```
Tip: Use `--home ` or `--endpoint ` alongside `--human` when inspecting an isolated development instance or remote socket.
## Bundled Canban Skill (canban skill)
Canban embeds a version-locked Agent Skill (`skills/canban/SKILL.md`, compiled into `canban_context::SKILL_MD` in `crates/context/src/lib.rs`) so any coding agent learns the exact CLI contract without Canban silently mutating user-global agent folders:
- **Zero-side-effect inspection & home materialization**: Running `canban skill` or `canban --skill` (`crates/cli/src/main.rs`) prints the compiled `SKILL.md` directly to stdout without opening SQLite or sockets. When `AppServer::open` starts (or `stage_remote` syncs a remote host), it atomically materializes `/skills/canban/SKILL.md` via `materialize_skill` whenever bytes differ—keeping user-global agent directories untouched.
- **Install or refresh into your agent**: In desktop **Agent Setup** and **Settings → Agents & Identities** (`crates/ui/src/agents_setup.rs`), Canban surfaces the `npx skills add` command for your active home, or you can write `canban skill` directly into any agent's `canban/SKILL.md` directory:
```sh
# Install or refresh from the materialized Canban home directory
npx skills add ~/.canban/skills --skill canban -g
# Or print and write the exact binary-locked skill file directly
canban skill > ~/.agents/skills/canban/SKILL.md
```
- **What the Skill teaches Agents**: Session preflight (`CANBAN_CLI` and `CANBAN_ENDPOINT` checks), keeping payloads in `$CANBAN_RUN_DIR` outside Git, slim `card show` and `card adopt`, explicit `report --state` completion gates, `reply --to` for live follow-ups, local unpublished `review draft`, `workflow submit --check`, and `worktree gc`.
---
# Remote Linux Hosts, Tailscale & SSH
> A single Canban.app desktop client connects simultaneously to your local Mac (`This Mac`) and one or more remote Linux or macOS `canband` hosts over Tailscale TCP or SSH.
## Simultaneous multi-host & offline-resilient execution
Each host runs a self-contained `canband` + local `herdr-core` (`hc`) pair owning its own SQLite WAL database, Projects, Cards, Workflows, Scheduler, and Git worktrees:
- **24/7 Autonomous Progression**: When your laptop sleeps or goes offline, remote `canband` hosts keep running agents, collecting reports, executing FIFO Queue Merge, and polling linked GitHub repositories.
- **Unified Board & Notifications**: `Canban.app` merges local and remote Projects into one `HostRegistry`, routing operations by owning `host_id` and surfacing remote `Needs you` / `Updates` items in `⌘I`.
- **Offline Snapshot Cache**: Successful remote snapshots are cached under `/cache/hosts/.json`. If Tailscale disconnects, remote boards remain inspectable in `Offline · Cached` read-only mode.
## Installing headless Linux canband
On headless Linux (`x86_64` or `aarch64`) servers without a desktop session, install standalone `canban` (no GTK4 or GStreamer required) and register a persistent `systemd --user` service:
```sh
curl -fsSL https://canban.dev/install.sh | bash -s -- --headless
canban service install --tailscale --port 7680
canban service status
```
`canban service install` enables `loginctl enable-linger` when available so user services and active `herdr-core` PTYs persist across logouts.
## Tailscale direct TCP vs. SSH pairing
Canban uses a Tailscale-first direct data plane with SSH bootstrap and fallback:
- **Tailscale Direct TCP (Recommended)**: `canban serve --tailscale` binds the host's Tailscale IPv4 (`100.64.0.0/10`, default port `7680`) and persists settings in `/config/server.json`. A 256-bit Bearer secret is stored in `/server.token` (`0600`). Pre-auth `host.probe` exposes only non-sensitive identity (`server_id`, `hostname`, `platform`, `version`, `api_version`), while all RPCs and `herdr.connect` PTY streams authenticate against `server.token`.
- **Pairing URI**: Run `canban pair [--port 7680]` on the remote host to print a copyable `canban://:#` URI, or use the desktop **Connect a Machine** wizard to discover Tailscale peers (`tailscale status --json`) and auto-pair or bootstrap over SSH.
- **Managed SSH Tunnel Fallback**: For pure-SSH hosts without Tailscale, `Canban.app` manages a background `ssh -L` Unix-socket forwarder into a mode-`0600` local socket directory.
## Built-in Diagnostics & remote daemon upgrades
Open **Settings → Diagnostics** to verify and repair local or remote hosts end to end:
- **Transport & Latency**: Socket, Tailscale TCP, or SSH tunnel state, RTT (`ms`), and reconnect history.
- **Canban Service & Storage**: Daemon PID, platform, version, `DESKTOP_API` compatibility, `systemd --user` / `launchd` state, and SQLite DB/WAL sizes.
- **Herdr & Toolchain**: Resolved `hc` binary, Core ID, active PTY count, `git`, `python3`, `tailscale`, and resolved paths for enabled Agent profiles.
- **Live Logs & Updates**: Stream `server.log` and `updater.log`, or trigger a remote `update.daemon` directly from the UI when `ApiMismatch` is detected.
---
## Agent CLI Skill Reference (`skills/canban/SKILL.md`)
# Canban CLI Skill
Canban injects `CANBAN_CLI` and task environment variables when launching an Agent session on a Card or Project. Use `"$CANBAN_CLI"` for all Canban mutations and queries.
## Guardrails
1. **Check environment first**: Before running Card-scoped commands, verify Canban injected a live session:
```sh
test -n "${CANBAN_CLI:-}" && test -n "${CANBAN_ENDPOINT:-}"
```
If unset, you are outside a Canban-launched session (or pass `--home` / `--endpoint` explicitly when the user asks).
2. **Always use current environment variables**: Use `"$CANBAN_CLI"`, `"$CANBAN_ENDPOINT"`, `"$CANBAN_CARD"`, `"$CANBAN_PROJECT"`, and `"$CANBAN_RUN_DIR"` from the current process environment. Never copy stale `CANBAN_CARD` or `CANBAN_PROJECT` values from earlier conversation turns.
3. **Never touch storage directly**: Never read or edit `canban.sqlite` directly, and do not archive Cards unless explicitly asked.
4. **Keep scratch and Markdown payloads outside Git**: Write report, reply, and Card body files under `"${CANBAN_RUN_DIR:-/tmp}"` (for example `"$CANBAN_RUN_DIR/report.md"`), never inside the repository worktree.
## Injected Environment
| Variable | Purpose |
| --- | --- |
| `CANBAN_CLI` | Absolute path to the matching `canban` executable (or remote bridge wrapper). |
| `CANBAN_ENDPOINT` | AppServer Unix socket path (or `spool:...` on remote execution hosts). |
| `CANBAN_HOME` | Active Canban application home directory. |
| `CANBAN_CARD` | Short Card number (for example `42`), injected into both scheduled Agent runs and manual Card Terminals. |
| `CARD_ID` | Internal Card ID, injected alongside `CANBAN_CARD` in both scheduled Agent runs and manual Card Terminals. |
| `CANBAN_PROJECT` | Active Project ID (CLI commands also infer the Project from a git repository or Card worktree CWD when omitted). |
| `CANBAN_RUN_DIR` | Scratch directory outside the repository worktree for Markdown payloads. |
| `CANBAN_PROFILE_ID` | Active `@identity` or Agent profile ID (when applicable). |
| `CANBAN_SCHEDULE_RUN_ID` | Scheduled run ID (`scheduled::`), injected into Cardless scheduled Terminal Agent runs. |
| `CANBAN_SCHEDULE_ID` | Parent schedule state ID (`schedule:::`), injected into Cardless scheduled runs. |
## Core Execution Commands
### Report task or comment outcome
```sh
"$CANBAN_CLI" report \
--state \
--message 'Concise one-line summary' \
[--file "$CANBAN_RUN_DIR/report.md"]
```
- `completed`: Deliverable work or dedicated `@mention` comment task is finished. For code tasks, stage and `git commit` deliverable changes on the Card branch before reporting `completed` (do not `git push` unless instructed).
- `blocked`: Waiting on human clarification, credentials, or a design decision.
- `backlog`: Card is already implemented, obsolete, or not actionable right now; returns the Card to Backlog with your explanation.
- `failed`: Unrecoverable execution error.
- `working`: Optional interim progress update without finishing the assignment.
> **Interactive sessions vs. comment tasks**:
> - In an **interactive Card session**, reply directly in the terminal for initial discussion; only run `report` once the user asks you to complete a concrete task.
> - In a **dedicated `@mention` comment assignment**, publish your answer and finish in a single `report --state completed` call (do not call `reply` separately).
### Report batch merge queue outcome (`batch report`)
When running in a project `_merge_queue` batch `@merger` session (`CANBAN_BATCH_ID` is injected):
```sh
"$CANBAN_CLI" batch report \
--state \
--message 'Concise summary of batch resolution' \
[--evict ...] \
[--file "$CANBAN_RUN_DIR/report.md"]
```
- Do not `git push` or modify the main checkout directly; Canban fast-forwards and pushes once on `completed`.
- Use repeatable `--evict ` only if you rebuilt `_merge_queue` cleanly from `refs/canban/batch//target` without those broken Card(s) and verified tests on the remaining Cards.
### Answer a live follow-up question (`reply`)
When a human posts a follow-up question with a Question ID against an already running non-comment task, answer that question without ending your main task:
```sh
"$CANBAN_CLI" reply --to --file "$CANBAN_RUN_DIR/reply.md"
```
### Inspect or update the current Card (`card show` / `card update`)
Read the current Card summary (uses `CANBAN_CARD` + `CANBAN_PROJECT` automatically, or pass `--card `):
```sh
"$CANBAN_CLI" card show
# Request task text explicitly when it is not already in the session context.
"$CANBAN_CLI" card show --fields number,title,body,stage,revision
```
Update the Card title or Markdown description only with user-confirmed design decisions or when explicitly requested:
```sh
"$CANBAN_CLI" card update [--title 'Updated title'] --file "$CANBAN_RUN_DIR/card.md"
```
### Adopt a workflow stage (`card adopt`)
In an interactive session on a Card not yet in `develop`, once the user authorizes implementation, adopt `develop` first so the current session takes over without spawning a duplicate scheduled run:
```sh
"$CANBAN_CLI" card adopt --stage develop
```
### Stage local diff review comments (`review draft`)
When reviewing a Card or GitHub PR, write line-specific findings and an overall summary as a **local unpublished review draft** (never publish directly to GitHub) so a human can inspect, edit, or publish them from the local Diff UI:
```sh
"$CANBAN_CLI" review draft --file "$CANBAN_RUN_DIR/review_draft.json"
```
Expected JSON schema for `review_draft.json`:
```json
{
"summary": "Overall review summary...",
"verdict": "comment",
"comments": [
{
"path": "crates/scheduler/src/lib.rs",
"line": 86,
"side": "RIGHT",
"snippet": "let _ = self.reconcile_slots();",
"body": "Explain the issue and suggested fix..."
}
]
}
```
- `verdict`: `"comment"` (default), `"approve"`, or `"request_changes"`.
- `side`: `"RIGHT"` (added or context line on the new file) or `"LEFT"` (deleted line on the old file).
- Use `"$CANBAN_CLI" review clear` to discard the local review draft for the current Card if needed.
## Efficient RPC and CLI use
- RPC and CLI default to compact Agent-facing summaries and mutation receipts.
`--human` pretty-prints the same JSON; it does not expand content.
- Use `--fields number,title,body,stage,revision` (RPC `fields` array) when task
text is needed. Use `--full` (RPC `view:"full"`) only for a complete business
view. Fields/full are mutually exclusive; fields are explicit top-level names.
- Reuse injected task text and existing query data. If the needed fields are
already known, request them together rather than summary then detail.
- Inventory with `card.list` and a stage filter. Read `items`, follow every
`next_cursor` to null, and handle `cursor_stale` by restarting and deduplicating
IDs. The default limit is 50; the maximum is 500. Do not routinely send full
project lists or snapshots into model context.
- Check discussions with `timeline.list`, `kinds:["comment.created","comment.updated"]`
and `after_sequence`. Follow next_cursor, then save last_sequence even after
an empty filtered result. Comment read text appears once as `body`.
- `event.list` instead filters after paging: continue its global cursor to
highwater even after an empty page. Do not confuse the two cursor contracts.
- Accepted write receipts normally suffice; do not read back full objects just
to confirm the write. Verify business outcomes or ambiguous/queued results
specifically. Preserve revision checks on concurrent writes.
- Write long payloads through `call METHOD @params.json`, explicitly set comment
`mentions:[]` unless dispatch is intended, and reuse a stable request_key when
retrying. Changing only fields/full does not change the write's identity.
- `canban skill` is the current binary's bundled skill; refresh installed copies
when upgrading. Old RPC defaults are not a compatibility contract.
## Inspecting State & Calling AppServer RPCs
Inspect overall state or runtime health:
```sh
"$CANBAN_CLI" snapshot
"$CANBAN_CLI" status
"$CANBAN_CLI" --help
```
Call any public AppServer JSON-RPC method via `"$CANBAN_CLI" call ''` (or `@/path/to/params.json`):
```sh
# List Projects or Cards
"$CANBAN_CLI" call project.list '{}'
"$CANBAN_CLI" call card.list '{"project_id":"","stage":"backlog","limit":50}'
# Read a Card, its Timeline events, or Diff preview
"$CANBAN_CLI" call card.get '{"card":,"project_id":"","fields":["number","title","body","stage","revision"]}'
"$CANBAN_CLI" call timeline.list '{"card":,"project_id":"","kinds":["comment.created","comment.updated"],"after_sequence":0,"limit":50}'
"$CANBAN_CLI" call review.preview '{"card":,"project_id":""}'
# Post a Card comment (supports @profile mentions to schedule another role)
"$CANBAN_CLI" call comment.add '{"card":,"project_id":"","body":"Ready for @reviewer","mentions":["reviewer"],"request_key":"review-request-unique"}'
# Create a follow-up Card in Backlog
"$CANBAN_CLI" call card.create '{"project_id":"","title":"Follow-up task","body":"Details..."}'
# Inspect the Card's Agent terminals or captured terminal output
"$CANBAN_CLI" call execution.get '{"card":,"project_id":""}'
"$CANBAN_CLI" call execution.output '{"terminal_id":""}'
```
## Authoring Workflows (CLI)
When asked to inspect or update a Project's or Global (`__global`) Workflow YAML (`workflow.sources` is stored in SQLite, not Git files):
```sh
# Project-scoped workflow collection
"$CANBAN_CLI" workflow sources --project-id
"$CANBAN_CLI" workflow export --project-id --name development.yaml --output "$CANBAN_RUN_DIR/development.yaml"
"$CANBAN_CLI" workflow submit --project-id --revision --file "$CANBAN_RUN_DIR/development.yaml" --check
"$CANBAN_CLI" workflow submit --project-id --revision --file "$CANBAN_RUN_DIR/development.yaml"
# Global host-level workflow collection (`scope: global`, no Board columns or Cards)
"$CANBAN_CLI" workflow sources --global
"$CANBAN_CLI" workflow export --global --name cleanup.yaml --output "$CANBAN_RUN_DIR/cleanup.yaml"
"$CANBAN_CLI" workflow submit --global --revision --file "$CANBAN_RUN_DIR/cleanup.yaml"
```
## Scheduled Workflows (Cron Tasks)
Workflows support GitHub Actions-style cron triggers (`schema: 9`) across two scopes:
- **`scope: global`** (`project_id: __global`): Host-level schedules without Board columns or `card:` creation rules (ideal for maintenance, cleanup, cross-project checks).
- **`scope: project`** (default): Project-scoped schedules running in either **Cardless Script/Agent mode** or **Card-creating mode** (`card:`).
Missed ticks while Canban was offline or asleep are skipped rather than replayed on wakeup.
### 1. Script-First + On-Failure Agent Escalation (Lazy Admission)
Scheduled workflows starting with `uses: script` (or top-level `run:` shorthand) run with **zero PTY and zero `scheduler.max_agents` slot overhead** when they succeed (`exit 0`). Only when `on_failure` transitions into an `uses: agent` step does Canban allocate a `TerminalEntry` and an Agent slot, handing off the failed step's exit code and stderr/stdout tail in the prompt.
If that recovery Agent calls `"$CANBAN_CLI" report --state blocked --message "..."`, its **live PTY stays open** (never auto-reclaimed) and surfaces in **Activity & Notifications (`⌘I`) → Needs you** so a human can inspect or reply directly in the terminal. Reporting `completed` or `failed` reclaims the PTY after the turn settles.
```yaml
schema: 9
scope: global
id: global:worktree_gc
name: Worktree GC (7d)
on:
schedule:
- cron: "0 3 * * *"
timezone: Local
overlap: skip # skip (default) | queue | allow
steps:
- id: gc
run: |
"$CANBAN_CLI" worktree gc --merged-before 7d --fail-on-dirty --env-dirty DIRTY_WORKTREES
on_failure: ask_agent
next: finish
- id: ask_agent
uses: agent
with:
profile: developer
instruction: |
Worktree cleanup found dirty or active worktrees ($DIRTY_WORKTREES).
Inspect the affected paths and call `$CANBAN_CLI report --state blocked --message "..."`
if human input is required, or clean safe items and report `--state completed`.
next: finish
- id: finish
uses: complete
```
Inside a Cardless scheduled Agent (`CANBAN_SCHEDULE_RUN_ID` is injected, `CANBAN_CARD` is unset; Global runs inject `CANBAN_SCOPE=global`), report your outcome with:
```sh
"$CANBAN_CLI" report \
--state \
--message 'Concise summary of scheduled run' \
[--file "$CANBAN_RUN_DIR/report.md"]
```
### 2. Card-Creating Mode (`scope: project` with `card:`)
Creates a Card on each trigger with `schedule_source` provenance (`Scheduled · #` badge on Board and Card Detail) and runs the workflow's step graph against that Card so execution logs, reports, and diffs attach to its Timeline:
```yaml
schema: 9
id: nightly_qa:example
name: Nightly QA
on:
nightly:
cron: "30 3 * * 1-5"
timezone: UTC
overlap: skip
start_at: run_qa
card:
column: develop
title: "Nightly QA ({{date}} #{{run_number}})"
body: "Automated scheduled check for {{workflow}} ({{datetime}})."
steps:
- id: run_qa
uses: agent
with:
profile: developer
instruction: Run full integration suite and fix or report regressions.
next: finish
- id: finish
uses: complete
```
Supported placeholders in `card.title` / `card.body`: `{{date}}`, `{{datetime}}`, `{{run_number}}`, `{{workflow}}`, `{{rule}}`. Supported `timezone` values: `Local` (default), `UTC`, fixed offsets (`+08:00`), or standard IANA names (`Asia/Shanghai`, `America/New_York`, `Europe/London`, `Asia/Tokyo`, etc.).
### 3. Operating Schedules & Worktree GC via CLI
```sh
# List schedules and recent runs (all scopes, --global, or --project-id)
"$CANBAN_CLI" schedule list
"$CANBAN_CLI" schedule list --global
"$CANBAN_CLI" schedule runs --global [--schedule-id ] [--limit 20]
# Create a Global or Project scheduled workflow directly
"$CANBAN_CLI" schedule create --global --name "Worktree GC" --cron "0 3 * * *" \
--mode script_agent --script '"$CANBAN_CLI" worktree gc --merged-before 7d --fail-on-dirty --env-dirty DIRTY_WORKTREES' \
--profile-id developer --instruction "Inspect dirty worktrees and ask the user with --state blocked if needed."
# Manually trigger ("Run now"), toggle, or delete a schedule
"$CANBAN_CLI" schedule trigger --schedule-id
"$CANBAN_CLI" schedule toggle --schedule-id --off
"$CANBAN_CLI" schedule toggle --schedule-id --on
"$CANBAN_CLI" schedule delete --schedule-id
# Read a finished Cardless run's script log or report
"$CANBAN_CLI" schedule artifact --schedule-run-id --path
# Garbage-collect merged clean worktrees older than a retention window
"$CANBAN_CLI" worktree gc --merged-before 7d [--project-id ] [--dry-run] [--fail-on-dirty] [--env-dirty DIRTY_WORKTREES]
```
---
## Recent Published Releases
- **20261119-1** (2026-11-19): https://github.com/jjyr/canban/releases/tag/20261119-1
- **20261118-1** (2026-11-17): https://github.com/jjyr/canban/releases/tag/20261118-1
- **20261116-7** (2026-11-16): https://github.com/jjyr/canban/releases/tag/20261116-7
- **20261116-6** (2026-11-16): https://github.com/jjyr/canban/releases/tag/20261116-6
- **20261116-5** (2026-11-16): https://github.com/jjyr/canban/releases/tag/20261116-5