NAME

karr - Kanban Assignment & Responsibility Registry

VERSION

version 0.600

SYNOPSIS

karr init --name "My Project"
karr create "Fix login bug" --priority high
karr move 1 in-progress --claim swift-fox
karr board
karr backup > karr-backup.yml

DESCRIPTION

karr is the primary command line interface for App::karr. It manages a Git-native kanban board whose canonical state lives in refs/karr/*, plus optional helper payloads in non-protected refs outside that namespace.

Run it from inside a Git repository. Commands discover the repository root, pull the current board refs, and read and write task cards directly against those refs -- no board files ever touch the work tree for an ordinary command. karr materialize and karr import are the two bridge commands that write and read a disposable, gitignored tasks/ plus config.yml view instead, for kanban-md interop and for grepping the board as files.

The script is the best starting point when you want to understand the CLI as a user. For architecture notes, Docker background, and Perl-facing examples, see App::karr.

CLI WORKFLOW

A typical session looks like this:

1. Create the board once with App::karr::Cmd::Init.

2. Add and inspect tasks with App::karr::Cmd::Create, App::karr::Cmd::List, App::karr::Cmd::Show, and App::karr::Cmd::Board.

3. Progress work with App::karr::Cmd::Move, App::karr::Cmd::Edit, App::karr::Cmd::Pick, and App::karr::Cmd::Handoff.

4. Export, restore, or remove board state with App::karr::Cmd::Backup, App::karr::Cmd::Restore, and App::karr::Cmd::Destroy.

COMMANDS

Board Setup And Configuration

• App::karr::Cmd::Init

  Creates the initial board in refs/karr/* and can install the bundled project skill for Claude Code.

• App::karr::Cmd::Config

  Shows or updates writable board settings such as the board name, defaults, and claim timeout.

• App::karr::Cmd::Disable

  Turns off automated agent runs for this board (karr-foundation), optionally recording a reason. The flag lives in refs/karr/config and syncs with the board.

• App::karr::Cmd::Enable

  Turns automated agent runs back on.

• App::karr::Cmd::Context

  Generates a compact board summary for embedding into files such as AGENTS.md.

• App::karr::Cmd::Skill

  Installs, checks, updates, or prints the bundled skill file for Claude Code, Codex, and Cursor.

Task Lifecycle

• App::karr::Cmd::Create

  Creates a new task card.

• App::karr::Cmd::List

  Lists tasks with filters for status, priority, tags, claims, and text search.

• App::karr::Cmd::Show

  Shows the full task document for one task id.

• App::karr::Cmd::Edit

  Updates task metadata, body text, claims, and blocked state.

• App::karr::Cmd::Move

  Moves tasks between statuses, including relative moves with --next and --prev.

• App::karr::Cmd::Delete

  Deletes task refs permanently.

• App::karr::Cmd::Archive

  Soft-deletes tasks by moving them to the archived status.

Board Flow And Coordination

• App::karr::Cmd::Board

  Shows the grouped board view.

• App::karr::Cmd::Pick

  Finds the next suitable task and claims it for an agent.

• App::karr::Cmd::Unlock

  Shows the pick locks currently held on the board, and breaks them. The escape hatch for a lock left behind by an agent that died mid-pick.

• App::karr::Cmd::Handoff

  Moves work into review and optionally appends a timestamped note.

• App::karr::Cmd::Log

  Prints activity log entries from refs/karr/log/*.

• App::karr::Cmd::Metrics

  Reports flow metrics -- throughput, lead/cycle time, flow efficiency, and aging work -- derived from each task's lifecycle stamps.

• App::karr::Cmd::Needs

  Reports, and optionally resolves, the cross-board dependencies recorded with karr create --needs / --escalated-from and karr edit --add-needs.

• App::karr::Cmd::AgentName

  Generates short random agent names for multi-agent workflows.

• App::karr::Cmd::Sync

  Explicitly pulls or pushes refs/karr/* when you want to inspect or control sync separately.

Snapshot And Recovery

• App::karr::Cmd::Backup

  Exports the entire refs/karr/* namespace as YAML.

• App::karr::Cmd::Restore

  Replaces the current board refs from a YAML snapshot. This is intentionally destructive and requires explicit confirmation flags.

• App::karr::Cmd::Destroy

  Deletes the whole board namespace from the repository.

• App::karr::Cmd::Repair

  Migrates a board off two old karr-writing bugs: double-encoded UTF-8 (boards written by karr 0.402 or earlier) and started stamps that precede their own card's created (pre-#68 bare-date stamps). Reports by default; --yes rewrites the affected refs. Idempotent, and a no-op on a board that is already current.

• App::karr::Cmd::Materialize

  Writes the current refs/karr/* board out as a tasks/ file view -- a bridge for kanban-md interop and grepping task files, not a storage backend.

• App::karr::Cmd::Import

  Reads a materialized tasks/ file view back into refs/karr/*, the reverse of Materialize.

Helper Refs

• App::karr::Cmd::SetRefs

  Stores arbitrary helper payloads in allowed refs outside protected namespaces.

• App::karr::Cmd::GetRefs

  Fetches one helper ref and prints only its payload to standard output.

EXIT CODES

karr's primary callers are agents scripting the CLI, for whom $? is part of the interface. The exit code is therefore a stable contract (see docs/adr/0002-exit-code-contract.md):

• 0 -- success, including no-op successes such as re-archiving a task that is already archived.

• 1 -- runtime failure: a task id was not found, the board is missing, a Git or sync operation failed, a destructive command was refused for want of --yes, or a batch committed partial work but at least one item failed.

• 2 -- usage error: an unknown command, an unknown option, an invalid option value, or a surplus or missing positional argument.

The 1-versus-2 split is what lets a scripting agent tell "I called this wrong" apart from "the operation failed". This deviates deliberately from kanban-md, which exits 1 for everything.

DOCKER USAGE

The CLI works well through the published Docker image. A common alias is:

alias karr='docker run --rm -it -w /work -e HOME=/home/karr \
  -v "$(pwd):/work" \
  -v "$HOME/.gitconfig:/home/karr/.gitconfig:ro" \
  -v "$HOME/.claude:/home/karr/.claude" \
  -v "$HOME/.codex:/home/karr/.codex" \
  raudssus/karr:latest'

That keeps the current repository mounted at /work and lets the default image adapt its runtime uid and gid to the owner of the mounted workspace. The CLI syntax stays the same after that:

karr board
karr skill install --agent codex --global --force

If you prefer a fixed non-root runtime, use raudssus/karr:user instead. That image defaults to uid and gid 1000:1000 and is intended as the predictable base for downstream custom images. Custom fixed-user derivatives can override KARR_UID and KARR_GID at build time.

EXAMPLES

Initialize a new board and install the project-local Claude Code skill:

karr init --name "HandyIntelligence Prototype" --claude-skill

Claim and start the next task for a generated agent:

NAME=$(karr agentname)
karr pick --claim "$NAME" --move in-progress

Export the board before trying a destructive restore:

karr backup > karr-backup.yml
karr restore --yes < karr-backup.yml

SEE ALSO

App::karr, App::karr::Task, App::karr::BoardStore, App::karr::Git, App::karr::Cmd::Init, App::karr::Cmd::Skill, App::karr::Cmd::Backup, App::karr::Cmd::Restore

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

cpanm App::karr

perl -MCPAN -e shell
install App::karr