/ 
Acme-Claude-Shell-0.03
/ Acme::Claude::Shell

NAME

Acme::Claude::Shell - AI-powered interactive shell using Claude Agent SDK

VERSION

Version 0.03

SYNOPSIS

use Acme::Claude::Shell qw(shell run);

# Interactive session mode (uses session() for multi-turn context)
shell();

# Single-shot query mode (uses query())
my $result = run("find all large log files");

# With options
shell(
    dry_run   => 1,      # Preview mode - show commands without executing
    safe_mode => 0,      # Disable dangerous command warnings
    colorful  => 1,      # Force colors (default: auto-detect)
);

DESCRIPTION

Acme::Claude::Shell is an AI-enhanced interactive shell that showcases all Claude::Agent SDK features:

  • query() for single-shot commands

  • session() for multi-turn conversations with context

  • SDK MCP tools for shell operations

  • Hooks for safety (confirm destructive commands)

  • Dry-run mode to preview

  • Async with IO::Async

  • CLI utilities (spinners, colored output, menus)

Describe what you want in natural language, and Claude figures out the shell commands, explains them, and executes them (with your approval).

EXPORTS

shell

shell(%options);

Start an interactive REPL session. Claude remembers context from previous commands, so you can say things like "now compress those files".

Options:

dry_run     - Preview mode, don't execute commands
safe_mode   - Confirm dangerous commands (default: 1)
working_dir - Starting directory (default: current)
colorful    - Force colors on/off (default: auto-detect)

run

my $result = run($prompt, %options);

Execute a single command and return the result. Does not maintain session context between calls.

EXAMPLE SESSION

============================================================
  Acme::Claude::Shell
============================================================

i AI-powered shell - describe what you want in plain English
i Type 'exit' or 'quit' to leave, 'history' for command log
------------------------------------------------------------

acme_claude_shell> find all perl files larger than 100k
Thinking...

I'll find all .pl files over 100KB and display their sizes:

i Command: find . -name "*.pl" -size +100k -exec ls -lh {} \;

Action:
  [a] Approve and run
  [d] Dry-run (show only)
  [e] Edit command
  [x] Cancel
> a

-rw-r--r--  1 user  staff   142K Jan 10 14:23 ./big_script.pl

Done

acme_claude_shell> now compress that file
Thinking...

Based on our previous results, I'll compress:

i Command: gzip ./big_script.pl

Action:
  [a] Approve and run
> a

Files compressed successfully

SDK FEATURES DEMONSTRATED

This module demonstrates every major feature of the Claude::Agent SDK:

query() - Single-shot mode via run()
session() - Multi-turn context via shell()
SDK MCP Tools - 6 tools: execute_command, read_file, list_directory, search_files, get_system_info, get_working_directory
Hooks (PreToolUse) - Audit logging of tool calls
Hooks (PostToolUse) - Stop spinner, track statistics
Hooks (PostToolUseFailure) - Graceful error handling
Hooks (Stop) - Session statistics on exit
Hooks (Notification) - Event logging (verbose mode)
Dry-run mode - Preview without executing
IO::Async - Non-blocking command execution and spinners
CLI utilities - Spinners, menus, colored output

Note: Command approval is handled directly in the execute_command tool handler to ensure it happens synchronously before execution.

AUTHOR

LNATION, <email at lnation.org>

SEE ALSO

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)