Package Exports

@vercel/detect-agent
@vercel/detect-agent/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@vercel/detect-agent) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@vercel/detect-agent

A lightweight utility for detecting if code is being executed by an AI agent or automated development environment.

Installation

npm install @vercel/detect-agent

Usage

import { determineAgent } from '@vercel/detect-agent';

const { isAgent, agent } = await determineAgent();

if (isAgent) {
  console.log(`Running in ${agent.name} environment`);
  // Adapt behavior for AI agent context
}

Supported Agents

This package can detect the following AI agents and development environments:

Custom agents via AI_AGENT environment variable
Cursor (cursor editor and cursor-cli)
Claude Code (Anthropic's Claude)
Devin (Cognition Labs)
Gemini CLI (Google)
Codex (OpenAI)
Replit (online IDE)

The AI_AGENT Standard

We're promoting AI_AGENT as a universal environment variable standard for AI development tools. This allows any tool or library to easily detect when it's running in an AI-driven environment.

For AI Tool Developers

Set the AI_AGENT environment variable to identify your tool:

export AI_AGENT="your-tool-name"
# or
AI_AGENT="your-tool-name" your-command

Recommended Naming Convention

Use lowercase with hyphens for multi-word names
Include version information if needed, separated by an @ symbol
Examples: claude-code, cursor-cli, devin@1, custom-agent@2.0

Use Cases

Adaptive Behavior

import { determineAgent } from '@vercel/detect-agent';

async function setupEnvironment() {
  const { isAgent, agent } = await determineAgent();

  if (isAgent) {
    // Running in AI environment - adjust behavior
    process.env.LOG_LEVEL = 'verbose';
    console.log(`🤖 Detected AI agent: ${agent.name}`);
  }
}

Telemetry and Analytics

import { determineAgent } from '@vercel/detect-agent';

async function trackUsage(event: string) {
  const result = await determineAgent();

  analytics.track(event, {
    agent: result.isAgent ? result.agent.name : 'human',
    timestamp: Date.now(),
  });
}

Feature Toggles

import { determineAgent } from '@vercel/detect-agent';

async function shouldEnableFeature(feature: string) {
  const result = await determineAgent();

  // Enable experimental features for AI agents
  if (result.isAgent && feature === 'experimental-ai-mode') {
    return true;
  }

  return false;
}

Contributing

We welcome contributions! Please see our contributing guidelines.

Adding New Agent Support

To add support for a new AI agent:

Add detection logic to src/index.ts
Add comprehensive test cases in test/unit/determine-agent.test.ts
Update this README with the new agent information
Follow the existing priority order pattern