Tinker

Introduction

Tinker is the agent's escape hatch. With it enabled, the agent can evaluate arbitrary PHP in the context of your booted Laravel app: query Eloquent models, hit the cache, inspect config, call any facade or service in the container. It can also run shell commands via Process::run(...), so this one tool covers both "ask the database" and "run an arbitrary script".

Ask "how many orders did we ship last week?" and the agent writes the query, runs it, and answers. Ask "what's on disk in storage/app?" and it shells out from PHP and tells you.

It's disabled by default. There is no sandbox.

Enabling Tinker

LARACLAW_TINKER_ENABLED=true

You'll also need laravel/tinker installed:

composer require laravel/tinker

When disabled, the tool is not registered with the agent at all.

Running Code

The tool accepts a single parameter:

The code is passed to php artisan tinker --execute in-process via Artisan::call, so there is no separate PHP boot per call. The output is returned as JSON containing exit_code and output.

Working With Your Models

The agent has access to everything in your app/Models directory and uses it the way you would in a Tinker session:

App\Models\Order::where('shipped_at', '>=', now()->subWeek())->count();

App\Models\User::with('subscription')
    ->where('subscription.cancelled_at', null)
    ->count();

For the agent to use your models effectively, model and column names should be self-describing. A User model with last_login_at is easier for the agent to reason about than one with lla or t3.

Running Shell Commands

Shell commands are available through Laravel's Process facade:

Process::run('git log --oneline -n 10')->output();

Process::run('ls -la storage/app')->output();

The agent does not need a separate shell tool. Wrapping a shell call in PHP is one layer of escaping instead of two.

Output Limits

Output is capped at 100 KB. Beyond that the response is truncated with a marker.

Security Considerations

!WARNING Tinker is full PHP execution inside your running application. The agent can read and write any model, run any shell command the PHP process can run, and reach anything the container exposes. There is no read-only mode.

• Don't enable this on a shared host or any machine where the PHP process has access to data the owner shouldn't see.
• Wrap write operations in custom tools that declare requiresApproval. Tinker itself does not prompt before running code.
• Inbound messages can influence prompts. Anyone who can message a trusted sender or DM the bot can in principle convince the agent to run code. Trust your trusted senders.
• Set LARACLAW_LOG_AGENT_REQUESTS=true to keep an audit trail of every prompt and response.
• Be deliberate about who can message the bot. With Tinker enabled, every trusted sender effectively has database write and shell access.

For narrower access — for example, "the agent may only run SELECT queries" — use the Read Database tool instead, which enforces read-only at the database connection level. For "the agent may only run queries against the orders table", build a custom tool that exposes exactly that.