README

PHPClaw for Laravel

A role-routed, tool-using AI agent platform for Laravel, built on the Laravel AI SDK. Inspired by PHPClaw, rebuilt the Laravel way: SOLID, CQRS, and a driver port so the whole agent layer is testable without ever calling a model.

Full docs in docs/: architecture · routing · tools · modules · sessions · memory · tasks · REST API · commands · browser control · development.

What it gives you

Role-based model routing with fallback — a role maps to a primary model and an ordered fallback chain; the runner fails over when a model errors or rate-limits.
Tools — 14 shipped (calculator, http, filesystem-read, grep, system/project/code analysis, memory) handed to the model via the Laravel AI SDK's function-calling. Add your own by implementing one interface.
Modules / tool-router — per-task tool whitelists (reasoning, coding, research, …) bundling a role + the tools that task may use.
Sessions — persisted chat transcripts that carry context across turns.
Memory — long-term notes the agent can write and recall, with compaction.
Queued tasks — run the agent in the background on Laravel's queue.
REST API — a token-guarded POST /phpclaw/chat endpoint.
Browser control — a bundled (TypeScript) Chrome extension lets the agent drive a real browser.
Dangerous tools, guarded — shell_exec / file_write / delete_file ship behind a static prohibition guard (like DB::prohibitDestructiveCommands()).
CQRS bus — every action is a Command/Query dispatched to a dedicated handler.
A driver port (LlmDriver) — the core depends on an interface; laravel/ai is one (optional) driver, so the whole stack is unit-tested with a fake driver.

Installation

composer require kevariable/phpclaw-laravel
php artisan vendor:publish --tag="phpclaw-laravel-config"

For the built-in Gemini driver, also install the Laravel AI SDK (needs Laravel 12.62+ or 13) and set your key — or bind your own LlmDriver and skip it:

composer require laravel/ai

GEMINI_API_KEY=your-key
PHPCLAW_API_TOKEN=a-long-random-string      # for the REST API
PHPCLAW_BROWSER_TOKEN=a-long-random-string  # for the browser extension

Usage

use Kevariable\PhpclawLaravel\Facades\Phpclaw;
use Kevariable\PhpclawLaravel\Tools\CalculatorTool;

// Run by role
$result = Phpclaw::run('reasoning', 'What is 19 * 23?', tools: [new CalculatorTool]);
echo $result->text;    // model output
echo $result->model;   // the model that actually answered (after any fallback)

// Run by module (uses the module's role + its tool whitelist)
Phpclaw::runModule('coding', 'Find where the bus is bound and explain it.');

// Inspect configuration
Phpclaw::roles();      // list<RoleDefinition>
Phpclaw::tools();      // list<Tool>
Phpclaw::modules();    // list<ModuleDefinition>

Roles & modules

config/phpclaw.php:

'roles' => [
    'reasoning' => [
        'provider' => 'gemini',
        'model' => 'gemini-2.5-flash',
        'timeout' => 120,
        'fallback' => [['provider' => 'gemini', 'model' => 'gemini-2.5-flash-lite']],
    ],
],

'modules' => [
    'coding' => ['role' => 'coding', 'tools' => ['file_read', 'dir_list', 'grep_search', 'code_symbols']],
],

Custom tools

Implement Kevariable\PhpclawLaravel\Contracts\Tool and add the class to phpclaw.tools (or scaffold one with php artisan make:phpclaw-tool WeatherTool):

class WeatherTool implements Tool
{
    public function name(): string { return 'weather'; }
    public function description(): string { return 'Get the weather for a city.'; }
    public function parameters(): array
    {
        return ['city' => ['type' => 'string', 'description' => 'City name.', 'required' => true]];
    }
    public function run(array $arguments): string { return "Sunny in {$arguments['city']}."; }
}

Dangerous tools

shell_exec, file_write, file_append, delete_file, mkdir, move_file, and db_query are shipped but prohibited by default — every call is gated like Laravel's DB::prohibitDestructiveCommands(). Opt in when you trust the environment:

use Kevariable\PhpclawLaravel\DangerousTools;

DangerousTools::allow();      // enable (off by default) — any dangerous tool works
DangerousTools::prohibit();   // re-lock; calls throw DangerousToolsProhibitedException

// or via the facade:
Phpclaw::prohibitDangerousTools();

Sessions, memory & queued tasks

Phpclaw::run('reasoning', 'long job…');   // synchronous

// Background (queued) — see docs/tasks.md
php artisan phpclaw:run reasoning "long job…" --queue

Artisan commands

Command	Purpose
`phpclaw:run {role} {prompt}`	One-shot generation (`--queue` to background it)
`phpclaw:chat`	Interactive REPL (`--role`, `--module`, `--session`)
`phpclaw:roles` / `:providers` / `:models`	Inspect roles, providers, models
`phpclaw:tools` / `:tools:test`	List / smoke-test tools
`phpclaw:modules`	List modules
`phpclaw:status`	Config summary
`phpclaw:sessions` / `:session:show {id}`	Chat sessions
`phpclaw:memory:show` / `:memory:compact`	Long-term memory
`phpclaw:tasks` / `:task:show {id}`	Queued tasks
`make:phpclaw-tool {name}`	Generate a tool stub

See docs/commands.md for the full reference.

REST API

curl -X POST http://localhost:8000/phpclaw/chat \
  -H "Authorization: Bearer $PHPCLAW_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Explain CQRS in one sentence.","module":"reasoning"}'
# => {"response":"…","model":"gemini-2.5-flash"}

See docs/api.md.

Browser control

A bundled TypeScript Chrome extension lets the agent drive a real browser. Publish the built extension, load it unpacked, and add the BrowserControlTool:

php artisan vendor:publish --tag="phpclaw-extension"   # -> base_path('phpclaw-extension')

See docs/browser.md for the full setup and the extension's TypeScript build.

Testing

Targets PHP 8.4 (Laravel 13 pulls Symfony 8, which needs PHP >= 8.4.1). The bundled Docker image pins it:

make build      # build the PHP 8.4 image
make test       # Pest suite
make coverage   # coverage (100%)
make analyse    # PHPStan (level 5 + Larastan)
make format     # Pint

Natively, with PHP 8.4: composer test / composer analyse / composer format. See docs/development.md.

License

The MIT License (MIT). See License File.

kevariable / phpclaw-laravel

Maintainers

Package info

Fund package maintenance!

Statistics

Security