datashaman/claude-agent-laravel
Laravel integration for building Claude-powered AI agents. Provides an agent loop with tool/function calling, conversation history, configurable system prompts, and a clean facade-based API so you can add Anthropic Claude assistants to any Laravel app.
This is a thin Laravel wrapper around the Claude Code CLI, so the surface area is small: one config file, one chat entry point, and env passthrough. Start here:
composer require the package, then php artisan vendor:publish --tag=claude-config to get config/claude.php.ANTHROPIC_API_KEY in .env. Confirm the CLI binary is on PATH in whatever process runs PHP (this bites people under Sail, Octane, and Horizon).app(ClaudeChat::class)->send('hello') — if this fails, it's almost always a binary-path or key-passthrough issue, not a package bug.The first real use case is a single-turn endpoint ("summarise this ticket", "draft a reply") behind a queued job. Don't start with streaming chat UI; start with a job that returns a string and log the raw output.
v0.2.1 matters if you deploy in containers: set CLAUDE_BARE=true (or 'bare' => true in config) to run without the interactive TUI assumptions. That's the main reason to adopt this release.
Config-first, not constructor-first. The new bare and exclude_env_keys options are both config-driven, which tells you the intended pattern: resolve behaviour from config('claude.*') per environment rather than passing flags at call sites. Keep CLAUDE_BARE false locally (you want the richer CLI behaviour when debugging) and true in the container image.
Wrap every call in a job. CLI subprocesses are slow and can hang. A ShouldQueue job with $timeout set slightly below the CLI's own timeout, plus $tries = 1 unless the operation is idempotent, is the safe default. This also makes bare mode's lack of interactivity a non-issue.
Env passthrough is now a deliberate decision. The SDK excludes ANTHROPIC_API_KEY from CLI passthrough by default — sensible for SDK-managed auth, but confusing when the wrapper shells out. If you rely on per-tenant keys, set them explicitly in exclude_env_keys-aware config or inject them into the subprocess environment yourself; don't assume the parent process env "just works".
Multi-tenant / per-request credentials. Combine exclude_env_keys with a scoped config override (config(['claude.exclude_env_keys' => [...]]) inside a middleware or job) so a customer's key isn't inherited by an unrelated concurrent request under Octane. This is the single most important pattern for SaaS deployments.
Bare mode for CI and batch. CLAUDE_BARE=true makes the wrapper usable in cron, queue workers, and GitHub Actions without a TTY. Pair it with a pinned model name in config so batch output stays reproducible across releases.
--bare strips interactive prompts, hooks, and some project-context discovery. Prompt quality can regress silently when you flip the flag — diff outputs on a fixed corpus before enabling it in production.ANTHROPIC_API_KEY exclusion is the #1 support ticket. If your CLI calls start failing with auth errors after upgrading, this default is why. Either pass the key through explicitly or manage auth in the CLI's own config.exclude_env_keys is a list, and list config merges badly. Laravel's config:cache and package-merge semantics mean a partial override can wipe the SDK's defaults. Always re-declare the full intended list rather than appending one key.^0.2 and treat minor bumps as review-worthy.ClaudeChat binding, prefer rebinding in a service provider over forking — you'll want to swap in a fake for tests, and a fake is far cheaper than hitting the real CLI in CI.How can I help you explore Laravel packages today?