Quickstart

Introduction

You just heard about Laraclaw and you want to see it actually do something. No webhooks, no Redis-required-yet, no production setup — just the smallest loop you can iterate from.

In this guide, we'll install the package, run the setup wizard, and have the agent reply to you in your terminal. Five minutes from now, you'll be talking to your Laravel app.

Ready? Let's go!

What You'll Have at the End

A working Laraclaw install with one connector (the terminal) talking to your AI provider of choice. From here, every other connector is just plumbing on top of the same loop — once this works, the rest is configuration.

1. Install the Package

Drop into your Laravel project and pull the package in via Composer:

composer require laraclaw/laraclaw
php artisan vendor:publish --tag=laraclaw

This drops config/laraclaw.php, the migrations, and the agent folder (laraclaw/instructions.md, a starter persona, and an example skill). We'll touch a few of them later.

2. Run the Wizard

Now for the fun part:

php artisan laraclaw:setup

The wizard walks you through everything. When it asks:

• Owner user — pick any user in your users table. This becomes your LARACLAW_ADMIN_USER_ID. (No users table yet? Make sure you've run your app's own migrations first.)
• AI provider — pick whichever laravel/ai driver you have credentials for. The wizard prompts for the API key inline.
• Connectors — skip them all for now. We can wire them up after the loop is working.
• Memory, Files, Calendar, Read Database, Headless Browser, Tinker — skip them all too. You don't need them yet.

The wizard writes everything to your .env, runs the migrations, and exits. Pretty smooth, right?

3. Start a Queue Worker

The terminal connector dispatches the agent invocation to a job, so without a worker the loop never closes. In a second terminal, run:

php artisan queue:work

Leave it running. You'll see jobs fly through it once you start chatting.

!TIP If you've never used Laravel queues before, the default QUEUE_CONNECTION=sync would also work for the terminal connector — but switching to database or redis matches what you'll need in production. The wizard does this for you.

4. Talk to the Agent

In a third terminal:

php artisan laraclaw:chat

You're now in a REPL talking to the agent as the owner. Send a message:

> Hi, what tools do you have access to?

The agent should reply within a few seconds. If it does, your install is working end-to-end and every other connector is just plumbing on top of this same loop. Awesome!

Try a couple more:

> What time is it?
> Set a reminder for 5 minutes from now to drink water.

If reminders aren't enabled yet (we skipped them in step 2), the agent will tell you so. That's fine — the point is to confirm the loop is alive.

Troubleshooting

A few things that trip people up the first time:

• "No reply at all." Check that php artisan queue:work is actually running and look at its output for stack traces. Most failures land there.
• "401 / authentication error." Your AI_DEFAULT provider's API key is wrong or missing. Re-run php artisan laraclaw:setup-agent to fix it without re-doing the whole wizard.
• "Agent says it has no tools." That's expected with the minimal quickstart config. We disabled them all in step 2 — head to Tools to enable some.

What to Do Next

Now that the loop works, here's where we'd go:

• Wire up a real chat surface. Pick a connector and run its setup wizard. Telegram is the fastest to get a webhook for — five minutes with @BotFather and you're done.
• Give the agent capabilities. Browse the tools. The File Manager and Calendar are the most commonly enabled.
• Read the Introduction for the mental model — what tools, skills, personas, commands, and superpowers are, and when to pick which.
• Read Deployment before you put this in front of users. The terminal loop has different requirements than a webhook-driven install.

Until next time!