Acme-Claude-Shell

 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;



( run in 2.655 seconds using v1.01-cache-2.11-cpan-234fa220139 )