Agent Detector Laravel Package

Product Decisions This Supports

Agent-aware product behavior. Once you can answer "is this code being executed by an AI agent, and which one?", a whole class of product decisions becomes implementable rather than theoretical:

• Output mode switching. Emit machine-readable output (JSON, stable exit codes, no ANSI/spinners) when an agent is driving the CLI, and human-friendly output otherwise. This is the single highest-value use case for any Laravel Artisan/CLI surface you ship.
• Interaction policy. Suppress interactive prompts, confirmations, and pagination when no human is present; escalate to a hard failure with actionable instructions instead of hanging on STDIN.
• Guardrails and approvals. Gate destructive operations (migrations, deletes, deploys, credential changes) behind an explicit human-in-the-loop check when isAgent is true. This is a defensible safety story for security reviews and enterprise procurement.
• Telemetry segmentation. Tag analytics, error reports, and support tickets with agent name versus human. Without this, your activation and retention metrics silently conflate agent-driven automation with human usage — a real measurement-risk for any product with a CLI or SDK.
• Rate limiting, quotas, and abuse handling. Agent traffic looks like bot traffic but isn't malicious. Detecting it lets you throttle or price it deliberately instead of discovering it in an incident review.
• Docs and onboarding routing. Serve agent-oriented quickstarts (non-interactive examples, full-flag invocations) to agents and human-oriented tutorials to people.

Roadmap input. The supported-agent table is a free, continuously updated census of which coding agents developers are actually using. Monitoring its changelog over a few quarters is a cheap signal for "should we be agent-native yet, and for whom?" — Claude, Cursor, Copilot, Codex, Gemini, plus a long tail (Amp, Opencode, Devin, Replit, Kiro, Goose, Cline, Junie, OpenClaw).

Build vs. buy. The detection logic is trivial — a dozen environment-variable checks and one file-existence probe. The non-trivial asset is the maintained fingerprint registry: ~25 agents, community PRs adding new ones within weeks of launch, first-party Laravel namespace. You are buying a maintained taxonomy, not code. That justifies a dependency; it does not justify a build.

When to Consider This Package

Adopt when:

• You ship a CLI, Artisan command set, installer, or developer SDK where a hung interactive prompt or human-formatted output actively breaks agent workflows.
• You have a safety, audit, or compliance requirement to distinguish agent-initiated actions from human ones.
• You need agent-vs-human segmentation in product analytics and it's cheaper to tag at the source than to infer downstream.
• You're already on PHP 8.2+ / Laravel and the cost of a composer require is genuinely zero.

Look elsewhere or hold when:

• You need certainty. Detection is heuristic and self-declared: it reads environment variables and marker files. Any agent that doesn't set them is invisible; any process that sets them can impersonate. Do not use this as a security control — use it as a signal, and pair any hard gate with a real authorization check.
• You need cross-language coverage. This is PHP-only. A polyglot stack needs per-language equivalents or an in-house convention (see below).
• Signal quality is weak. With 92 stars, zero dependents, and a v2.0.0 that broke the namespace, this is unproven in production anywhere. Treat it as a thin, replaceable adapter — wrap it behind your own EnvironmentContext::isAgent() interface so swapping it out (or absorbing it into your own code) is a one-file change.
• You're in a regulated or privacy-sensitive context where reporting a third-party vendor identifier in telemetry needs a disclosure review first.
• Your real problem is "is this automated?" — CI runners, cron, and headless scripts dominate that population, and this package explicitly does not answer it.

Mitigation for the fingerprint risk: pair adoption with the AI_AGENT custom variable, which lets your own agents, internal tooling, and CI self-identify deterministically. That converts a best-effort heuristic into a reliable contract for the traffic you control.

How to Pitch It (Stakeholders)

One line: A small first-party Laravel utility that tells our code whether it's being executed by an AI coding agent — and which one — so we can behave correctly when no human is watching.

For executives: Agent-driven development is becoming a normal way our users and our own engineers touch our product, and right now we can't tell it apart from human usage in our metrics or our logs. This package is a low-cost, MIT-licensed, zero-infrastructure way to close that blind spot: it lets us stop agent runs from hanging on prompts, add human-approval gates before destructive actions, and separate agent traffic from human traffic in analytics and quotas. Cost is a Composer dependency and a few conditional branches; risk is contained because it's a heuristic signal we wrap in our own interface and can replace in an afternoon.

For engineering: Adopt laravel/agent-detector behind an internal EnvironmentContext abstraction. Two integration points to start: (1) a global "non-interactive mode" that disables prompts and emits structured output whenever an agent is detected, and (2) an audit tag on log entries and jobs recording agent name. Set AI_AGENT in our own CI and internal agents so our own automation is deterministic rather than dependent on vendor fingerprinting. Explicitly do not use it for authorization — detection is spoofable, so any destructive-action gate must also check real permissions. Budget a small maintenance allowance: the upstream agent list changes monthly, so pin a minor version, review the changelog on upgrade, and keep the adapter under ~50 lines so replacing it — or vendoring the env-var table ourselves — is trivial if the package stalls.