AI Agent Detector

Detect whether your Python code is running inside an AI agent (Codex, Claude, Cursor, Devin, and more).

A Python port of pushpak1300's PHP library agent-detector.

Installation

pip install ai-agent-detector

Usage

from ai_agent_detector import detect_agent

result = detect_agent()

result.is_agent       # True / False
result.name           # "codex", "claude", "cursor", … or None
result.is_known_agent # True if the agent is in the built-in list

How detection works

Detection is attempted in this order:

1. Custom agent — AI_AGENT env var

Any process can set the AI_AGENT environment variable to identify itself:

AI_AGENT=my-custom-agent python script.py

result.is_known_agent will be False for custom agents not in the built-in list.

2. Known agents — environment variables

Each known agent is detected by the presence of one or more environment variables it sets automatically:

Agent	Env vars
Amp	AMP_CURRENT_THREAD_ID
Antigravity	ANTIGRAVITY_AGENT
Augment CLI	AUGMENT_AGENT
Claude Code	CLAUDECODE, CLAUDE_CODE
Codex	CODEX_SANDBOX, CODEX_THREAD_ID
Copilot	COPILOT_CLI
Cursor	CURSOR_AGENT
Gemini CLI	GEMINI_CLI
Opencode	OPENCODE_CLIENT, OPENCODE
Replit	REPL_ID

The variable just needs to be present — its value is not checked.

3. Devin — filesystem marker

Devin does not set a dedicated env var. Instead, its presence is detected by checking for the file /opt/.devin.

Development

uv sync
uv run mypy src
uv run pytest