agent-detector 1.0.0__py3-none-any.whl

agent_detector/__init__.py

@@ -0,0 +1,17 @@
+from agent_detector._detector import (
+    KNOWN_AGENTS,
+    AgentConfidence,
+    AgentName,
+    DetectionResult,
+    DetectionSource,
+    detect_agent,
+)
+
+__all__ = [
+    "KNOWN_AGENTS",
+    "AgentConfidence",
+    "AgentName",
+    "DetectionResult",
+    "DetectionSource",
+    "detect_agent",
+]

agent_detector/_detector.py

@@ -0,0 +1,171 @@
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Literal, Optional, cast
+
+AgentConfidence = Literal["high", "medium", "low"]
+DetectionSource = Literal["environment", "path"]
+AgentName = Literal[
+    "amp",
+    "antigravity",
+    "augment-cli",
+    "claude-code",
+    "codex",
+    "copilot-cli",
+    "cowork",
+    "cursor",
+    "cursor-cli",
+    "gemini-cli",
+    "goose",
+    "kiro",
+    "opencode",
+    "pi",
+    "replit",
+]
+
+KNOWN_AGENTS: frozenset[AgentName] = frozenset(
+    {
+        "amp",
+        "antigravity",
+        "augment-cli",
+        "claude-code",
+        "codex",
+        "copilot-cli",
+        "cowork",
+        "cursor",
+        "cursor-cli",
+        "gemini-cli",
+        "goose",
+        "kiro",
+        "opencode",
+        "pi",
+        "replit",
+    }
+)
+
+_PI_AGENT_PATH = re.compile(r"(?:^|[\\/])\.pi[\\/]agent(?:[\\/]|$)")
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    """Evidence that an AI coding agent is driving the current process."""
+
+    agent: AgentName
+    confidence: AgentConfidence
+    source: DetectionSource
+    signal: str
+
+
+def detect_agent(
+    environ: Optional[Mapping[str, str]] = None,
+    *,
+    minimum_confidence: AgentConfidence = "low",
+) -> Optional[DetectionResult]:
+    """Detect the AI coding agent driving the current process, if any.
+
+    Detection is best-effort. A ``None`` result means "unattributed", not "human".
+
+    Values from the environment are inspected locally but are never included in
+    the returned result.
+    """
+
+    values = os.environ if environ is None else environ
+
+    if minimum_confidence not in ("high", "medium", "low"):
+        raise ValueError("minimum_confidence must be 'high', 'medium', or 'low'")
+
+    confidence_order: tuple[AgentConfidence, ...] = ("high", "medium", "low")
+    minimum_confidence_index = confidence_order.index(minimum_confidence)
+    candidates: list[DetectionResult] = []
+
+    # An explicit known identity is checked before inferred signals.
+    explicit_agent = values.get("AI_AGENT", "")
+    if explicit_agent in KNOWN_AGENTS:
+        candidates.append(
+            DetectionResult(cast(AgentName, explicit_agent), "high", "environment", "AI_AGENT")
+        )
+
+    # Amp sets CLAUDECODE too, so its more specific signals must win.
+    if values.get("AGENT") == "amp":
+        candidates.append(DetectionResult("amp", "high", "environment", "AGENT"))
+    if values.get("AMP_CURRENT_THREAD_ID"):
+        candidates.append(DetectionResult("amp", "medium", "environment", "AMP_CURRENT_THREAD_ID"))
+
+    # OpenAI Codex CLI.
+    for signal in ("CODEX_THREAD_ID", "CODEX_CI", "CODEX_SANDBOX"):
+        if values.get(signal):
+            candidates.append(DetectionResult("codex", "high", "environment", signal))
+
+    # Google Gemini CLI.
+    if values.get("GEMINI_CLI"):
+        candidates.append(DetectionResult("gemini-cli", "high", "environment", "GEMINI_CLI"))
+
+    # GitHub Copilot CLI. This signal is observed but not publicly documented.
+    if values.get("COPILOT_CLI"):
+        candidates.append(DetectionResult("copilot-cli", "medium", "environment", "COPILOT_CLI"))
+
+    # OpenCode sets OPENCODE for the running agent. OPENCODE_CLIENT and
+    # OPENCODE_CALLER identify its launcher, so they are intentionally ignored.
+    if values.get("OPENCODE"):
+        candidates.append(DetectionResult("opencode", "high", "environment", "OPENCODE"))
+
+    if values.get("ANTIGRAVITY_AGENT"):
+        candidates.append(
+            DetectionResult("antigravity", "medium", "environment", "ANTIGRAVITY_AGENT")
+        )
+
+    if values.get("AUGMENT_AGENT"):
+        candidates.append(DetectionResult("augment-cli", "medium", "environment", "AUGMENT_AGENT"))
+
+    # Cowork and Claude Code share ambient Claude markers. Check Cowork first.
+    if values.get("CLAUDE_CODE_IS_COWORK"):
+        candidates.append(DetectionResult("cowork", "high", "environment", "CLAUDE_CODE_IS_COWORK"))
+
+    # This specifically marks commands spawned by Claude Code.
+    if values.get("CLAUDE_CODE_CHILD_SESSION"):
+        candidates.append(
+            DetectionResult("claude-code", "high", "environment", "CLAUDE_CODE_CHILD_SESSION")
+        )
+
+    # These can also exist in Claude's integrated terminal, so they carry less
+    # confidence than the child-session signal.
+    for signal in ("CLAUDECODE", "CLAUDE_CODE"):
+        if values.get(signal):
+            candidates.append(DetectionResult("claude-code", "medium", "environment", signal))
+
+    # Cursor IDE and Cursor CLI are distinguishable when both signals exist.
+    if values.get("CURSOR_TRACE_ID"):
+        candidates.append(DetectionResult("cursor", "medium", "environment", "CURSOR_TRACE_ID"))
+
+    if values.get("CURSOR_AGENT"):
+        candidates.append(DetectionResult("cursor-cli", "high", "environment", "CURSOR_AGENT"))
+
+    if values.get("CURSOR_EXTENSION_HOST_ROLE") == "agent-exec":
+        candidates.append(
+            DetectionResult("cursor-cli", "medium", "environment", "CURSOR_EXTENSION_HOST_ROLE")
+        )
+
+    # The following signals are broader or have less first-party evidence, so
+    # they are checked only after the more specific agent signals above.
+    if values.get("TERM_PROGRAM") == "kiro":
+        candidates.append(DetectionResult("kiro", "low", "environment", "TERM_PROGRAM"))
+
+    path = values.get("PATH", "")
+    if _PI_AGENT_PATH.search(path):
+        candidates.append(DetectionResult("pi", "medium", "path", "PATH"))
+
+    if values.get("REPL_ID"):
+        candidates.append(DetectionResult("replit", "low", "environment", "REPL_ID"))
+
+    if values.get("GOOSE_PROVIDER"):
+        candidates.append(DetectionResult("goose", "low", "environment", "GOOSE_PROVIDER"))
+
+    return next(
+        (
+            candidate
+            for candidate in candidates
+            if confidence_order.index(candidate.confidence) <= minimum_confidence_index
+        ),
+        None,
+    )

