@vercel/detect-agent

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

Installation

``bash
npm install @vercel/detect-agent
`

Usage

`typescript
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.

$3

Set the AI_AGENT environment variable to identify your tool:

`bash
export AI_AGENT="your-tool-name"


or


AI_AGENT="your-tool-name" your-command
`

$3

- 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

$3

`typescript
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});
}
}
`

$3

`typescript
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(),
});
}
`

$3

`typescript
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.

$3

To add support for a new AI agent:

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

Links

- GitHub Repository
- npm Package
- Vercel Documentation