agenthint 0.4.0__py3-none-any.whl

agenthint/__init__.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Callable, Mapping
+
+AgentName = str
+
+TRUE_VALUES = {"1", "true", "yes", "on"}
+PARENT_CONFIDENCE = 0.55
+
+
+@dataclass(frozen=True)
+class AgentHintResult:
+    is_agent: bool
+    agent: AgentName | None
+    confidence: float
+    signals: list[str]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "isAgent": self.is_agent,
+            "agent": self.agent,
+            "confidence": self.confidence,
+            "signals": self.signals,
+        }
+
+
+def detect_agent(
+    *,
+    env: Mapping[str, str] | None = None,
+    stdout_is_tty: bool | None = None,
+    stdin_is_tty: bool | None = None,
+    check_filesystem: bool = True,
+    check_parent_process: bool = True,
+    parent_process_name: str | None = None,
+    file_exists: Callable[[str], bool] = os.path.exists,
+) -> AgentHintResult:
+    env = os.environ if env is None else env
+
+    if _is_truthy(env.get("AGENTHINT_DISABLE")):
+        return AgentHintResult(False, None, 1, ["env:AGENTHINT_DISABLE"])
+
+    if _is_truthy(env.get("AGENTHINT_FORCE")):
+        return AgentHintResult(
+            True,
+            _normalize_agent_name(env.get("AGENTHINT_AGENT")) or "unknown",
+            1,
+            ["env:AGENTHINT_FORCE"],
+        )
+
+    ai_agent = _from_ai_agent(env)
+    if ai_agent is not None:
+        return ai_agent
+
+    matches = _detection_matches(env)
+    if matches:
+        best = matches[0]
+        return AgentHintResult(True, best["agent"], best["confidence"], [signal for match in matches for signal in match["signals"]])
+
+    if check_filesystem and file_exists("/opt/.devin"):
+        return AgentHintResult(True, "devin", 0.9, ["file:/opt/.devin"])
+
+    parent_result = _from_parent_process(check_parent_process, parent_process_name)
+    if parent_result is not None:
+        return parent_result
+
+    tty_signals: list[str] = []
+    if stdout_is_tty is False:
+        tty_signals.append("stdio:stdout-not-tty")
+    if stdin_is_tty is False:
+        tty_signals.append("stdio:stdin-not-tty")
+    if tty_signals:
+        return AgentHintResult(False, None, 0.2, tty_signals)
+
+    return AgentHintResult(False, None, 0, [])
+
+
+def format_explanation(result: AgentHintResult) -> str:
+    status = "agent runtime likely detected" if result.is_agent else "agent runtime not detected"
+    agent = f"\nagent: {result.agent}" if result.agent else ""
+    signals = ", ".join(result.signals) if result.signals else "none"
+    return f"{status}{agent}\nconfidence: {result.confidence:.2f}\nsignals: {signals}"
+
+
+def format_json(result: AgentHintResult) -> str:
+    return json.dumps(result.to_dict(), indent=2)
+
+
+def _from_ai_agent(env: Mapping[str, str]) -> AgentHintResult | None:
+    value = env.get("AI_AGENT")
+    if value is None or not value.strip():
+        return None
+
+    return AgentHintResult(True, _normalize_agent_name(value) or value.strip(), 0.98, ["env:AI_AGENT"])
+
+
+def _detection_matches(env: Mapping[str, str]) -> list[dict[str, object]]:
+    rules = _rules()
+    matches: list[dict[str, object]] = []
+
+    for rule in rules["environmentRules"]:
+        signals = _present(env, rule["names"])
+        if signals:
+            matches.append({"agent": rule["agent"], "confidence": rule["confidence"], "signals": signals})
+
+        if rule["agent"] == "opencode":
+            claude_signals = _present(env, ["CLAUDECODE", "CLAUDE_CODE", "CLAUDECODE_CWD"])
+            if claude_signals:
+                agent = "cowork" if _present(env, ["CLAUDE_CODE_IS_COWORK"]) else "claude-code"
+                matches.append({"agent": agent, "confidence": 0.9, "signals": claude_signals})
+
+    for rule in rules["prefixRules"]:
+        signals = _prefix_present(env, rule["prefix"])
+        if signals:
+            matches.append({"agent": rule["agent"], "confidence": rule["confidence"], "signals": signals})
+
+    return matches
+
+
+def _from_parent_process(check_parent_process: bool, parent_process_name: str | None) -> AgentHintResult | None:
+    if not check_parent_process:
+        return None
+
+    name = _normalize_process_name(parent_process_name or _parent_process_name())
+    if name is None:
+        return None
+
+    for rule in _rules()["parentProcessRules"]:
+        if name in rule["names"]:
+            return AgentHintResult(True, rule["agent"], PARENT_CONFIDENCE, [f"process:parent:{name}"])
+
+    return None
+
+
+def _parent_process_name() -> str | None:
+    ppid = os.getppid()
+    if ppid <= 0:
+        return None
+
+    proc_path = Path(f"/proc/{ppid}/comm")
+    try:
+        value = proc_path.read_text(encoding="utf8").strip()
+        if value:
+            return value
+    except OSError:
+        pass
+
+    try:
+        return subprocess.run(
+            ["ps", "-o", "comm=", "-p", str(ppid)],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError):
+        return None
+
+
+def _present(env: Mapping[str, str], names: list[str]) -> list[str]:
+    return [f"env:{name}" for name in names if env.get(name)]
+
+
+def _prefix_present(env: Mapping[str, str], prefix: str) -> list[str]:
+    return [f"env:{name}" for name, value in env.items() if name.startswith(prefix) and value]
+
+
+def _is_truthy(value: str | None) -> bool:
+    return value is not None and value.lower() in TRUE_VALUES
+
+
+def _normalize_agent_name(value: str | None) -> str | None:
+    if value is None or not value.strip():
+        return None
+
+    normalized = value.strip()
+    if normalized in {"github-copilot", "github-copilot-cli"}:
+        return "copilot"
+    if normalized.startswith("claude-code"):
+        return "claude-code"
+    if normalized in {"roo", "roo-code"}:
+        return "roo-code"
+    if normalized in {"kilo-code", "kilocode"}:
+        return "kilocode"
+    if normalized in {"mistral-vibe", "vibe"}:
+        return "mistral-vibe"
+    return normalized
+
+
+def _normalize_process_name(value: str | None) -> str | None:
+    if value is None or not value.strip():
+        return None
+    return Path(value.strip()).name.removesuffix(".exe").lower()
+
+
+def _rules() -> dict[str, object]:
+    return json.loads(files("agenthint").joinpath("detection-rules.json").read_text(encoding="utf8"))
+
+
+__all__ = ["AgentHintResult", "detect_agent", "format_explanation", "format_json"]

