Weave Code
Agent Detector Laravel Package
shipfastlabs/agent-detector
Lightweight PHP/Laravel utility to detect when your code runs inside an AI agent or automated dev environment. Checks common agent-specific environment variables (e.g., Cursor, Gemini, Codex, or custom) and returns agent status and name.
Detect if code is running in an AI agent or automated development environment
Frequently asked questions about Agent Detector
- How do I integrate this package into Laravel middleware for request-level agent detection?
- Create a middleware class extending `Closure` or `Middleware`, then call `AgentDetector::detect()` in the `handle` method. Attach it to your middleware group in `app/Http/Kernel.php`. This injects agent metadata into every request for conditional logic.
- Does this package support custom AI agents not listed in the KnownAgent enum?
- Yes. Set the `AI_AGENT` environment variable to your agent’s identifier, and the package will detect it as a custom agent. This is useful for internal tools or third-party agents not yet in the default list.
- Will this work in Laravel 9.x, or is PHP 8.2+ required?
- The package requires PHP 8.2+, so it’s fully compatible with Laravel 10.x and 11.x. Laravel 9.x uses PHP 8.1+, which may cause compatibility issues. Check your Laravel version before installing.
- Can I use this in Artisan commands or CLI scripts, not just web requests?
- Absolutely. The package includes a standalone `detectAgent()` function that works in any context—Artisan commands, cron jobs, or even standalone PHP scripts. It checks environment variables and filesystem markers just like in web requests.
- How accurate is the detection, and what are the false positive risks?
- Detection relies on environment variables and filesystem checks, which are highly reliable for known agents like Cursor or Claude. False positives are rare but possible if an agent doesn’t set expected env vars. Custom agents or edge cases may require additional logic.
- Should I use middleware or a service provider for global agent detection?
- Middleware is ideal for request-scoped detection (e.g., tagging requests with agent metadata). Use a service provider if you need the detector instance globally, like in controllers or repositories. Both approaches are lightweight and non-intrusive.
- How do I test agent-specific behavior in PHPUnit?
- Mock environment variables using `putenv()` or Laravel’s `actingAs()` with custom env configs. For example, set `putenv('CURSOR_AGENT=1')` before running tests. The package’s `KnownAgent` enum makes assertions straightforward.
- Are there performance concerns with this package in high-traffic Laravel apps?
- No. The package performs stateless environment variable checks (O(1) operations) and has negligible overhead. Benchmark in production if critical, but it’s designed for minimal impact even in high-throughput environments.
- What’s the best way to handle agent detection in API rate limiting or security rules?
- Use middleware to tag requests with agent metadata, then apply conditional logic in your rate-limiting middleware or policy classes. For example, throttle Claude requests differently than web users by checking `$request->agent`.
- Are there alternatives to this package for AI agent detection in Laravel?
- Few packages specialize in AI agent detection, but you could manually check env vars or use browser fingerprinting libraries like `spatie/ray`. However, this package is optimized for Laravel’s ecosystem with enums, middleware, and CLI support.
Weaver
How can I help you explore Laravel packages today?