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 | ✅ | | Grok | grok | ✅ | | Kilo Code | kilocode | ✅ | | Kiro | kiro | ✅ | | Muse Code | muse | 🚫 | | 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.

OpenCode 1.0.19 and later is detected from environment variables by default. OpenCode 0.x requires experimental process-tree detection.

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, REPLIT_SESSION, and GROK_SESSION_ID. 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