Weave Code
Claude Hooks Sdk Laravel Package
beyondcode/claude-hooks-sdk
A Laravel/PHP SDK for building Claude Code hooks with clean, typed classes instead of raw shell scripts. Register hooks, handle events, and integrate Claude Code automation directly into your Laravel apps with minimal boilerplate.
A PHP SDK for building Claude Code hooks.
Frequently asked questions about Claude Hooks Sdk
- How do I install beyondcode/claude-hooks-sdk?
- Install it with Composer using composer require beyondcode/claude-hooks-sdk. On Laravel the service provider is auto-discovered, so no manual registration is needed. Then publish the config and scaffold your first hook with the package's Artisan install command. Run the generated hook once against Claude Code to confirm the payload parses correctly before wiring it into CI.
- Which Claude Code hook events does this SDK cover?
- The SDK wraps the Claude Code lifecycle events such as PreToolUse, PostToolUse, Notification, Stop, and SessionStart, parsing the JSON payload from stdin into typed event objects. Each hook replies with a decision via exit codes and optional stdout JSON. Because Anthropic owns the hook schema, verify the exact event list against the version of Claude Code you are running. Budget a short spike to confirm coverage before committing to a design.
- How do I publish the config or scaffold a hook in Laravel?
- The package ships a publishable configuration file and an Artisan-friendly install or scaffold command for generating hook classes. Publish the config with the standard vendor:publish tag so hook settings live alongside the rest of your Laravel configuration. The scaffolded class gives you a typed starting point instead of a hand-written shell script. Keep hook definitions small and focused on a single guardrail or side effect.
- Can I use this SDK outside of Laravel?
- Yes. It is a PHP 8+ Composer package that parses stdin and returns decisions, so the Laravel service provider and config publishing are conveniences rather than requirements. Framework-agnostic PHP projects can instantiate the typed event objects and decision responses directly. You lose the Artisan scaffolding, but the core adapter behaviour stays the same.
- What PHP and Laravel versions does it require?
- The package targets PHP 8 and above and integrates idiomatically with modern Laravel through auto-discovery and config publishing. Check the exact Composer constraint in the package's composer.json against your support matrix before adopting it. Also confirm it introduces no conflicting Symfony or PSR constraints against your existing lockfile. Test the resolved dependency set on the same OS images your CI runners use.
- How do I test a Claude Code hook built with this SDK?
- Because the SDK converts a JSON stdin payload into typed event objects, you can feed fixtures directly into your hook classes from PHPUnit or Pest without spawning Claude Code. Assert on the returned decision, exit code, and any stdout JSON your hook emits. Keep a set of payload fixtures captured from real events, and re-record them after Claude Code upgrades. This is the main advantage of typed classes over raw shell scripts, which are hard to unit test.
- Should I add this package to my production dependencies?
- No. Claude Code hooks are short-lived CLI processes spawned by the agent on developer workstations and CI runners, so this belongs in require-dev or a tooling-only context. Keeping it out of production require prevents a developer-tooling dependency from ever loading in an application request path. Treat it as repository and workstation guardrail tooling, not application infrastructure.
- How do I block a destructive command or secret write with a hook?
- Use a PreToolUse hook to inspect the incoming tool call and return a block decision through the SDK's typed response, which the agent translates into exit codes and JSON. Typical first guardrails are blocking infra writes, blocking destructive shell commands, or gating edits behind lint and static analysis. Start with a low-risk, fail-open hook such as audit logging, then tighten to blocking once the payload shape is proven. Log every decision so you can measure blocked actions and audit coverage.
- Does it work on Windows and in CI runners?
- The binding constraint is environmental: Claude Code must be installed and a PHP binary must exist on every machine and runner that fires a hook. The SDK is thin, but hooks are typically spawned through a shell, so behaviour on Windows runners needs explicit testing. Verify against the exact OS images your CI uses and scope that portability work up front. Assume Unix-like environments are the best-supported path until you have proven otherwise.
- Is the package maintained, and what if Anthropic changes the hook schema?
- Treat it as early-stage: it has around 68 stars, zero dependents, and a single July 2025 release, though Beyond Code has a credible Laravel track record. The real risk is contractual, since the hook schema is owned by Anthropic and will evolve independently of the SDK. Pin an exact version, wrap the package behind one small internal interface and DTO, and keep a fork-or-raw-shell fallback ready from day one. That way a schema change or a stalled release costs you one class, not every hook.
Weaver
How can I help you explore Laravel packages today?