agent-detector 1.0.0__tar.gz

agent_detector-1.0.0/.autopub/release_info.json

@@ -0,0 +1 @@
+{"release_type": "major", "release_notes": "Agent Detector is now available as a dependency-free Python package for\nidentifying the AI coding agent driving a process.\n\nIt recognizes Codex, Claude Code, Amp, Pi, OpenCode, Cursor, Gemini CLI, and\nother coding agents using environment evidence. Each result includes a\nnormalized agent name, confidence, source, and signal without returning\nenvironment values. Callers can also require a minimum confidence level.", "additional_info": {"content": "Agent Detector is now available as a dependency-free Python package for\nidentifying the AI coding agent driving a process.\n\nIt recognizes Codex, Claude Code, Amp, Pi, OpenCode, Cursor, Gemini CLI, and\nother coding agents using environment evidence. Each result includes a\nnormalized agent name, confidence, source, and signal without returning\nenvironment values. Callers can also require a minimum confidence level."}, "additional_release_notes": ["This release was contributed by [@patrick91](https://github.com/patrick91) in [#1](https://github.com/patrick91/agent-detector/pull/1)"], "version": "1.0.0", "previous_version": "0.0.0", "hash": "e0f5b31f69c02a9991e2fabc594cbb30e187a97418ddda70f4d87db32f7d4643"}

agent_detector-1.0.0/.github/workflows/release-check.yml

@@ -0,0 +1,39 @@
+name: Release file check
+
+on:
+  pull_request_target:
+    types: [synchronize, reopened, opened, ready_for_review]
+    branches: [main]
+    paths:
+      - "RELEASE.md"
+      - "src/agent_detector/**"
+      - "pyproject.toml"
+
+permissions:
+  contents: read
+
+jobs:
+  check-release:
+    name: Release check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    if: github.event.pull_request.user.type != 'Bot'
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          ref: refs/pull/${{ github.event.number }}/merge
+          persist-credentials: false
+          sparse-checkout: |
+            RELEASE.md
+            pyproject.toml
+          sparse-checkout-cone-mode: false
+
+      - name: Check for release
+        uses: autopub/autopub-action@5fdc82e84c048a82303de6b5c5a9d027665e73cf # v1.1.1
+        with:
+          command: check
+          autopub-version: "1.0.0a60"
+          fail-on-missing: "true"

agent_detector-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+concurrency: release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check-release:
+    name: Check for release
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    outputs:
+      has_release: ${{ steps.check.outputs.has-release }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Check for release
+        id: check
+        uses: autopub/autopub-action@5fdc82e84c048a82303de6b5c5a9d027665e73cf # v1.1.1
+        with:
+          command: check
+          autopub-version: "1.0.0a60"
+
+  publish:
+    name: Publish to PyPI
+    needs: check-release
+    if: needs.check-release.outputs.has_release == 'true'
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python 3.14
+        run: uv python install 3.14
+
+      - name: Prepare release
+        uses: autopub/autopub-action@5fdc82e84c048a82303de6b5c5a9d027665e73cf # v1.1.1
+        with:
+          command: prepare
+          autopub-version: "1.0.0a60"
+
+      - name: Build package
+        uses: autopub/autopub-action@5fdc82e84c048a82303de6b5c5a9d027665e73cf # v1.1.1
+        with:
+          command: build
+          autopub-version: "1.0.0a60"
+
+      - name: Publish to PyPI
+        uses: autopub/autopub-action@5fdc82e84c048a82303de6b5c5a9d027665e73cf # v1.1.1
+        with:
+          command: publish
+          autopub-version: "1.0.0a60"

agent_detector-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,53 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run pytest
+
+  quality:
+    name: Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy
+
+      - name: Build
+        run: uv build

agent_detector-1.0.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/

agent_detector-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.4
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: [--fix]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: no-commit-to-branch
+        args: [--branch, main]

agent_detector-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+1.0.0 - 2026-07-21
+------------------
+
+Agent Detector is now available as a dependency-free Python package for
+identifying the AI coding agent driving a process.
+
+It recognizes Codex, Claude Code, Amp, Pi, OpenCode, Cursor, Gemini CLI, and
+other coding agents using environment evidence. Each result includes a
+normalized agent name, confidence, source, and signal without returning
+environment values. Callers can also require a minimum confidence level.
+
+This release was contributed by [@patrick91](https://github.com/patrick91) in [#1](https://github.com/patrick91/agent-detector/pull/1)
+
+# Changelog
+
+This file is managed by [AutoPub](https://github.com/patrick91/autopub).

agent_detector-1.0.0/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.

agent_detector-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,101 @@
+# 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/RELEASE.md

@@ -0,0 +1,11 @@
+---
+release type: major
+---
+
+Agent Detector is now available as a dependency-free Python package for
+identifying the AI coding agent driving a process.
+
+It recognizes Codex, Claude Code, Amp, Pi, OpenCode, Cursor, Gemini CLI, and
+other coding agents using environment evidence. Each result includes a
+normalized agent name, confidence, source, and signal without returning
+environment values. Callers can also require a minimum confidence level.

agent_detector-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "agent-detector"
+version = "1.0.0"
+description = "Detect AI coding agents from their execution environment"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Patrick Arminio" }]
+dependencies = []
+keywords = ["agent", "ai", "cli", "codex", "claude", "telemetry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/patrick91/agent-detector"
+Repository = "https://github.com/patrick91/agent-detector"
+Issues = "https://github.com/patrick91/agent-detector/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "pytest-cov>=6.2.1",
+]
+lint = [
+    "mypy>=1.17.1,<2",
+    "ruff>=0.12.4",
+]
+
+[tool.ruff]
+fix = true
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "RUF", "UP", "W"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=agent_detector --cov-report=term-missing"
+testpaths = ["tests"]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true
+
+[tool.mypy]
+python_version = "3.9"
+files = ["src"]
+strict = true
+
+[tool.autopub]
+git-username = "github-actions[bot]"
+git-email = "41898282+github-actions[bot]@users.noreply.github.com"
+plugins = ["autopub.plugins.github", "autopub.plugins.uv"]

agent_detector-1.0.0/src/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",
+]