# @vercel/detect-agent

> Detect if code is running in an AI agent or automated development environment

Latest version **1.2.5** (published 2026-08-11) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @vercel/detect-agent
pnpm add @vercel/detect-agent
yarn add @vercel/detect-agent
bun add @vercel/detect-agent
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.5 |
| Published | 2026-08-11 |
| First published | 2025-08-13 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 0 |
| Unpacked size | 22.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 16340 |
| Author | Vercel |
| Maintainers | matheuss, matt.straka, vercel-release-bot, zeit-bot |
| Keywords | ai, agent, detection, environment, cursor, claude, devin, automation, ai-agent |

## Links

- npm: https://www.npmjs.com/package/@vercel/detect-agent
- Repository: https://github.com/vercel/vercel
- Homepage: https://github.com/vercel/vercel/tree/main/packages/detect-agent#readme
- Issues: https://github.com/vercel/vercel/issues
- npm.io page: https://npm.io/package/@vercel/detect-agent

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.2.5 (latest) — 2026-08-11
- 1.2.3 (canary) — 2026-04-17
- 1.2.4 — 2026-08-03
- 1.2.2 — 2026-04-10
- 1.2.1 — 2026-03-11
- 1.2.0 — 2026-03-11
- 1.1.1 — 2026-03-09
- 1.2.0-canary.20260211174907.cdd2da6 — 2026-02-11
- 1.2.0-canary.20260211173433.cdd2da6 — 2026-02-11
- 1.1.0 — 2026-01-23
- 1.0.0 — 2025-09-22
- 0.2.0 — 2025-08-15
- 0.1.0 — 2025-08-13

## README

# @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)
- **Antigravity** (Google DeepMind)
- **GitHub Copilot** (via `AI_AGENT=github-copilot|github-copilot-cli`, `COPILOT_MODEL`, `COPILOT_ALLOW_ALL`, or `COPILOT_GITHUB_TOKEN`)
- **Replit** (online IDE)
- **v0** (Vercel's AI assistant, via `AI_AGENT=v0`)

## 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:

```bash
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

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

### Telemetry and Analytics

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

### Feature Toggles

```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](../../CONTRIBUTING.md).

### Adding New Agent Support

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](https://github.com/vercel/vercel/tree/main/packages/detect-agent)
- [npm Package](https://www.npmjs.com/package/@vercel/detect-agent)
- [Vercel Documentation](https://vercel.com/docs)

---
_Source: https://npm.io/package/@vercel/detect-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._