Weave Code
Agent Detector Laravel Package
ergebnis/agent-detector
Detect whether your PHP code is running under an AI agent. This Composer package checks environment variables for 30+ agents like Claude Code, Codex, Cursor, and Copilot, exposing a simple Detector class with one isAgentPresent() method.
ergebnis/agent-detector is a lightweight Composer package that detects whether your PHP code is running inside an AI coding agent or automated environment. Pass it an environment array (typically \getenv()) and the Detector reports whether a supported agent is present—ideal for adapting behavior, logging, or gating features in CI and agent-driven workflows.
- Simple API: instantiate
AgentDetector\Detectorand callisAgentPresent() - Recognizes popular agents such as Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and more
- Detection via well-known environment variables, no configuration required
- Zero-friction install with Composer; strictly typed, testable PHP
Frequently asked questions about Agent Detector
- How do I install ergebnis/agent-detector in a Laravel application?
- Run composer require ergebnis/agent-detector. The package requires PHP 8.2 or newer and has no framework dependencies, so it installs cleanly alongside your existing Composer packages. There is no service provider to register, you can start using the Detector class immediately.
- How does Detector::isAgentPresent() actually detect an AI agent?
- Instantiate Ergebnis\AgentDetector\Detector and pass an array of environment variables, typically getenv(), to isAgentPresent(). The detector checks for known agent-specific variables such as CLAUDECODE, CODEX_CI, CURSOR_AGENT, GEMINI_CLI, and COPILOT_CLI, plus a generic AI_AGENT flag. It returns a boolean and performs no database calls, external API requests, or runtime hooks.
- Which AI coding agents does ergebnis/agent-detector support?
- It detects Claude Code, OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot, Amp, Antigravity, and Augment, each through their documented environment variables. It also recognizes a generic AI_AGENT variable so unknown or future tools can opt in without a package release. Additional agents are added in upstream releases.
- How can I use agent-detector in Laravel middleware?
- Create a middleware class, resolve or instantiate Ergebnis\AgentDetector\Detector, and call isAgentPresent($_SERVER) inside handle(). Then branch on the result, for example logging, rate-limiting, or calling abort(403) for agent traffic before returning $next($request). Register the middleware globally in bootstrap/app.php or attach it to specific routes.
- Does ergebnis/agent-detector work with Laravel 9, 10, 11, and 12?
- The package targets PHP 8.2+ and contains no Laravel-specific code, so it works with any Laravel version running on a supported PHP release, which in practice means Laravel 10 and later. It also works in Lumen, Symfony, Slim, or standalone PHP scripts. Only the environment variables need to be available to the PHP process.
- Can I bind the Detector in Laravel's service container?
- Yes. Register it in a service provider, for example $this->app->singleton(Detector::class), then inject Ergebnis\AgentDetector\Detector into controllers, middleware, listeners, or jobs via constructor dependency injection. The class is stateless and does no I/O, so a singleton binding is safe across concurrent requests.
- How do I unit test code that uses the Detector?
- Because isAgentPresent() accepts the environment array as an argument, you can pass arrays like ['CLAUDECODE' => '1'] or an empty array in PHPUnit and assert the boolean result, without touching real environment variables. This keeps detection logic deterministic and easy to cover in Laravel feature or unit tests.
- Is there any performance overhead from calling isAgentPresent()?
- The check is a pure in-memory lookup over an array of environment variables and typically completes in well under a millisecond. If you need the result in several places during one request, resolve the Detector once and store the boolean. For long-running workers or queued jobs where the environment is fixed, caching the result avoids repeated checks.
- What happens if my AI agent is not detected, or if I get false positives?
- If an agent sets none of the known variables, detection returns false; you can set the generic AI_AGENT variable or extend the check with your own variables. False positives can occur when unrelated tooling sets similarly named environment variables, so log detection results before enforcing hard blocks. Missing agents can be added by submitting an upstream pull request.
- Does ergebnis/agent-detector have dependencies, and is it production safe?
- It has no transitive runtime dependencies beyond PHP core and is stateless, which makes it safe for production monoliths and high-traffic APIs. Pin a major version in composer.json and review release notes for new agent coverage. Building your own environment checks is an alternative, but you would lose the maintained agent variable list.
Weaver
How can I help you explore Laravel packages today?