agenthint/cli.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import sys
+
+from agenthint import detect_agent, format_explanation, format_json
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if "-h" in args or "--help" in args:
+        print_help()
+        raise SystemExit(0)
+
+    result = detect_agent()
+
+    if "--json" in args:
+        print(format_json(result))
+    elif "--explain" in args:
+        print(format_explanation(result))
+
+    raise SystemExit(0 if result.is_agent else 1)
+
+
+def print_help() -> None:
+    print(
+        """agenthint
+
+Detect whether the current process is probably running under an AI agent.
+
+Usage:
+  agenthint             Exit 0 if an agent is likely detected, otherwise 1
+  agenthint --json      Print the structured detection result
+  agenthint --explain   Print a short human-readable explanation
+  agenthint --help      Show this help"""
+    )
+
+
+if __name__ == "__main__":
+    main()

agenthint/detection-rules.json

@@ -0,0 +1,151 @@
+{
+  "knownAgents": [
+    "codex",
+    "claude-code",
+    "cowork",
+    "aider",
+    "cursor",
+    "gemini",
+    "augment-cli",
+    "amp",
+    "opencode",
+    "copilot",
+    "replit",
+    "devin",
+    "antigravity",
+    "pi",
+    "kiro-cli",
+    "windsurf",
+    "cline",
+    "roo-code",
+    "kilocode",
+    "openclaw",
+    "mistral-vibe",
+    "v0",
+    "unknown"
+  ],
+  "environmentRules": [
+    {
+      "agent": "cursor",
+      "confidence": 0.92,
+      "names": ["CURSOR_AGENT"]
+    },
+    {
+      "agent": "gemini",
+      "confidence": 0.92,
+      "names": ["GEMINI_CLI"]
+    },
+    {
+      "agent": "codex",
+      "confidence": 0.92,
+      "names": ["CODEX_SANDBOX", "CODEX_CI", "CODEX_THREAD_ID", "CODEX_HOME", "CODEX_USER_AGENT"]
+    },
+    {
+      "agent": "augment-cli",
+      "confidence": 0.9,
+      "names": ["AUGMENT_AGENT"]
+    },
+    {
+      "agent": "amp",
+      "confidence": 0.9,
+      "names": ["AMP_CURRENT_THREAD_ID"]
+    },
+    {
+      "agent": "opencode",
+      "confidence": 0.9,
+      "names": ["OPENCODE_CLIENT", "OPENCODE"]
+    },
+    {
+      "agent": "copilot",
+      "confidence": 0.88,
+      "names": ["COPILOT_MODEL", "COPILOT_ALLOW_ALL", "COPILOT_GITHUB_TOKEN", "COPILOT_CLI"]
+    },
+    {
+      "agent": "replit",
+      "confidence": 0.65,
+      "names": ["REPL_ID"]
+    },
+    {
+      "agent": "antigravity",
+      "confidence": 0.9,
+      "names": ["ANTIGRAVITY_AGENT"]
+    },
+    {
+      "agent": "pi",
+      "confidence": 0.9,
+      "names": ["PI_CODING_AGENT"]
+    },
+    {
+      "agent": "kiro-cli",
+      "confidence": 0.9,
+      "names": ["KIRO_AGENT_PATH"]
+    },
+    {
+      "agent": "windsurf",
+      "confidence": 0.82,
+      "names": ["WINDSURF_AGENT"]
+    },
+    {
+      "agent": "cline",
+      "confidence": 0.82,
+      "names": ["CLINE_AGENT"]
+    },
+    {
+      "agent": "roo-code",
+      "confidence": 0.82,
+      "names": ["ROO_CODE_AGENT", "ROO_CODE"]
+    },
+    {
+      "agent": "kilocode",
+      "confidence": 0.82,
+      "names": ["KILOCODE_AGENT"]
+    },
+    {
+      "agent": "openclaw",
+      "confidence": 0.82,
+      "names": ["OPENCLAW_AGENT"]
+    }
+  ],
+  "prefixRules": [
+    {
+      "agent": "aider",
+      "confidence": 0.86,
+      "prefix": "AIDER_"
+    },
+    {
+      "agent": "cursor",
+      "confidence": 0.82,
+      "prefix": "CURSOR_"
+    }
+  ],
+  "parentProcessRules": [
+    {
+      "agent": "codex",
+      "names": ["codex"]
+    },
+    {
+      "agent": "claude-code",
+      "names": ["claude", "claude-code"]
+    },
+    {
+      "agent": "cursor",
+      "names": ["cursor-agent", "cursor"]
+    },
+    {
+      "agent": "gemini",
+      "names": ["gemini"]
+    },
+    {
+      "agent": "aider",
+      "names": ["aider"]
+    },
+    {
+      "agent": "opencode",
+      "names": ["opencode"]
+    },
+    {
+      "agent": "amp",
+      "names": ["amp"]
+    }
+  ]
+}

