README

Laravel + Claude Code, configured to work together.

One command installs a complete Laravel stack with AI-powered code review, consistent coding standards that Claude actually follows, and GitHub workflows that let you @mention Claude in issues and PRs.

composer require stumason/claudavel
php artisan claudavel:install

Why This Exists

Claude Code is powerful, but it works better when your project has clear conventions. Claudavel gives you:

Coding standards Claude follows - Published to docs/standards/ and referenced in CLAUDE.md. No more explaining the same patterns every session.
AI code review on every PR - Claude reviews your code automatically via GitHub Actions. Catches bugs, suggests improvements, checks against your standards.
@claude in issues and PRs - Mention Claude anywhere in GitHub and it responds with context about your codebase.
A complete stack - Fortify, Sanctum, Horizon, Reverb, Telescope, Pail, Wayfinder, Sqids. All configured, all working together.

Quick Start

laravel new my-app
cd my-app
composer require stumason/claudavel
php artisan claudavel:install
createdb my_app
composer run dev

Add CLAUDE_CODE_OAUTH_TOKEN to your GitHub repo secrets to enable AI features.

What Gets Installed

Packages

Package	Purpose
laravel/fortify	Authentication without Breeze/Jetstream bloat
laravel/sanctum	API tokens
laravel/horizon	Redis queue dashboard
laravel/reverb	WebSockets without third-party services
laravel/telescope	Debug assistant
laravel/pail	Real-time log tailing
laravel/wayfinder	Type-safe routes in TypeScript
sqids/sqids	ID obfuscation

GitHub Workflows

Workflow	What it does
claude-code-review.yml	AI reviews every PR automatically
claude.yml	Responds to @claude mentions
tests.yml	Runs Pest with Postgres
lint.yml	Pint + ESLint + Prettier
dependabot-automerge.yml	Auto-merges minor/patch dependency updates

Coding Standards

Published to docs/standards/ with conventions that matter:

Actions pattern - Business logic in app/Actions/{Domain}/
DTOs - Type-safe data containers in app/DataTransferObjects/
Money as integers - Store cents, not dollars
Lowercase imports - @/components/button not @/Components/Button

These get referenced in your CLAUDE.md so every Claude session knows your conventions.

Environment

DB_CONNECTION=pgsql
SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis
ADMIN_EMAILS=you@example.com,team@example.com

Configuration

Claudavel publishes config/claudavel.php for package settings:

// config/claudavel.php
return [
    'admin_emails' => env('ADMIN_EMAILS'),  // Comma-separated list
];

Admin emails control access to Horizon and Telescope in production. In local environment, everyone has access.

Features

ID Obfuscation

Never expose sequential IDs. Add the trait to any model:

use App\Models\Traits\HasUid;

class User extends Model
{
    use HasUid;
}

$user->uid;  // "K4x9Pq" instead of "1"
User::findByUid('K4x9Pq');  // Works
Route::get('/users/{user}', ...);  // Binds automatically

Generator Commands

php artisan make:action User/UpdateProfile
php artisan make:dto UserProfile --properties=id:int,name:string,email:?string
php artisan types:generate  # Generates TypeScript interfaces from DTOs

Health Check

The /health endpoint verifies database, Redis, cache, queue, and storage. Use it for load balancer checks.

Installation Options

php artisan claudavel:install                      # Install everything (default)
php artisan claudavel:install --horizon            # Only Horizon (skip Reverb, Telescope)
php artisan claudavel:install --no-workflows       # Skip GitHub workflows
php artisan claudavel:install --force              # Overwrite existing files

The command is idempotent - run it on existing projects and it only installs what's missing.

Development Server

composer run dev runs everything concurrently:

Laravel dev server
Horizon (queue worker)
Reverb (WebSockets)
Scheduler (schedule:work)
Pail (log tailing)
Vite (frontend)

Requirements

PHP 8.3+
Laravel 12+
Postgres
Redis

License

MIT

stumason / claudavel

Maintainers

Details