/ 
App-karr-0.400
/ App::karr

NAME

App::karr - Kanban Assignment & Responsibility Registry

VERSION

version 0.400

SYNOPSIS

karr init --name "My Project"
karr create "Fix login bug" --priority high
karr list --status todo,in-progress
karr board
karr set-refs superpowers/spec/1234.md draft ready
karr get-refs superpowers/spec/1234.md

DESCRIPTION

App::karr is the central module behind the karr command line client. The distribution manages a Git-native kanban board stored in refs/karr/*, where task cards are Markdown payloads and board configuration is sparse YAML kept in refs rather than in checked-in work tree files.

The distribution is intended for repositories that want Git to remain the transport and source of truth. Commands materialize a temporary board view only for the lifetime of a command, then serialize changes back into refs and push them onward. This keeps the repository free of a persistent karr/ board tree and avoids ordinary file-level merge conflicts for shared task state.

This module gives the architectural overview. If you want day-to-day command usage, command groups, and command-by-command navigation, start with karr.

ARCHITECTURE

  • refs/karr/config

    Sparse board configuration overrides layered onto code defaults from App::karr::Config.

  • refs/karr/meta/next-id

    Dedicated metadata ref for numeric id allocation.

  • refs/karr/tasks/*/data

    Task payloads stored in the same Markdown plus YAML frontmatter shape used by App::karr::Task.

  • refs/karr/log/*

    Append-style activity log entries written as per-agent JSON lines.

App::karr::Git provides the low-level Git ref operations, while App::karr::BoardStore handles the higher-level board model: merged config, task loading, materialization, serialization, snapshots, and restore.

CLI ENTRY POINT

The installed executable is karr. Running karr without a subcommand shows the board summary by default, and the command-specific modules under App::karr::Cmd::* implement the individual operations.

Use karr when you want to learn:

  • which command to run for a task

  • how backup, restore, destroy, and helper refs fit together

  • which module implements each subcommand

  • how to use the Docker-wrapped CLI day to day

DOCKER RUNTIME

Perl installation remains the normal development path, but Docker is a first-class runtime option for vendoring karr into other repositories or tooling environments.

The default raudssus/karr:latest image starts as root only long enough to inspect the mounted /work directory and then drops to the matching numeric uid and gid before running karr. This prevents root-owned project files when the image is used through a shell alias. The companion raudssus/karr:user image is the fixed-user variant for environments that prefer a predictable non-root runtime without that auto-adjustment.

See karr and README.md for the shell alias form and operator-focused examples.

PROGRAMMATIC USAGE

Although the distribution is centered on the CLI, the lower-level modules are usable from Perl when you want to inspect or manipulate board refs directly.

Reading the current board state:

use App::karr::Git;
use App::karr::BoardStore;

my $git = App::karr::Git->new(dir => '.');
my $store = App::karr::BoardStore->new(git => $git);

my $config = $store->load_config;
my @tasks  = $store->load_tasks;

Creating a task and writing it back:

use App::karr::Task;

my $id = $store->allocate_next_id;
my $task = App::karr::Task->new(
  id       => $id,
  title    => 'Document the release process',
  status   => 'backlog',
  priority => 'high',
);

$store->save_task($task);
$git->push;

Taking a full board snapshot for export logic:

my $snapshot = $store->snapshot;

These modules are more appropriate for Perl automation than instantiating App::karr itself, which mainly exists as the MooX::Cmd dispatcher for the CLI.

BOARD DISCOVERY

Most commands automatically search upward from the current directory for a Git repository that contains refs/karr/*. The --dir option overrides the starting directory used for that repository discovery and is accepted in either position: before the subcommand (karr --dir PATH list) or on the subcommand itself (karr list --dir PATH). Both forms behave identically. The upward walk still applies from the given path, so --dir names any directory inside the target repository, not necessarily its root. If no Git repository is found from the given path, the command fails loudly rather than falling back to the current directory.

DEFAULT BEHAVIOUR

Running karr without a subcommand shows the board summary, which makes the tool convenient as a quick project status command.

SEE ALSO

karr, App::karr::Git, App::karr::BoardStore, App::karr::Task, App::karr::Config, App::karr::Cmd::Init, App::karr::Cmd::Skill

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; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.