Agent Detector Laravel Package

Product Decisions This Supports

• Agent-aware product behavior. The detector answers one boolean question — "is an AI coding agent driving this process?" — from environment variables set by Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Replit, and others. That single signal lets you branch product behavior: skip interactive confirmations and TTY prompts, emit JSON instead of human-formatted output, change error verbosity, or adjust default timeouts for non-interactive runs.
• Attribution and usage analytics. Tag events, requests, and CLI invocations as agent-originated to measure how much of your traffic is machine-driven versus human-driven. This informs roadmap prioritization (is investing in an MCP server, agent-friendly docs, or a headless API worth it?) with data instead of anecdotes.
• Safety guardrails for autonomous execution. When an agent is present, default destructive Artisan commands to --dry-run, tighten rate limits, require explicit opt-in flags, or enrich audit logs. This is a cheap risk-mitigation lever for teams shipping tools that agents can invoke unattended.
• Packaging and licensing decisions. Distinguishing agent sessions from human sessions supports decisions about seat counting, tiering, per-agent quotas, or terms-of-service language — before those decisions become expensive to retrofit.
• Build vs. buy. The underlying logic is a list of env-var string checks. Adopting this package is not really a technology bet; it's a bet that a maintained, curated agent list is worth more than ~50 lines of our own code. With 24 stars and zero dependents, treat it as a convenience wrapper, not infrastructure.
• QA and test-environment handling. Detect agent- or CI-driven runs to adjust fixtures, snapshots, or test isolation behavior in automated pipelines.

When to Consider This Package

Adopt when:

• You ship a PHP CLI, developer tool, SDK, or code-generation workflow that agents actually invoke, and you want a deterministic, zero-cost signal without inventing your own taxonomy.
• You want a curated, actively refreshed list of agent environment variables (releases in 2025–2026 added Cursor, Copilot CLI, and Pi detection) rather than owning that churn.
• Broad PHP compatibility matters: 7.4 through 8.6 is supported, which fits legacy Laravel estates still on older runtimes.
• MIT licensing and a near-zero dependency footprint clear your supply-chain review.
• The signal is used for soft decisions: telemetry enrichment, output formatting, logging context, UX hints.

Look elsewhere when:

• You need to know which agent, its version, or its capabilities. The public API is a single isAgentPresent() boolean; the agent table is internal. Any need for per-agent branching, identity, or auth requires building on top or going elsewhere.
• The request path is hosted/SaaS rather than a local process. Environment variables do not survive an HTTP hop — you need headers, tokens, or user-agent parsing instead.
• You require SLAs, vendor support, or a multi-maintainer project. The README explicitly states a limited support policy, and the package is effectively single-maintainer with no downstream dependents to signal production hardening.
• You're not on PHP — port the env-var list or use the upstream inspiration, shipfastlabs/agent-detector.
• The detection would gate security, billing enforcement, or access control. Env vars are trivially spoofable by the caller; never make this an authorization boundary.
• Note on framing: despite the "Laravel/PHP package" label, this is framework-agnostic — no service provider, facade, config file, or Artisan integration. Budget a small internal adapter (container binding + your own interface) as part of the adoption cost.

How to Pitch It (Stakeholders)

To executives (30 seconds): We can now tell, cheaply and reliably, when an AI coding agent is driving our PHP tooling instead of a human. That unlocks three things: real data on how much agent-driven usage we have, safer defaults when an agent runs something unattended, and the option to package or price agent access differently later. Cost is one Composer dependency, MIT-licensed, no runtime dependencies, roughly a day of integration.

To engineering (2 minutes): composer require ergebnis/agent-detector, instantiate Detector, call isAgentPresent(getenv()). It checks a maintained set of environment variables across Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Replit, and more, plus a generic AI_AGENT escape hatch. Integration pattern: bind it behind our own AgentContext interface in a service provider, resolve via the container, and consume that interface everywhere. Do not type against Ergebnis\AgentDetector\Detector in domain code — it's a five-minute swap if we ever replace it, and we want that optionality preserved.

Risks and mitigations to state plainly: single maintainer, limited support policy, zero dependents, and an API surface that returns only a boolean. Mitigate by (1) wrapping it, (2) restricting it to non-critical paths initially, and (3) treating spoofability as a given — it informs behavior, it does not enforce policy.

Recommendation: Run a two-sprint pilot scoped to telemetry attribution and CLI output formatting. If agent-originated usage turns out to be material, escalate to a product decision on agent-specific UX and packaging; if it's noise, we've spent a day and learned something concrete.