Proposal: Standard environment variable for agent runtime detection

[ianlet]

Problem

Scripts and CLIs can detect CI environments via the CI=true convention, enabling non-interactive behavior and CI-appropriate output. There's no equivalent for AI coding agents.

When agents execute commands, scripts have no way to know they're running in an agent context. This matters because:

• Error output — Agents benefit from structured errors (JSON with actionable suggestions) rather than human-friendly prose
• Verbosity — Agents can process more context; humans need scannable output
• Interactivity — Like CI, agents can't respond to prompts, but the existing CI=true doesn't capture the full picture

Use cases

# Script adapts output format
if [[ -n "${AGENT:-}" ]]; then
  echo '{"error": "config_missing", "suggestion": "run ./setup.sh", "docs": "https://..."}'
  exit 1
else
  echo "Error: Config file not found. Run ./setup.sh to initialize."
  exit 1
fi

# Test runner provides richer failure context for agents
if [[ -n "${AGENT:-}" ]]; then
  pytest --tb=long --verbose "$@"
else
  pytest "$@"
fi

Proposal

Agents set an environment variable when executing commands:

Variable	Value	Meaning
AGENT	[agent-name], 1, or true	Running under an AI coding agent

Adoption

AGENT variable (this proposal)

Project	Value	Status	Ref
Goose	goose	implemented	PR #7017
Amp	amp	implemented	Docs
Claude Code	-	issue open	#24838
Cursor	-	requested (no response)	Forum thread

Tool-specific variables (status quo)

Project	Variable	Value	Ref
Claude Code	CLAUDECODE	1	Env vars reference
Cursor	CURSOR_AGENT	1	Docs
Gemini CLI	GEMINI_CLI	1	Source
Codex CLI	CODEX_SANDBOX	seatbelt	Source
Augment	AUGMENT_AGENT	1	Docs
Cline	CLINE_ACTIVE	true	Discussion #5366
OpenCode	OPENCODE_CLIENT	1	Vercel PR #15121
TRAE AI	TRAE_AI_SHELL_ID	(session id)	Vercel PR #14257
Devin	/opt/.devin	(filesystem)	Vercel detect-agent source

Consumer-side detection

Tools already adapting behavior based on agent detection:

Project	How	Ref
Bun	isAIAgent() checks AGENT=1, CLAUDECODE, REPL_ID. Suppresses passing tests, shows only failures.	PR #21135
Vercel	@vercel/detect-agent checks AI_AGENT, then falls back to 9+ tool-specific vars. Sets deployment actor.	PR #13736

Both had to build detection matrices because no single standard exists.

Precedent

• CI=true — Set by GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins, etc.
• NO_COLOR=1 — Disables color output across CLIs (no-color.org)
• TERM=dumb — Signals limited terminal capabilities
• InfoQ: Patterns for AI Agent Driven CLIs — Recommends --no-interactive flags and structured output, but no env var convention

The CI convention emerged organically as tools independently adopted it. A coordinated standard would accelerate adoption for agents.

Open questions

1. Variable name — AGENT (Goose, Amp, Bun), AI_AGENT (Vercel's detect-agent), or something else? AGENT is concise and mirrors CI, but could collide with non-AI agent systems. AI_AGENT is more specific but verbose.
2. Scope — Should this cover all automation (like CI) or specifically AI agents?
3. Relationship to CI — Should agents also set CI=true, or is this orthogonal?
4. Coexistence — Should tools set both the standard variable AND their tool-specific one? (Goose already does: AGENT=goose + GOOSE_TERMINAL=1)

Known opposition

Project	Position	Ref
VS Code / Copilot	Agents should work in identical environments to users. Shipped terminal profile settings instead of env vars.	#258911, #253945

Prior art

• OpenAI Codex uses CODEX_SANDBOX=1 internally for sandbox detection
• Claude Code uses CLAUDECODE=1 paired with CLAUDE_CODE_ENTRYPOINT=cli

---

Comments welcome to update the adoption tables.

[gmeligio]

I think this standard environment variable should be added in the agent process. See the related discussion anthropics/claude-code#24838 .

[ianlet]

Project goose implemented the AGENT=goose environment variable in their tool block/goose#7017 as well as amp with AGENT=amp.

[sw-square]

Re "Variable name" in open questions: I'm personally a fan of AGENT over AI_AGENT.

There's lots of precedence with using shorter names (LANG, EDITOR/VISUAL, CI, TERM, etc), and the word "agent" is quickly converging to exclusively refer to AI (and didn't really have a commonly used/clearly defined meaning beforehand). The leading AI_ feels quite redundant (as would TERM_PROGAM or USER_LANG would be), and I just see no reason for the stratification