agent_detector/py.typed

@@ -0,0 +1 @@
+

agent_detector-1.0.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: agent-detector
+Version: 1.0.0
+Summary: Detect AI coding agents from their execution environment
+Project-URL: Homepage, https://github.com/patrick91/agent-detector
+Project-URL: Repository, https://github.com/patrick91/agent-detector
+Project-URL: Issues, https://github.com/patrick91/agent-detector/issues
+Author: Patrick Arminio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude,cli,codex,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Agent Detector
+
+`agent-detector` is a small, dependency-free Python package for detecting which
+AI coding agent is driving the current process.
+
+It returns evidence rather than only a boolean, so callers can distinguish an
+explicit identity from a broad environmental hint.
+
+## Installation
+
+```bash
+pip install agent-detector
+```
+
+## Usage
+
+```python
+from agent_detector import detect_agent
+
+detection = detect_agent()
+
+if detection:
+    print(detection.agent)       # "codex"
+    print(detection.confidence)  # "high"
+    print(detection.signal)      # "CODEX_THREAD_ID"
+```
+
+The returned `DetectionResult` contains:
+
+- `agent`: an `AgentName` literal containing a supported agent name
+- `confidence`: `high`, `medium`, or `low`
+- `source`: `environment` or `path`
+- `signal`: the name of the matched signal, never its value
+
+Pass a mapping to make detection deterministic in tests:
+
+```python
+assert detect_agent({"OPENCODE": "1"}).agent == "opencode"
+```
+
+Require a minimum confidence when broad environmental hints are not useful:
+
+```python
+detection = detect_agent(minimum_confidence="high")
+```
+
+`minimum_confidence` is typed as `Literal["high", "medium", "low"]` and
+defaults to `"low"`.
+
+## Supported agents
+
+| Agent | Signals | Confidence |
+| --- | --- | --- |
+| Explicit override | `AI_AGENT` containing a supported agent name | high |
+| Amp | `AGENT=amp`, `AMP_CURRENT_THREAD_ID` | high / medium |
+| Codex | `CODEX_THREAD_ID`, `CODEX_CI`, `CODEX_SANDBOX` | high |
+| Gemini CLI | `GEMINI_CLI` | high |
+| Copilot CLI | `COPILOT_CLI` | medium |
+| OpenCode | `OPENCODE` | high |
+| Antigravity | `ANTIGRAVITY_AGENT` | medium |
+| Augment CLI | `AUGMENT_AGENT` | medium |
+| Cowork | `CLAUDE_CODE_IS_COWORK` | high |
+| Claude Code | `CLAUDE_CODE_CHILD_SESSION`, `CLAUDECODE`, `CLAUDE_CODE` | high / medium |
+| Cursor | `CURSOR_TRACE_ID` | medium |
+| Cursor CLI | `CURSOR_AGENT`, `CURSOR_EXTENSION_HOST_ROLE=agent-exec` | high / medium |
+| Kiro | `TERM_PROGRAM=kiro` | low |
+| Pi | `.pi/agent` entry in `PATH` | medium |
+| Replit | `REPL_ID` | low |
+| Goose | `GOOSE_PROVIDER` | low |
+
+`AI_AGENT` takes precedence over inferred signals when its value is one of the
+supported agent names. Unknown values are ignored.
+
+The detector is deliberately ordered. For example, Amp is checked before
+Claude Code because Amp also sets `CLAUDECODE`.
+
+## Important limitations
+
+Detection is best-effort. `None` means **unattributed**, not "human". Some
+signals can also be present in an integrated terminal where a person typed the
+command manually.
+
+This package detects the execution harness. It cannot determine whether a
+particular skill, plugin, prompt, or model caused the command. Use a separate
+explicit marker when that attribution matters.
+
+## Privacy
+
+Environment values such as thread IDs are never returned. A result contains
+only a normalized agent name and the name and category of the matched signal.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+```

agent_detector-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_detector/__init__.py,sha256=kU9nRrHT7TWT-GCpzQUkca2pSPlOVmNSinKe6HZi4Ec,296
+agent_detector/_detector.py,sha256=QSu8HNVQJX3In8DuS-8isPE_ppc-GzJ_a6lvsWnOKIY,5935
+agent_detector/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+agent_detector-1.0.0.dist-info/METADATA,sha256=jMTgQBHAz770f8FMC5Dv9zpX2jVZ2yydVm1kiPpmTLk,4177
+agent_detector-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+agent_detector-1.0.0.dist-info/licenses/LICENSE,sha256=pFgSIuwDZh_CA1OuRDQ1k2oD1IdkWDwoLw4xQZ06Q-4,1072
+agent_detector-1.0.0.dist-info/RECORD,,

agent_detector-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_detector-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Arminio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.