agenthint-0.4.0.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: agenthint
+Version: 0.4.0
+Summary: Detect AI agent runtimes and adapt CLI output.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/forjd/agenthint
+Project-URL: Repository, https://github.com/forjd/agenthint
+Project-URL: Issues, https://github.com/forjd/agenthint/issues
+Keywords: ai,agent,cli,detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agenthint
+
+[![CI](https://github.com/forjd/agenthint/actions/workflows/ci.yml/badge.svg)](https://github.com/forjd/agenthint/actions/workflows/ci.yml)
+[![Release](https://github.com/forjd/agenthint/actions/workflows/release.yml/badge.svg)](https://github.com/forjd/agenthint/actions/workflows/release.yml)
+[![npm](https://img.shields.io/npm/v/agenthint?logo=npm&color=cb3837)](https://www.npmjs.com/package/agenthint)
+[![crates.io](https://img.shields.io/crates/v/agenthint?logo=rust&color=dea584)](https://crates.io/crates/agenthint)
+[![License](https://img.shields.io/github/license/forjd/agenthint)](LICENSE)
+[![GitHub Repo stars](https://img.shields.io/github/stars/forjd/agenthint?style=social)](https://github.com/forjd/agenthint)
+
+Detect AI agent runtimes and adapt CLI output.
+
+`agenthint` is a small runtime detection spec, CLI, and library for developer tools that want to know when they are probably being run by an AI agent such as Codex, Claude Code, Cursor, Gemini CLI, or Aider.
+
+It is built for ergonomics, not security. Use it to choose better output defaults for agents; do not use it as a trust boundary.
+
+## Why
+
+AI agents benefit from different CLI defaults than humans:
+
+- structured output instead of decorative output
+- no spinners, pagers, prompts, or browser launches
+- stable section markers and clear exit-code meanings
+- absolute paths and line-oriented diagnostics
+- concise logs that preserve useful debugging context
+
+`agenthint` gives CLIs and libraries a shared way to make that decision.
+
+## Quick Start
+
+```sh
+npm install -g agenthint
+# or
+cargo install agenthint
+```
+
+```sh
+if agenthint; then
+  my-tool --json --no-progress
+else
+  my-tool
+fi
+```
+
+Use it inside another CLI or script to choose agent-friendly output:
+
+```sh
+if agenthint >/dev/null; then
+  exec my-cli --json --no-progress --no-pager "$@"
+else
+  exec my-cli "$@"
+fi
+```
+
+For agents and wrappers, the preferred explicit convention is `AI_AGENT`:
+
+```sh
+AI_AGENT=codex my-tool
+AI_AGENT=claude-code my-tool
+AI_AGENT=my-custom-agent my-tool
+```
+
+## CLI
+
+```sh
+agenthint             # exit 0 if an agent is likely detected, otherwise 1
+agenthint --json      # print the structured detection result
+agenthint --explain   # print a short explanation
+agenthint doctor      # print detection details and setup advice
+agenthint doctor --json
+                      # print detection details and setup advice as JSON
+agenthint init codex  # print the recommended AI_AGENT value
+```
+
+Example JSON output:
+
+```json
+{
+  "isAgent": true,
+  "agent": "codex",
+  "confidence": 0.92,
+  "signals": ["env:CODEX_CI", "env:CODEX_THREAD_ID"]
+}
+```
+
+## Install
+
+Install from npm:
+
+```sh
+npm install -g agenthint
+agenthint --json
+```
+
+Install from crates.io:
+
+```sh
+cargo install agenthint
+agenthint --json
+```
+
+Install from PyPI:
+
+```sh
+python3 -m pip install agenthint
+agenthint --json
+```
+
+Install the latest native binary from GitHub Releases:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/forjd/agenthint/main/install.sh | sh
+```
+
+Override the install directory or version:
+
+```sh
+AGENTHINT_INSTALL_DIR=/usr/local/bin sh install.sh
+AGENTHINT_VERSION=agenthint-vX.Y.Z sh install.sh
+```
+
+Native binaries are built by GitHub Actions for release assets. The installer verifies `SHA256SUMS` when the selected release provides it.
+
+## TypeScript API
+
+```ts
+import { detectAgent } from "agenthint";
+
+const result = detectAgent();
+
+if (result.isAgent) {
+  // Prefer structured, quiet, non-interactive output.
+}
+```
+
+## Rust API
+
+The repository also contains a Rust implementation under `crates/agenthint`.
+
+```rust
+use agenthint::detect_agent;
+
+let result = detect_agent();
+
+if result.is_agent {
+    // Prefer structured, quiet, non-interactive output.
+}
+```
+
+Run the Rust CLI locally:
+
+```sh
+cargo run -q -p agenthint -- --json
+```
+
+## Python API
+
+```python
+from agenthint import detect_agent
+
+result = detect_agent()
+
+if result.is_agent:
+    # Prefer structured, quiet, non-interactive output.
+    pass
+```
+
+## Detection Model
+
+The result includes:
+
+- `isAgent`: whether an agent runtime is likely detected
+- `agent`: known or custom agent name
+- `confidence`: a number from `0` to `1`
+- `signals`: diagnostic signal names, never secret values
+
+Detection priority:
+
+1. `AGENTHINT_DISABLE`
+2. `AGENTHINT_FORCE`
+3. explicit `AI_AGENT`
+4. known environment signals
+5. documented filesystem signals
+6. low-confidence parent process signals
+7. low-confidence stdio hints
+
+## Supported Agents
+
+Current known agent names include:
+
+- Codex
+- Claude Code
+- Cowork
+- Cursor
+- Gemini CLI
+- Aider
+- Augment CLI
+- AMP
+- OpenCode
+- OpenClaw
+- GitHub Copilot
+- Replit
+- Devin
+- Google Antigravity
+- Pi
+- Kiro CLI
+- Windsurf
+- Cline
+- Roo Code
+- Kilo Code
+- Mistral Vibe
+- v0
+
+Custom agents are supported through any non-empty `AI_AGENT` value.
+
+See [docs/agents.md](docs/agents.md) for recommended `AI_AGENT` values.
+
+See [docs/integrations.md](docs/integrations.md) for Bash, Zsh, Fish, Node.js, Rust, and Python integration snippets.
+
+See [docs/signals.md](docs/signals.md) for the signal registry and confidence levels.
+
+## Principles
+
+- Detection is advisory and can be spoofed.
+- Prefer `AI_AGENT` when an agent can set an explicit hint.
+- Prefer explicit environment signals over brittle heuristics.
+- Return confidence, not false certainty.
+- Print signal names, not environment variable values.
+- Keep output quiet and machine-readable when requested.
+- Make the convention useful across languages and toolchains.
+
+## Packages
+
+Current:
+
+- `agenthint` JavaScript/TypeScript package
+- `agenthint` Rust crate and CLI implementation
+- `agenthint` Python package
+
+Planned:
+
+- standalone native binary releases
+
+The packages use the unscoped `agenthint` name across npm, crates.io, and PyPI. If the npm name becomes unavailable before first publish, the fallback package name is `@forjd/agenthint`.
+
+## CI and Releases
+
+GitHub Actions runs formatting, linting, TypeScript tests, Rust tests, Python tests, npm package checks, Python package build checks, and `cargo publish --dry-run`.
+
+Releases use release-please with Conventional Commits. npm and PyPI publishing use trusted publishing via GitHub Actions OIDC, so no long-lived package tokens are required. Before the first publish, configure trusted publishers for `forjd/agenthint` and `.github/workflows/release.yml`.
+
+See [docs/releases.md](docs/releases.md) for release details.
+
+## Development
+
+Use [mise](https://mise.jdx.dev/) for local toolchain versions:
+
+```sh
+mise install
+```
+
+Install dependencies and run checks:
+
+```sh
+npm install
+npm run check
+```
+
+Useful commands:
+
+```sh
+npm run format
+npm run lint
+npm test
+npm run python:build
+npm run python:test
+npm run generate:rules
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+## Security
+
+`agenthint` is not an authentication, authorization, sandboxing, or policy tool. Environment variables, parent process names, and filesystem markers can be spoofed. Treat all results as UX hints only.
+
+## License
+
+MIT © Forjd

agenthint-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agenthint/__init__.py,sha256=psAFlb4lH6g2ehwgpu6bZ7kfvkVhOSo-Qnyb_7RwNQ0,6462
+agenthint/cli.py,sha256=hpDwzzzdDVhEmu1PqyklAkgO325h9jw5CIyLVVsc8iw,899
+agenthint/detection-rules.json,sha256=wKnYSBXPY0qe3Hb16-MT-2TooHQnbJQRyLTk7gEABe0,2824
+agenthint-0.4.0.dist-info/licenses/LICENSE,sha256=nXyn4JNOhM1tW6PbUeQ9Wu0EuToVPvK6gehLRML1VLk,1062
+agenthint-0.4.0.dist-info/METADATA,sha256=CeCwerspuwy93hqd0QBMJYmC5ABJA2d-0SMO-o1NkoM,7759
+agenthint-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agenthint-0.4.0.dist-info/entry_points.txt,sha256=sRjtzXRUOzK0TvXmbncvVVDPRzcBIugwe6wPfV9WsO8,49
+agenthint-0.4.0.dist-info/top_level.txt,sha256=W03YuMpAFJVQFAmqURdoN-t06ZVQJhs_EjRafnnHvnc,10
+agenthint-0.4.0.dist-info/RECORD,,

agenthint-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agenthint-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agenthint = agenthint.cli:main

agenthint-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forjd
+
+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.

agenthint-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agenthint