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

NAME

App::karr::AgentName - Derive a claim-safe agent name from a checkout directory

VERSION

version 0.601

SYNOPSIS

use App::karr::AgentName qw( agent_name );

my $name   = agent_name();                       # this checkout, e.g. "karr"
my $unique = agent_name( unique => 1 );           # e.g. "karr-8fa"
my $other  = agent_name( dir => $path, unique => 1 );

DESCRIPTION

The name derivation behind karr agent-name (App::karr::Cmd::AgentName), lifted out of the command so that it is callable without a command object. ADR 0005 makes KARR_CLAIM default to exactly what karr agent-name prints, and App::karr::Foundation::Runner exports KARR_CLAIM into an agent's environment -- so both sides have to produce the same string from the same checkout, which means one function, not two copies.

The name is the checkout's own directory name, sanitised to a claim-safe token: a value that is stable per worktree, meaningful in karr show, and distinct per worktree without a generator. unique => 1 appends a short random suffix for the one case a directory name cannot tell apart -- several agents started in the same directory (ADR 0005, scenario S3).

agent_name

my $name = agent_name( dir => $path, unique => 1 );

The claim name for a checkout. Both arguments are optional:

  • dir -- the directory to name. Defaults to the current directory. The worktree root is discovered from it ("checkout_basename"), so it does not matter which subdirectory of the checkout is passed.

  • unique -- when true, append - and a short random alphanumeric suffix, so several agents in the same directory get distinct names.

Returns the sanitised base name ("sanitize_claim_token"), with the suffix when asked. A directory whose name sanitises to nothing falls back to agent, so the result is always a usable claim token.

checkout_basename

my $base = checkout_basename( dir => $path );

The raw (un-sanitised) directory name of the checkout dir sits in: the worktree root discovered by walking up from dir the way every other board-discovering path does ("repo_root" in App::karr::Git, libgit2's workdir, which is what git rev-parse --show-toplevel reports). Outside a work tree it falls back to the basename of dir itself (default: the current directory).

sanitize_claim_token

my $token = sanitize_claim_token('My Project!');   # "my-project"

Folds any string to a claim-safe token: lowercase, every run of characters outside [a-z0-9] collapsed to a single -, with leading and trailing - trimmed. Returns the empty string when nothing survives.

SEE ALSO

karr, App::karr, App::karr::Cmd::AgentName

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)