view release on metacpan or search on metacpan
bin/acme_claude_shell view on Meta::CPAN
=item B<--no-color>
Disable colored output.
=item B<-d, --directory> DIR
Set working directory (default: current directory).
=item B<-c, --command> CMD
Run a single command and exit instead of starting interactive mode.
Use '-' to read the command from stdin for piping.
=item B<-m, --model> MODEL
Specify the Claude model to use (e.g., claude-opus-4-5, claude-sonnet-4-5).
=item B<-h, --help>
Show help message.
lib/Acme/Claude/Shell/Hooks.pm view on Meta::CPAN
use Claude::Agent::Hook::Result;
use Term::ANSIColor qw(colored);
use Time::HiRes qw(time);
sub safety_hooks {
my ($session) = @_;
my $execute_cmd_pattern = 'execute_command$';
my $any_shell_tool = 'mcp__shell-tools__.*';
$session->_session_start(time()) unless $session->_session_start;
return {
PreToolUse => [
Claude::Agent::Hook::Matcher->new(
matcher => $any_shell_tool,
hooks => [sub {
my ($input, $tool_use_id, $context) = @_;
my $tool_name = $input->{tool_name} // 'unknown';
my $tool_input = $input->{tool_input} // {};
lib/Acme/Claude/Shell/Hooks.pm view on Meta::CPAN
}],
),
],
Stop => [
Claude::Agent::Hook::Matcher->new(
matcher => '.*',
hooks => [sub {
my ($input, $tool_use_id, $context) = @_;
my $duration = time() - ($session->_session_start // time());
my $tool_count = $session->_tool_count // 0;
my $tool_errors = $session->_tool_errors // 0;
my $history_count = scalar(@{$session->_history // []});
if ($session->colorful) {
print "\n";
print colored(['cyan'], "â" x 40) . "\n";
status('info', "Session Statistics");
printf " Duration: %.1f seconds\n", $duration;
printf " Tools used: %d\n", $tool_count;
lib/Acme/Claude/Shell/Hooks.pm view on Meta::CPAN
=cut
=head1 FUNCTIONS
=head2 safety_hooks
my $hooks = safety_hooks($session);
Build the hooks hash for a L<Acme::Claude::Shell::Session> or
L<Acme::Claude::Shell::Query>, ready for the C<hooks> option. Records the
session start time on first call.
=head1 AUTHOR
LNATION, C<< <email at lnation.org> >>
=head1 LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under:
lib/Acme/Claude/Shell/Query.pm view on Meta::CPAN
use 5.020;
use strict;
use warnings;
use Object::Proto ();
use Claude::Agent qw(query create_sdk_mcp_server);
use Claude::Agent::Options;
use Claude::Agent::Content;
use Claude::Agent::CLI qw(
start_spinner stop_spinner
header divider status
);
use Acme::Claude::Shell::Tools qw(shell_tools);
use Acme::Claude::Shell::Hooks qw(safety_hooks);
use Future::AsyncAwait;
BEGIN {
Object::Proto::define('Acme::Claude::Shell::Query',
'loop:Object:required',
'dry_run:Bool:default(0):predicate',
'safe_mode:Bool:default(1):predicate',
'working_dir:Str:default(.):predicate',
'colorful:Bool:default(1):predicate',
'verbose:Bool:default(0):predicate',
'audit_log:Bool:default(0):predicate',
'model:Str:predicate',
'effort:Str:predicate',
'_history:ArrayRef:default([])',
'_spinner',
'_session_start',
'_tool_count:Int:default(0)',
'_tool_errors:Int:default(0)',
'_audit_log:ArrayRef:default([])',
);
}
my @SPINNERS = (
{ spinner => 'moon', spinner_color => 'yellow' },
{ spinner => 'earth', spinner_color => 'cyan' },
{ spinner => 'clock', spinner_color => 'blue' },
lib/Acme/Claude/Shell/Query.pm view on Meta::CPAN
);
}
async sub run {
my ($self, $prompt) = @_;
if ($self->colorful) {
header("Acme::Claude::Shell - Query Mode");
}
$self->_spinner(start_spinner("Thinking...", $self->loop, _random_spinner())) if $self->colorful;
my $iter = query(
prompt => $prompt,
options => $self->options,
loop => $self->loop,
);
my $response_text = '';
my $result;
my %tool_names;
lib/Acme/Claude/Shell/Query.pm view on Meta::CPAN
dry_run => 0,
safe_mode => 1,
);
my $result = $query->run("find all large log files")->get;
=head1 DESCRIPTION
Executes a single natural language command through Claude::Agent's
C<query()>. Each C<run> is independent: no context is kept between calls.
This suits scripting, or a one-shot command without starting an
interactive session.
=head1 ATTRIBUTES
=head2 loop
The L<IO::Async::Loop> to run on. Required.
=head2 dry_run
lib/Acme/Claude/Shell/Query.pm view on Meta::CPAN
Record every tool call in C<_audit_log>. Default 0.
=head2 model
Claude model to use. Optional.
=head2 effort
Effort level: C<low>, C<medium>, C<high>, C<xhigh> or C<max>. Optional.
=head2 _history, _spinner, _session_start, _tool_count, _tool_errors, _audit_log
State the tools and hooks read and write.
=head1 METHODS
=head2 new
Takes a flat list of name/value pairs. Unknown names are ignored.
=head2 options
lib/Acme/Claude/Shell/Session.pm view on Meta::CPAN
use 5.020;
use strict;
use warnings;
use open ':std', ':encoding(UTF-8)';
use Object::Proto ();
use Claude::Agent qw(session create_sdk_mcp_server);
use Claude::Agent::Options;
use Claude::Agent::Content;
use Claude::Agent::CLI qw(
start_spinner stop_spinner
header divider status choose_from
);
use Acme::Claude::Shell::Tools qw(shell_tools);
use Acme::Claude::Shell::Hooks qw(safety_hooks);
use Future::AsyncAwait;
use Term::ReadLine;
use Term::ANSIColor qw(colored);
use File::Spec;
BEGIN {
lib/Acme/Claude/Shell/Session.pm view on Meta::CPAN
'safe_mode:Bool:default(1):predicate',
'working_dir:Str:default(.):predicate',
'colorful:Bool:default(1):predicate',
'verbose:Bool:default(0):predicate',
'audit_log:Bool:default(0):predicate',
'model:Str:predicate',
'effort:Str:predicate',
'_client',
'_history:ArrayRef:default([])',
'_spinner',
'_session_start',
'_tool_count:Int:default(0)',
'_tool_errors:Int:default(0)',
'_audit_log:ArrayRef:default([])',
);
}
my $HISTORY_FILE = File::Spec->catfile($ENV{HOME} // '.', '.acme_claude_shell_history');
my $MAX_HISTORY = 1000;
my @SPINNERS = (
lib/Acme/Claude/Shell/Session.pm view on Meta::CPAN
$self->_client->disconnect if $self->_client && $self->_client->is_connected;
status('info', "Goodbye!") if $self->colorful;
return 1;
}
async sub _process_input {
my ($self, $input) = @_;
if ($self->colorful) {
my $cursor_row = _get_cursor_row();
$self->_spinner(start_spinner("Thinking...", $self->loop,
_random_spinner(),
defined $cursor_row ? (terminal_line => $cursor_row) : ()));
}
if ($self->_client->is_connected) {
$self->_client->send($input);
} else {
$self->_client->connect($input);
}
lib/Acme/Claude/Shell/Session.pm view on Meta::CPAN
Record every tool call in C<_audit_log>. Default 0.
=head2 model
Claude model to use. Optional.
=head2 effort
Effort level: C<low>, C<medium>, C<high>, C<xhigh> or C<max>. Optional.
=head2 _client, _history, _spinner, _session_start, _tool_count, _tool_errors, _audit_log
State the tools and hooks read and write: the L<Claude::Agent::Client>,
the commands run this session, the active spinner, and the statistics the
Stop hook reports.
=head1 METHODS
=head2 new
Takes a flat list of name/value pairs. Unknown names are ignored.
lib/Acme/Claude/Shell/Session.pm view on Meta::CPAN
=item * C<clear> - Clear the screen
=item * C<exit> / C<quit> - Exit the shell
=back
=head1 HISTORY
Command history is persisted to C<~/.acme_claude_shell_history> and loaded
on startup. Maximum 1000 lines are kept.
=head1 AUTHOR
LNATION, C<< <email at lnation.org> >>
=head1 LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION.
This is free software, licensed under:
lib/Acme/Claude/Shell/Tools.pm view on Meta::CPAN
package Acme::Claude::Shell::Tools;
use 5.020;
use strict;
use warnings;
use Exporter 'import';
our @EXPORT_OK = qw(shell_tools);
use Claude::Agent qw(tool);
use Claude::Agent::CLI qw(menu status ask_yn prompt start_spinner stop_spinner);
use IO::Async::Process;
use Future;
use Cwd qw(abs_path getcwd);
use File::Spec;
use Term::ANSIColor qw(colored);
sub shell_tools {
my ($session) = @_;
return [
lib/Acme/Claude/Shell/Tools.pm view on Meta::CPAN
pattern => {
type => 'string',
description => 'Glob pattern to filter files (e.g., "*.pl", "*.txt")',
},
long_format => {
type => 'boolean',
description => 'Show detailed file information (size, date, permissions)',
},
show_hidden => {
type => 'boolean',
description => 'Include hidden files (starting with .)',
},
},
},
sub {
my ($params, $loop) = @_;
return _list_directory_safe($session, $params, $loop);
},
),
tool(
lib/Acme/Claude/Shell/Tools.pm view on Meta::CPAN
unless ($approved) {
my $future = $loop->new_future;
$future->done(_mcp_result("User cancelled command", 1));
return $future;
}
$command = $new_command if defined $new_command;
if ($colorful) {
$session->_spinner(start_spinner("Executing...", $loop));
}
push @{$session->_history}, {
time => _timestamp(),
command => $command,
status => 'running',
};
my $future = $loop->new_future;
my $stdout = '';
t/02-hooks.t view on Meta::CPAN
ok($matcher->matches('mcp__shell-tools__read_file'), 'Matches read_file');
};
subtest 'Stop and Notification matchers match anything' => sub {
ok($hooks->{Stop}[0]->matches('end_turn'), 'Stop matches end_turn');
ok($hooks->{Notification}[0]->matches('any_notification'), 'Notification matches anything');
};
subtest 'Session statistics initialization' => sub {
my $fresh = make_session();
ok(!$fresh->_session_start, 'no start time before the hooks are built');
safety_hooks($fresh);
ok($fresh->_session_start, 'Session start time initialized');
is($fresh->_tool_count, 0, 'Tool count starts at zero');
is($fresh->_tool_errors, 0, 'Tool errors start at zero');
};
subtest 'hooks run through the registry' => sub {
my $audit = make_session(audit_log => 1);
my $registry = Claude::Agent::Hook::Registry->new(hooks => safety_hooks($audit), loop => $loop);
my $config = $registry->to_initialize_config;
is_deeply([sort keys %$config], [qw(Notification PostToolUse PostToolUseFailure PreToolUse Stop)], 'every event is registered');
is($config->{PreToolUse}[0]{matcher}, 'mcp__shell-tools__.*', 'the PreToolUse pattern is sent to the CLI');
my %id_for;
t/04-session.t view on Meta::CPAN
subtest 'Session history' => sub {
plan tests => 3;
require IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $session = Acme::Claude::Shell::Session->new(
loop => $loop,
);
is(scalar(@{$session->_history}), 0, 'History starts empty');
push @{$session->_history}, { command => 'ls', status => 'success' };
is(scalar(@{$session->_history}), 1, 'Can add to history');
push @{$session->_history}, { command => 'pwd', status => 'success' };
is(scalar(@{$session->_history}), 2, 'Can add multiple entries');
};
# Test _spinner attribute
subtest 'Session spinner' => sub {
plan tests => 3;
require IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $session = Acme::Claude::Shell::Session->new(
loop => $loop,
);
ok(!$session->_spinner, 'Spinner starts undefined');
$session->_spinner('fake-spinner');
is($session->_spinner, 'fake-spinner', 'Can set spinner');
$session->_spinner(undef);
ok(!$session->_spinner, 'Can clear spinner');
};
done_testing();
t/05-query.t view on Meta::CPAN
working_dir => '/tmp',
colorful => 0,
);
ok($query, 'Query created');
isa_ok($query, 'Acme::Claude::Shell::Query');
is($query->dry_run, 0, 'dry_run attribute');
is($query->safe_mode, 1, 'safe_mode attribute');
is($query->working_dir, '/tmp', 'working_dir attribute');
is($query->colorful, 0, 'colorful attribute');
ok(!$query->_spinner, '_spinner starts undefined');
};
# Test optional model attribute
subtest 'Query with model' => sub {
plan tests => 2;
require IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $query = Acme::Claude::Shell::Query->new(
t/05-query.t view on Meta::CPAN
subtest 'Query spinner' => sub {
plan tests => 3;
require IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $query = Acme::Claude::Shell::Query->new(
loop => $loop,
);
ok(!$query->_spinner, 'Spinner starts undefined');
$query->_spinner('fake-spinner');
is($query->_spinner, 'fake-spinner', 'Can set spinner');
$query->_spinner(undef);
ok(!$query->_spinner, 'Can clear spinner');
};
done_testing();
t/07-cli-bin.t view on Meta::CPAN
use File::Spec;
# Test the CLI binary exists and has correct structure
my $bin = File::Spec->catfile('bin', 'acme_claude_shell');
# Check file exists
ok(-f $bin, 'CLI binary exists');
ok(-r $bin, 'CLI binary is readable');
# Check it starts with shebang
open my $fh, '<', $bin or die "Cannot open $bin: $!";
my $first_line = <$fh>;
close $fh;
like($first_line, qr/^#!/, 'Starts with shebang');
like($first_line, qr/perl/, 'Uses perl interpreter');
# Check syntax by compiling (but not running)
subtest 'Syntax check' => sub {
plan tests => 1;