Detect if code is running in an AI agent or automated development environment
npm install @vercel/detect-agentA lightweight utility for detecting if code is being executed by an AI agent or automated development environment.
``bash`
npm install @vercel/detect-agent
`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
}
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)
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.
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
- Use lowercase with hyphens for multi-word names
- Include version information if needed, separated by an @ symbolclaude-code
- Examples: , cursor-cli, devin@1, custom-agent@2.0
`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});`
}
}
`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(),
});
}
`
`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;
}
`
We welcome contributions! Please see our contributing guidelines.
To add support for a new AI agent:
1. Add detection logic to src/index.tstest/unit/determine-agent.test.ts`
2. Add comprehensive test cases in
3. Update this README with the new agent information
4. Follow the existing priority order pattern