Metadata-Version: 2.3
Name: ai-agent-detector
Version: 0.2.0
Summary: A library to detect if Python code is run inside an agent
Author: Einenlum
Author-email: Einenlum <contact@einenlum.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# AI Agent Detector

[![Tests](https://github.com/einenlum/ai-agent-detector/actions/workflows/tests.yml/badge.svg)](https://github.com/einenlum/ai-agent-detector/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

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

> A Python port of [pushpak1300](https://github.com/pushpak1300)'s PHP library [agent-detector](https://github.com/shipfastlabs/agent-detector).

## Installation

```bash
pip install ai-agent-detector
```

## Usage

```python
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:

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

```bash
uv sync
uv run mypy src
uv run pytest
```
