Weave Code
Agent Detector Laravel Package
laravel/agent-detector
Laravel Agent Detector is a lightweight PHP 8.2+ utility for detecting whether your code runs inside an AI agent or automated development environment, with known-agent checks and a simple standalone detectAgent() helper.
Detect if code is running in an AI agent or automated development environment
Frequently asked questions about Agent Detector
- How do I install laravel/agent-detector in a Laravel app?
- Run composer require laravel/agent-detector on PHP 8.2 or newer. There is nothing else to do: the package ships no service provider, no config file to publish, and no migrations, so installation is complete once Composer finishes. You then call Laravel\AgentDetector\AgentDetector::detect() or the namespaced detectAgent() helper wherever you need a decision.
- Does laravel/agent-detector work in HTTP requests or only in CLI?
- Detection is environment based, so it is reliable in CLI processes such as artisan commands, Composer scripts, queue workers, seeders and CI jobs that inherit the agent environment. In FPM or Octane request handling, environment variables come from the web server or supervisor pool config, so a browser request routed through an AI proxy will not be detected. Treat it as a CLI-side primitive and do not build plans that assume the app knows an HTTP request came from an agent.
- What PHP and Laravel versions does laravel/agent-detector support?
- The package requires PHP 8.2 or higher and is MIT licensed. It is architecturally inert, meaning it works in Laravel 10, 11 and 12 applications, in bare PHP scripts, and in any Composer project, because it has no framework bootstrapping, database, HTTP client or queue integration. The only runtime dependency is the Composer autoloader.
- How do I detect a specific AI agent such as Claude, Cursor or Codex?
- Call AgentDetector::detect() and compare the result against the KnownAgent enum, for example $result->knownAgent() === KnownAgent::Claude. The AgentResult also exposes isAgent, name and label(), which are useful for logging or display. If you only need a boolean, prefer isAgent, because comparing against KnownAgent ties your code to the vendor list that changes between releases.
- Is laravel/agent-detector safe to use for authentication or access control?
- No. Detection relies on environment variable presence and values plus a filesystem check, and variables such as AI_AGENT, CURSOR_AGENT or CLAUDECODE can be set by anyone. Use it only as a hint that alters user experience, logging, telemetry provenance or non-destructive defaults. Never gate permissions, billing or security decisions on isAgent.
- How do I test code that calls AgentDetector::detect()?
- Because there are no container bindings or config values to swap, the simplest approach is to set the relevant environment variables with putenv() or by writing to $_ENV and $_SERVER before calling detect(), then unset them in tearDown. If your PHP configuration caches environment lookups, run the affected test in a separate process. Always assert both the agent and non-agent branches, since the safe default matters when detection is wrong.
- What environment variables and signals does AgentDetector check?
- It looks for vendor-specific variables such as AI_AGENT, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, CODEX_CI, CODEX_THREAD_ID and CLAUDECODE, plus a filesystem check for /opt/.devin used by Devin. These signals are undocumented vendor implementation details, so they can change without notice. Minor releases regularly add new agents and refine existing checks, which means runtime behaviour can shift without an API change.
- Can I use laravel/agent-detector outside Laravel, in a plain PHP script or Composer script?
- Yes. The package is a plain PHP utility with no Laravel dependencies beyond the autoloader, so a standalone script, a Composer post-install hook or a CI shell step can call detectAgent() directly after requiring the Composer autoloader. This is often the most useful context, because build and deployment scripts are exactly where automated environments appear.
- How do I skip destructive or interactive artisan commands when an AI agent is running?
- Call AgentDetector::detect() early in the command handle method and return an explanatory message or require an explicit --force flag when isAgent is true. You can also use the result to suppress prompts, colours and progress bars that produce noise in an agent transcript, and to skip rate-limited external API calls. Decide in advance what the safe default is when detection is wrong in either direction.
- Is laravel/agent-detector actively maintained, and should I write my own helper instead?
- The package is now first-party under the laravel organisation after transferring from shipfastlabs, which materially lowers abandonment risk, and it ships frequent releases adding agents such as Kimi, Grok, Cline, Goose, Junie, Kiro and Antigravity. A five-line internal helper reading AI_AGENT and a couple of documented variables delivers most of the value with no dependency, so the package earns its place mainly through a maintained detection matrix. If you only need a boolean, the dependency is cheap; if you need per-agent granularity, budget time for upgrades.
Weaver
How can I help you explore Laravel packages today?