Weave Code
Agent Detector Laravel Package
ergebnis/agent-detector
Detect the presence of coding agents in your PHP app by checking environment variables. Supports Amp, Antigravity, Augment, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and more via a simple Detector::isAgentPresent() API.
🤖 Provides a composer package with a detector for detecting the presence of an agent.
Frequently asked questions about Agent Detector
- How do I install ergebnis/agent-detector in a Laravel project?
- Run `composer require ergebnis/agent-detector` in your project root. The package has no Laravel-specific dependencies and works in any PHP 8.2+ app, including vanilla PHP or other frameworks.
- Does this package work with Laravel middleware for blocking agents?
- Yes. Use the `Detector` class in a middleware (e.g., `BotGuardMiddleware`) to check `$_ENV` or Laravel’s config array. Example: `if ($detector->isAgentPresent($_ENV)) return response('Forbidden', 403);` in `handle()`.
- Which Laravel versions does ergebnis/agent-detector support?
- The package supports PHP 8.2–8.6, which aligns with Laravel 9+ (PHP 8.0+) and Laravel 10/11. For older Laravel versions, upgrade PHP first, as the package requires PHP 8.2+ features.
- Can I extend the package to detect custom agents or internal tools?
- Yes. The `Detector` class is designed for extensibility. Override the `isAgentPresent()` method or use a decorator pattern to add custom checks for environment variables or internal tooling.
- How accurate is agent detection? Will it block legitimate CI/CD tools?
- Detection relies on environment variables, which can be spoofed. For higher accuracy, combine with user-agent parsing (e.g., `spatie/browsershot`) or IP reputation tools. Exclude known CI/CD variables (e.g., `REPL_ID` for Replit) in your rules.
- Does this package work in serverless environments (AWS Lambda, etc.)?
- Yes. The package uses `getenv()` or accepts custom environment arrays, making it compatible with serverless functions, Docker/Kubernetes, and Laravel Forge. Pass your environment variables directly to `isAgentPresent($envArray)`.
- How do I test this package in Laravel unit tests?
- Mock `getenv()` or inject a custom environment array into the `Detector` constructor. Example: `$detector = new Detector(['COPILOT_CLI' => 'true']);`. Use PHPUnit’s `setEnv()` or `putenv()` for simpler cases.
- What are the performance implications of using this package?
- The package has negligible overhead (O(1) environment variable inspection). Benchmark in high-traffic Laravel APIs if latency is critical, but it’s safe for most use cases like middleware or feature flags.
- Are there alternatives to ergebnis/agent-detector for Laravel?
- For broader bot detection, consider `spatie/browsershot` (user-agent parsing) or `laravel-fingerprint` (browser fingerprinting). However, this package is specialized for AI coding agents via environment variables, offering a lightweight solution.
- How do I integrate this with Laravel’s service container for dependency injection?
- Register the `DetectorServiceProvider` in `config/app.php` and bind the `Detector` class. Then inject `Detector` into controllers or services via constructor injection. Example: `public function __construct(private Detector $detector) {}`.
Weaver
How can I help you explore Laravel packages today?