NAME

App::karr::Cmd::AgentName - Generate a random two-word agent name

VERSION

version 0.600

SYNOPSIS

karr agentname

# Capture the name once, then pass the same variable to every call that
# has to agree about the claim:
NAME=$(karr agentname)
karr pick --claim "$NAME" --move in-progress
karr handoff 7 --claim "$NAME" --note "Implementation complete"

DESCRIPTION

Generates a random two-word, lowercase agent name joined by a hyphen. The command prefers the system dictionary when available and falls back to the built-in word list otherwise.

Every call mints a new name. Nothing is remembered between calls -- not per board, not per process, not per agent -- so $(karr agentname) written twice produces two unrelated names.

That matters because claims are compared by name. --claim on App::karr::Cmd::Pick and App::karr::Cmd::Move records the name; App::karr::Cmd::Move, App::karr::Cmd::Edit and App::karr::Cmd::Handoff check the name they are handed against the one on the card ("check_claim" in App::karr::Role::ClaimTimeout); and karr list --claimed-by and karr log --agent select on it. So this pair

karr pick --claim "$(karr agentname)" --move in-progress    # DON'T
karr handoff 7 --claim "$(karr agentname)"                  # DON'T

claims under one name and hands off under another. Substituting the command inline is only ever correct where the name is used once and never referred to again -- which is almost never, since the handoff at the end of the work is a second reference. Capture it into a shell variable instead, as the SYNOPSIS does (ticket #176).

A name that was not captured is still recoverable from the board rather than lost: karr pick prints (claimed by NAME), karr show ID prints Claimed:, and the refusal check_claim raises names the current claimant. Minting a fresh one instead is the mistake. While the original claim is live the mismatch is refused outright; once it has expired the mutation goes through and re-stamps the card, but no longer without saying so -- the override is reported with the name it stepped over ("expired_claim_report" in App::karr::Role::ClaimTimeout), which is the same name to go back to.

The generated name is deliberately not made stable per agent. Any handle that would survive across separate karr processes -- the board, the Git identity, the host -- is equally shared by every other agent working that same board, so deriving a name from one would hand two concurrent agents an identical claim. That is strictly worse than the mismatch it would fix: a mismatch is refused by check_claim, a collision is indistinguishable from the rightful owner and is not. Callers that need a stable identity should supply their own name and not go through this command, which exists to suggest a name, not to remember one.

SEE ALSO

karr, App::karr, App::karr::Cmd::Pick, App::karr::Cmd::Handoff, App::karr::Cmd::Log, App::karr::Role::ClaimTimeout

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)