/ 
App-karr-0.601
/ App::karr::Cmd::AgentName

NAME

App::karr::Cmd::AgentName - Print a claim name derived from the checkout directory

VERSION

version 0.601

SYNOPSIS

# The claim name for this checkout -- stable, so every call agrees:
karr agent-name                 # -> karr, graphify-fix, wt1, ...

# Export it once; every nested karr call in the session claims as it:
export KARR_CLAIM=$(karr agent-name)
karr pick --move in-progress
karr handoff 7 --note "Implementation complete"

# Several agents in ONE directory: a random suffix keeps them apart.
export KARR_CLAIM=$(karr agent-name --unique)   # -> karr-8fa

DESCRIPTION

Prints a claim-safe name for the current checkout: the worktree root's directory name, lowercased with every run of non-[a-z0-9] characters folded to a single - and the ends trimmed. The agent working the karr checkout is karr; the one in a worktree at .../graphify-fix is graphify-fix. The source is the worktree root (libgit2's workdir, what git rev-parse --show-toplevel reports), so it does not matter which subdirectory the command runs in; outside a work tree it falls back to the current directory's basename.

ADR 0005 makes this the value KARR_CLAIM carries. Every command that takes --claim (App::karr::Cmd::Move, App::karr::Cmd::Handoff, App::karr::Cmd::Pick, App::karr::Cmd::Edit, App::karr::Cmd::Create) and karr list --claimed-by defaults to $KARR_CLAIM when the flag is omitted, so the recommended shape is to export it once per session:

export KARR_CLAIM=$(karr agent-name)

rather than passing --claim NAME on every call. An explicit --claim still wins over the environment for a one-off.

The name is now stable per checkout, not the random word it used to be: it is meaningful in karr show, and distinct per worktree without a generator. The recommended way to run several agents on one board is therefore one worktree each -- their directory names already differ, so their claims differ.

--unique

The one case a directory name cannot tell apart is several agents started in the same directory: they would all get the same name and, because claims match by name, stamp and hand off over each other. --unique appends a short random suffix -- karr-8fa -- keeping the checkout identity visible while making each agent distinct. Captured once into KARR_CLAIM, the suffix is stable for that session. This is where the old random-name behaviour now lives.

OPTIONS

  • --unique

    Append a short random suffix to the checkout name, for several agents sharing one directory.

  • --json

    Emit the name as one JSON object -- {"name":"..."} -- and nothing else on stdout, so a caller can capture the name without trimming a trailing newline.

SEE ALSO

karr, App::karr, App::karr::AgentName, App::karr::Cmd::Pick, App::karr::Cmd::Handoff, App::karr::Role::ClaimDefault

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)