NAME

Acme::Claude::Shell::Query - Single-shot query mode for Acme::Claude::Shell

SYNOPSIS

use Acme::Claude::Shell::Query;
use IO::Async::Loop;

my $loop = IO::Async::Loop->new;

my $query = Acme::Claude::Shell::Query->new(
    loop      => $loop,
    dry_run   => 0,
    safe_mode => 1,
);

my $result = $query->run("find all large log files")->get;

DESCRIPTION

Executes a single natural language command using Claude's query() function. Does not maintain session context between calls - each run() is independent.

This is useful for scripting or when you want a one-shot command without starting an interactive session.

Uses Claude::Agent SDK features:

• query() - Single-shot prompt execution

• SDK MCP tools - execute_command, read_file, list_directory, search_files, get_system_info, get_working_directory

• Hooks - PreToolUse (audit), PostToolUse (stats), PostToolUseFailure (errors), Stop (statistics), Notification (logging)

• CLI utilities - Spinners and colored output

Attributes

• loop (required) - IO::Async::Loop instance

• dry_run - Preview mode, don't execute commands (default: 0)

• safe_mode - Confirm dangerous commands (default: 1)

• working_dir - Starting directory (default: '.')

• colorful - Use colored output (default: 1)

• model - Claude model to use (optional)

Methods

• run($prompt) - Execute a single prompt and return a Future

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)