ai-agent-detector 0.2.0

A library to detect if Python code is run inside an agent

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