README

Claude Code-equivalent tools for laravel/ai agents. Filesystem, shell, task management, and tool discovery.

Requirements

• PHP 8.3+
• Laravel 12+ or 13+
• laravel/ai ^0.3

Installation

composer require datashaman/laravel-agent-tools

The service provider is auto-discovered. To publish the config:

php artisan vendor:publish --tag=laravel-agent-config

For the database task store, publish and run the migration:

php artisan vendor:publish --tag=laravel-agent-migrations
php artisan migrate

Tools

Filesystem

Execution

Task Management

Meta

Usage

All tools implement Laravel\Ai\Contracts\Tool and work with any laravel/ai agent:

use DataShaman\LaravelAgent\Tools\Filesystem\ReadFile;
use DataShaman\LaravelAgent\Tools\Filesystem\WriteFile;
use DataShaman\LaravelAgent\Tools\Filesystem\EditFile;
use DataShaman\LaravelAgent\Tools\Filesystem\GlobFiles;
use DataShaman\LaravelAgent\Tools\Filesystem\GrepFiles;
use DataShaman\LaravelAgent\Tools\Execution\RunCommand;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CodeAssistant implements Agent, HasTools
{
    use Promptable;

    public function __construct(
        private string $projectPath,
    ) {}

    public function instructions(): string
    {
        return 'You are a code assistant with full filesystem and shell access.';
    }

    public function tools(): iterable
    {
        return [
            new ReadFile(basePath: $this->projectPath),
            new WriteFile(basePath: $this->projectPath),
            new EditFile(basePath: $this->projectPath),
            new GlobFiles(basePath: $this->projectPath),
            new GrepFiles(basePath: $this->projectPath),
            new RunCommand(
                basePath: $this->projectPath,
                timeout: 30,
                allow: ['git *', 'composer *', 'php *'],
                deny: ['rm -rf *', 'sudo *'],
            ),
        ];
    }
}

Task Management

use DataShaman\LaravelAgent\Support\InMemoryTaskStore;
use DataShaman\LaravelAgent\Tools\Tasks\TaskCreate;
use DataShaman\LaravelAgent\Tools\Tasks\TaskList;
use DataShaman\LaravelAgent\Tools\Tasks\TaskUpdate;

$store = new InMemoryTaskStore;

$tools = [
    new TaskCreate($store),
    new TaskList($store),
    new TaskUpdate($store),
    // ... other tools
];

Tool Discovery

Start with a minimal tool set and let the agent discover more at runtime:

use DataShaman\LaravelAgent\Support\ToolRegistry;
use DataShaman\LaravelAgent\Tools\Meta\ToolSearch;

$registry = new ToolRegistry([
    new ReadFile(basePath: $path),
    new WriteFile(basePath: $path),
    new EditFile(basePath: $path),
    new GlobFiles(basePath: $path),
    new GrepFiles(basePath: $path),
    new RunCommand(basePath: $path),
]);

// Agent starts with just ReadFile, GlobFiles, and ToolSearch
$tools = [
    new ReadFile(basePath: $path),
    new GlobFiles(basePath: $path),
    new ToolSearch($registry),
];

Background Commands

use DataShaman\LaravelAgent\Support\InMemoryTaskStore;
use DataShaman\LaravelAgent\Support\ProcessManager;
use DataShaman\LaravelAgent\Tools\Execution\RunCommand;

$store = new InMemoryTaskStore;
$processManager = new ProcessManager($store);

// Async: background process via Laravel Process::start()
$tool = new RunCommand(
    basePath: $path,
    executor: 'async',
    taskStore: $store,
    processManager: $processManager,
);

// Queued: dispatched as a Laravel job
$tool = new RunCommand(
    basePath: $path,
    executor: 'queued',
    taskStore: $store,
);

Configuration

All tools are configured via constructor parameters. No global config required.

The config/laravel-agent.php file provides defaults for the service provider bindings:

Sandboxing

All filesystem and execution tools accept a basePath parameter that restricts operations to that directory. Paths outside basePath are rejected.

RunCommand additionally supports allow and deny glob patterns for command filtering. Deny takes precedence over allow.

Custom Descriptions

Every tool ships with Claude Code-quality descriptions that guide LLM behavior. Override them per-instance:

new EditFile(
    basePath: $path,
    description: 'Edit files. No restrictions.',
)

Testing

composer test

Or directly:

vendor/bin/phpunit

License

MIT