Weave Code
Agent Detector Laravel Package
shipfastlabs/agent-detector
Lightweight PHP utility that detects whether your code is running inside an AI agent or automated dev environment. Identify Claude, Cursor, Gemini, Codex and more via env vars or a standalone detectAgent() helper.
Laravel Agent Detector is a lightweight PHP utility that tells your code whether it is running inside an AI agent or automated development environment. A single AgentDetector::detect() call returns a result exposing isAgent, the detected agent's name, and a knownAgent() helper for comparing against supported agents such as Claude, Cursor, Gemini, and Codex.
- Zero-configuration detection through environment variables
- Fluent result object with
isAgent,name, andknownAgent() KnownAgentenum for type-safe comparisons- Standalone
detectAgent()helper function - Requires PHP 8.2+ and installs via Composer
Frequently asked questions about Agent Detector
- What does the laravel/agent-detector package actually do?
- Agent Detector is a lightweight PHP utility that tells you whether your code is running inside an AI agent or automated development environment. It inspects environment variables and filesystem markers set by tools like Claude, Cursor, Gemini, Codex, Cline, Goose, Junie, Grok, Kimi, and OpenClaw. You get back a result object with an isAgent flag, the detected name, and an optional KnownAgent enum value for type-safe comparisons.
- How do I install agent-detector in a Laravel application?
- Install it with Composer by running composer require laravel/agent-detector. There are no service providers, migrations, config files, or middleware to publish, so installation is complete after the require command. The package requires PHP 8.2 or higher.
- Which Laravel and PHP versions are supported?
- The only hard requirement is PHP 8.2+, which means any modern Laravel release (Laravel 10, 11, and 12 applications) will satisfy it. The package is also framework-agnostic, so it works in plain PHP projects and other frameworks. If you are still on PHP 8.1 or older, you would need to upgrade before installing.
- How do I use agent-detector to check if my code is running inside Claude or Cursor?
- Call the static detect method on AgentDetector, or use the detectAgent helper function, and inspect the returned result. Check the isAgent property to know whether any agent was detected, then compare result->knownAgent() against an enum case such as KnownAgent::Claude. The enum gives you autocompletion and avoids stringly-typed comparisons.
- Does agent-detector work with custom or internal AI agents?
- Yes. If an agent is not on the built-in supported list, you can set the AI_AGENT environment variable and the detector will report it as a custom agent. This makes the package forward-compatible with internal tooling or newly released assistants that have not yet been added upstream. You can also open a pull request to add first-class support for a widely used agent.
- How does the detection mechanism work under the hood?
- Detection is performed by reading well-known environment variables, such as CURSOR_AGENT for Cursor, GEMINI_CLI for Gemini, and CODEX_SANDBOX or CODEX_THREAD_ID for Codex, plus a few lightweight filesystem checks. No processes are spawned, no network calls are made, and no runtime hooks are installed. Each check is effectively constant time, so the cost per request or CLI invocation is negligible.
- Will agent-detector slow down my Laravel requests?
- No measurable impact is expected. The checks are simple environment variable lookups that resolve in constant time, and nothing is written to disk or cached at boot. Even with the additional agents added in recent releases, the number of lookups remains small and fixed per invocation.
- Can I use agent-detector in middleware to block or log AI-generated requests?
- Yes, that is a common pattern. You can call AgentDetector::detect() inside a middleware, controller, form request, or Artisan command and then decide whether to allow, block, or log the request. Because the class is stateless and cheap to call, you can safely resolve or bind it as a singleton in the container if you prefer dependency injection.
- How accurate is agent-detector, and what about false positives or false negatives?
- Accuracy depends entirely on the environment variables each tool sets, so a custom or heavily reconfigured agent may go undetected. The AI_AGENT environment variable provides an escape hatch for anything not covered by the built-in list. If precise detection matters for security decisions, treat the result as one signal among several rather than an absolute guarantee.
- Is the package actively maintained, and are there alternatives?
- The package is maintained under the laravel GitHub organization with active test workflows and frequent additive releases that onboard new agents, such as the six agents added in version 2.0.4. Upgrades within the 2.x line have been non-breaking, and the last breaking change was the 2.0.0 namespace update. Alternatives exist, but most are framework-specific or heavier; Agent Detector's advantage is its zero-configuration, dependency-free design.
Weaver
How can I help you explore Laravel packages today?