view release on metacpan or  search on metacpan

lib/App/FuguBench/Traces.pod  view on Meta::CPAN

=head1 NAME

App::FuguBench::Traces - the traces verb of fugubench

=head1 SYNOPSIS

    fugubench [-C <root>] traces [--root <dir>] [--name <name>]

=head1 DESCRIPTION

B<App::FuguBench::Traces> measures the Claude Code sessions of one
checkout. Claude Code keeps one trace directory for each working
directory, under F<~/.claude/projects/>. The name of the directory is
the absolute path of the working directory, and the harness replaces
each character outside a letter, a digit and a hyphen with a hyphen.

The verb derives that name from the checkout root, it matches the
trace directories of the checkout, and it prints one line for each
session in them that holds a request. The verb takes no argument, and
an argument gives the usage error.

This verb and the hook verb hold the Claude Code assumptions of the
program. Every other verb is agent-agnostic.

=head2 THE NAME

The name comes from the checkout root of C<-C>, or of the walk to the
nearest F<.toolingrc>. The verb resolves that root to its real path,
and it cuts the path at the last F<.claude/worktrees/> marker. A
nested checkout holds the marker more than one time, and a cut at the
first marker names the wrong checkout.

A worktree holds a F<.toolingrc> of its own, so the walk stops in the
worktree and the cut reaches the checkout. The sessions of a worktree
then join the sessions of the checkout that holds it.

=head2 THE MATCH

Three name forms belong to one checkout: the checkout itself, a
worktree of it, and a project clone in either of them. The match takes
the exact forms, so a sibling checkout, such as a backup, stays out.

=head2 THE OPTIONS

C<--root E<lt>dirE<gt>> names a trace root in place of the directory
under the home of the operator. A trace root that is no directory is a
failure, and the message holds the path.

C<--name E<lt>nameE<gt>> replaces the derived name. The verb then
derives no name. It still reads the checkout, because the edits column
takes its boundary from the checkout path.

=head2 THE OUTPUT

The verb prints a header, and one line for each session that holds a
request. The lines sort by start time. A session with no request never
reached the model, so it gets no line. A name that matches no
directory gives one line, C<no session of E<lt>nameE<gt>>, and the
verb returns 0.

The columns are:

=over 4

=item C<session>

The first eight characters of the session identifier.

=item C<start>

The time of the first record of the session, in UTC.

=item C<reqs>

The requests of the main session.

=item C<peak>

The largest context of one request: the fresh input tokens, the cache
writes and the cache reads.

=item C<out>

The output tokens of the main session, thinking included.

=item C<panel>

The requests that hold a panel launch.

=item C<edits>

The file edits of the main session after the first panel launch.

=item C<sub-in>

The input tokens of every sub-agent of the session.

=item C<sub-out>

The output tokens of every sub-agent.