agent-cli-detector

agent-cli-detector

Detect whether a JavaScript CLI is running inside a coding agent.

Please open an issue if your coding agent isn't properly detected :)

Installation

npm install agent-cli-detector

Usage

import { detectAgent } from "agent-cli-detector";

const result = detectAgent();

if (result.detected) {
  console.log("The name of the coding agent is:", result.agent.name);
} else {
  console.log("This program is not running inside a coding agent");
}

Supported agents

Officially supported coding agents:

Name	ID	Session ID
Antigravity	antigravity
Bolt	bolt
Claude Code	claude-code
Cline	cline
Codex	codex
Cursor	cursor
Devin	devin
Gemini CLI	gemini
GitHub Copilot CLI	copilot
Kilo Code	kilocode
Kiro	kiro
OpenCode	opencode
Pi	pi
Replit	replit
Rork	rork

Detection is data-driven: the exact environment variables and process patterns for each agent live in src/agents.ts.

API

detectAgent([options])

Runs detection and returns a DetectionResult:

{
  detected: true,
  agent: {
    id: "cursor",
    name: "Cursor",
    sessionId: "d9e9cd60-2e1c-487c-9bc7-fceee5e9c3a2"
  }
}

result.detected

A boolean. Will be true if the code is running inside a coding agent, otherwise false.

result.agent.id

A stable identifier for the detected agent (see the ID column in the support table above). Prefer comparing against this instead of result.agent.name.

result.agent.name

A string containing the display name of the detected coding agent.

Don't depend on the value of this string not to change for a specific agent. If you find yourself writing result.agent.name === "Claude Code", you most likely want to use result.agent.id === "claude-code" instead.

result.agent.sessionId

A string containing the agent's session identifier, normalized from agent-specific environment variables such as CODEX_THREAD_ID, CURSOR_CONVERSATION_ID, CLAUDE_CODE_SESSION_ID, ANTIGRAVITY_TRAJECTORY_ID, KIRO_SESSION_ID, KILO_RUN_ID, and COPILOT_AGENT_SESSION_ID, and REPLIT_SESSION. Omitted when the agent doesn't expose one (see the Session ID column in the support table above).

isRunningFromAgent([options])

A convenience shortcut that returns result.detected as a boolean:

import { isRunningFromAgent } from "agent-cli-detector";

if (isRunningFromAgent()) {
  // Adjust CLI behavior for agent-driven execution.
}

CLI

The package also ships a CLI:

npx agent-cli-detector
npx agent-cli-detector --json

Exit codes:

• 0: a coding agent was detected
• 1: no coding agent was detected

Process-tree detection (experimental)

Detection uses environment variables by default. Parent-process inspection is available as an opt-in for callers that can tolerate best-effort process-tree matching:

const result = detectAgent({ experimentalProcessTree: true });

Some sandboxes block ps, and process names can vary by launcher, so process-tree detection should be treated as experimental. It has only been tested on macOS and does not work on Windows.

Custom agents

Add an agent by supplying an AgentDefinition:

import { detectAgent, defaultAgents } from "agent-cli-detector";

const result = detectAgent({
  agents: [
    ...defaultAgents,
    {
      id: "my-agent",
      name: "My Agent",
      env: [{ name: "MY_AGENT", value: "1" }],
      process: [{ pattern: /^my-agent$/i }]
    }
  ]
});

Custom strategies

Add a detection strategy by implementing DetectionStrategy:

import type { DetectionStrategy } from "agent-cli-detector";

const strategy: DetectionStrategy = {
  name: "my-strategy",
  detect(context) {
    return [];
  }
};

License

MIT