Weave Code
Agent Detector Laravel Package
shipfastlabs/agent-detector
Lightweight Laravel/PHP utility to detect when your code is running inside an AI agent or automated dev environment. Supports multiple known agents (e.g., Cursor, Gemini, Codex, Claude) via environment-variable detection. Requires PHP 8.2+.
A lightweight PHP utility to detect if your code is running inside an AI agent or automated development environment.
Frequently asked questions about Agent Detector
- How do I install Laravel Agent Detector in my project?
- Run `composer require laravel/agent-detector` in your project root. The package requires PHP 8.2+ and integrates seamlessly with Laravel or standalone PHP apps. No additional setup is needed beyond installation.
- Can I use this to block AI-generated requests in my Laravel API?
- Yes. Use the `AgentDetector` class or `detectAgent()` function to check for AI agents, then implement middleware or route guards to block or redirect requests. Example: `if ($result->isAgent) abort(403);`.
- Does this work with Laravel middleware? How do I integrate it globally?
- Absolutely. Create a middleware class extending `Closure` or `Handle`, then use `AgentDetector::detect()` inside the `handle()` method. Bind it globally in `app/Http/Kernel.php` under the `$routeMiddleware` array for API-wide protection.
- What Laravel versions are supported? Will this break my existing app?
- The package is framework-agnostic but optimized for Laravel 9+. It won’t break existing apps—just install it via Composer and use the detection logic where needed. No migrations or service providers are required.
- How accurate is the detection? Are there false positives for non-AI environments?
- Detection relies on environment variables (e.g., `CURSOR_AGENT`, `GEMINI_CLI`) and is highly accurate for known agents. False positives are rare but possible if custom tools mimic these vars. Extend detection via the `AI_AGENT` env var for edge cases.
- Can I detect custom AI tools or internal scripts not listed in the package?
- Yes. Set the `AI_AGENT` environment variable to a custom value (e.g., `AI_AGENT=my-internal-tool`), and the package will recognize it. This also allows future-proofing for new agents without updates.
- How do I log or monitor AI agent detections in production?
- Use Laravel’s logging system (e.g., `logger()->info('AI Detected', ['agent' => $result->name])`) or integrate with monitoring tools like Prometheus. The package provides structured results (`isAgent`, `name`, `knownAgent()`) for easy tracking.
- Will this slow down my Laravel application? Is it performant?
- No. Detection is O(1) and executed once per request/CLI invocation via environment variable checks. It adds negligible overhead—ideal for high-traffic apps or background workers (e.g., queues).
- Are there alternatives to this package for AI detection in Laravel?
- Few. Similar packages like `spatie/ai-detector` exist but lack Laravel-native features (e.g., `KnownAgent` enum). This package is official Laravel-backed, lightweight, and extensible. For CLI-only detection, consider `symfony/process` with custom checks.
- How do I test this in a CI/CD pipeline or local development?
- Simulate AI agents by setting environment variables (e.g., `AI_AGENT=github-copilot` or `CURSOR_AGENT=true`). Test in CI by adding these vars to your pipeline config. For local testing, use `.env` files or CLI flags (e.g., `php artisan tinker --env=AI_AGENT=claude`).
Weaver
How can I help you explore Laravel packages today?