kardbrd-agent

kardbrd

Single Go binary for Kardbrd board automation and CLI access. kardbrd agent ... runs the coding-agent daemon, while opt-in kardbrd worker ... runs a separate durable personal-operations worker. Every other command is the Kardbrd client CLI.

Prerequisites

• Go 1.24+ to build from source
• git
• One executor CLI for agent work:
  • Claude CLI (claude) - default executor
  • Goose (goose)
  • Codex CLI (codex)
  • Pi (pi)

Build

git clone https://github.com/Kardbrd/kardbrd-agent.git
cd kardbrd-agent
go build -o kardbrd ./cmd/kardbrd

Quick Start

export KARDBRD_API_URL=https://app.kardbrd.com
export KARDBRD_TOKEN=<bot-token>
export KARDBRD_AGENT_BOARD_ID=<board-id>
export KARDBRD_AGENT_NAME=<agent-name>
export KARDBRD_AGENT_CWD=/path/to/your/repo
export ANTHROPIC_API_KEY=<api-key>
# For Codex executor:
# export OPENAI_API_KEY=<api-key>

./kardbrd agent start

Equivalent flags:

./kardbrd --token <bot-token> agent start \
  --board-id <board-id> \
  --name <agent-name> \
  --cwd /path/to/your/repo

Commands

Personal worker

The worker is disabled unless explicitly invoked. It uses versioned ops card metadata, server revision-CAS claims, bounded trusted subprocess adapters, and durable receipts. It has no Gmail, Calendar, browser, or built-in notification connector and does not change the coding-agent lifecycle. See the personal worker guide for safe fixture setup, operator activation, and rollback.

Label updates

Use board-detail label discovery, then provide the complete desired label set with repeated flags:

kardbrd board labels BOARD_ID
kardbrd card update CARD_ID --label-ids LABEL_A --label-ids LABEL_B
kardbrd card update CARD_ID --clear-labels

--label is an alias for --label-ids; both are repeatable and perform a full replacement. The CLI validates requested IDs before mutations, adds before removing, and returns the refreshed card. --clear-labels is the explicit empty replacement and cannot be combined with either label flag. When scalar fields and labels are changed together, server endpoints make the operation non-atomic; a reported reconciliation failure is safe to retry with the same full set.

Card metadata

Cards support arbitrary JSON metadata without a fixed set of keys or value types. The root is an object; values may be strings, numbers, booleans, null, arrays or nested objects. These commands work independently of kardbrd agent:

kardbrd card metadata get CARD_ID
kardbrd card metadata get CARD_ID ops.status
kardbrd card metadata set CARD_ID ops.status '"waiting_external"'
kardbrd card metadata set CARD_ID attempts 2
kardbrd card metadata set CARD_ID result null
kardbrd card metadata remove CARD_ID result
kardbrd card metadata update CARD_ID --set '{"ops.status":"ready","attempts":3}' --remove old_key --if-revision 7
kardbrd card metadata update CARD_ID --set-file metadata.json

Keys are literal: ops.status is one key, not a nested path. Setting a nested object replaces that key's complete value. Other keys are preserved. Use --set-file - to read an object from stdin; repeat --remove for multiple keys. Null is stored as a value and never implicitly deletes a key. Results are JSON.

Reads return metadata and metadata_revision. Writes require the revision on which the change is based. Without --if-revision, the CLI fetches it once before writing. For coordinated work, pass the revision from the read that informed your decision. A conflict fails with METADATA_CONFLICT (HTTP 409); the CLI does not fetch a new revision and blindly retry. Inspect the current state before deciding whether to try again, especially after an interrupted response.

The server changes keys, advances the revision, and records activity in one transaction. Every successful write advances the revision, including setting an existing value or removing an absent key. Metadata also appears in card detail, board JSON and card Markdown responses. This requires the Django metadata API and migration; an older server returns an error rather than accepting the write.

CLI output formats

Collection reads such as kardbrd board list now default to TSV with headers. Add --no-headers for headerless TSV, --format json for the lossless indented JSON response, or --format md for a Markdown table. Output formats apply only to client commands; agent commands reject --format.

kardbrd board list
kardbrd --format json board list
kardbrd board list --format md

Agent Configuration

Legacy names such as KARDBRD_ID, KARDBRD_AGENT, KARDBRD_URL, and AGENT_* are rejected with explicit rename messages.

Rules

For the opt-in verified Git lifecycle, exact card commands, and administrative adoption, see Portable worktree lifecycle.

Create kardbrd.yml in the target repository:

board_id: 0gl5MlBZ
agent: MyBot
executor: codex

rules:
  - name: Explore new ideas
    event: card_created
    list: Ideas
    model: sonnet
    action: /ke

  - name: Stop on red flag
    event: reaction_added
    emoji: "🛑"
    action: __stop__

Validate it:

kardbrd agent validate
kardbrd agent validate path/to/kardbrd.yml

Docker

docker build -t kardbrd .
docker run --rm \
  -e KARDBRD_API_URL=https://app.kardbrd.com \
  -e KARDBRD_TOKEN=<bot-token> \
  -e KARDBRD_AGENT_BOARD_ID=<board-id> \
  -e KARDBRD_AGENT_NAME=<agent-name> \
  -e KARDBRD_AGENT_CWD=/home/agent/repository \
  -e ANTHROPIC_API_KEY=<api-key> \
  -e OPENAI_API_KEY=<api-key> \
  -v ./repository:/home/agent/repository \
  -v ./workspaces:/home/agent/workspaces \
  -v ./codex:/home/agent/.codex \
  kardbrd

The Docker image includes Go, the official GitHub CLI, Codex, and pre-commit for agent delivery work. Python support is included only for pre-commit; uv is not installed.

Development

go test ./...
go run ./cmd/kardbrd --help
go run ./cmd/kardbrd agent --help