/ 
Claude-Agent-0.12
/ Claude::Agent::Client

NAME

Claude::Agent::Client - Persistent session client for Claude Agent SDK

SYNOPSIS

use Claude::Agent::Client;
use Claude::Agent::Options;

my $client = Claude::Agent::Client->new(
    options => Claude::Agent::Options->new(
        allowed_tools => ['Read', 'Glob', 'Grep'],
    ),
);

# Start a session
$client->connect("Help me understand this codebase");

# Process messages until result
while (my $msg = $client->receive) {
    if ($msg->isa('Claude::Agent::Message::Result')) {
        print "Result: ", $msg->result, "\n";
        last;
    }
    elsif ($msg->isa('Claude::Agent::Message::Assistant')) {
        print "Claude: ", $msg->text, "\n";
    }
}

# Send follow-up in same session
$client->send("Now find all TODO comments");

while (my $msg = $client->receive) {
    # ... process messages
}

# Disconnect when done
$client->disconnect;

DESCRIPTION

Claude::Agent::Client provides a persistent session interface for multi-turn conversations with Claude. Unlike the simple query() function which creates a new session for each call, the Client maintains state across multiple interactions.

ATTRIBUTES

options

Claude::Agent::Options object with configuration settings.

METHODS

connect

$client->connect($prompt);

Start a new session with the given prompt.

is_connected

if ($client->is_connected) { ... }

Returns true if the client has an active session.

session_id

my $id = $client->session_id;

Returns the current session ID (available after first message).

receive

my $msg = $client->receive;

Blocking call to receive the next message. Returns undef when no more messages.

receive_async

my $msg = await $client->receive_async;

Async call to receive the next message. Returns a Future.

receive_until_result

my @messages = $client->receive_until_result;

Receive all messages until a Result message is received.

send

$client->send($message);

Send a follow-up message in the current session.

interrupt

$client->interrupt;

Send an interrupt signal to abort the current operation.

disconnect

$client->disconnect;

End the current session.

resume

$client->resume($session_id, $prompt);

Resume a previous session.

EXAMPLE: INTERACTIVE SESSION

use Claude::Agent::Client;
use Claude::Agent::Options;

my $client = Claude::Agent::Client->new(
    options => Claude::Agent::Options->new(
        allowed_tools   => ['Read', 'Glob', 'Grep', 'Edit'],
        permission_mode => 'acceptEdits',
    ),
);

# Interactive loop
print "Enter your first prompt: ";
while (my $input = <STDIN>) {
    chomp $input;
    last if $input eq 'quit';

    if ($client->is_connected) {
        $client->send($input);
    } else {
        $client->connect($input);
    }

    # Process response
    for my $msg ($client->receive_until_result) {
        if ($msg->isa('Claude::Agent::Message::Assistant')) {
            print "Claude: ", $msg->text, "\n\n";
        }
        elsif ($msg->isa('Claude::Agent::Message::Result')) {
            print "--- End of turn ---\n";
        }
    }

    print "Your turn: ";
}

$client->disconnect;

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).