who-behind-me

Detect whether your code is being run by an AI agent or a human.

This library analyzes the runtime environment to determine if the current process was launched by an AI coding agent (like Claude Code, GitHub Copilot, or Codex) rather than a human sitting at a terminal.

How it works

The library runs a set of rules against the current platform (Node.js or Deno), each returning a [isAgentSignal, confidence, description?] tuple. Each result is assigned a numeric weight, and the weighted scores are summed. If the total exceeds a threshold, the process is classified as agent-driven.

Detection Rules

| Rule | What it checks | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Environment variables | Scans for agent-specific env vars (e.g., CLAUDECODE, CODEX_THREAD_ID, COPILOT_AGENT, AI_AGENT, OMPCODE, __PI_NATIVE_VARIANT_CACHE) and analyzes TERM settings | | Stdio pipes | Checks whether stdin/stdout/stderr are connected to a TTY (interactive terminal) or piped, and whether stdin has buffered data |

Confidence levels

• confident — Strong signal (e.g., a known AI agent env var is set)
• maybe — Suggestive but not definitive (e.g., non-TTY stdout)
• unknown — Inconclusive (e.g., TTY stdout — can be spoofed)

Installation

npm install who-behind-me
# or
pnpm add who-behind-me
# or
bun add who-behind-me

Usage

import { check } from "who-behind-me";

const result = check();
console.log(result.isAgent); // true | false
console.log(result.score); // weighted sum
console.log(result.detail); // individual rule results

Custom weights

You can override the default scoring weights to tune sensitivity:

import { check } from "who-behind-me";

const result = check({
    truthy: { confident: 20, maybe: 0.5, unknown: 0 },
    falsy: { confident: -20, maybe: -0.5, unknown: 0 },
});

Default scoring

| Result | confident | maybe | unknown | | ---------------------- | --------- | ----- | ------- | | true (agent signal) | +10 | +0.1 | 0 | | false (human signal) | -10 | -0.1 | 0 |

Threshold: 0.5 — scores above this classify as agent.

API

check(weight?, opts?)

• weight — Optional custom WeightConfig to override detection sensitivity
• opts — Optional platform-specific options (e.g., { checkType: "active" } for Deno permission mode)
• Returns { isAgent: boolean, detail: RuleEntity[], score: number }

Supported Platforms

• Node.js >= 24
• Deno (with environment permission handling)

License

MIT