PATTERN Cited by 1 source

Auto-detect agent context¶

A CLI designed for both humans and agents auto-detects when it's being driven by an agent harness (Claude Code, Cursor, Codex CLI, etc.) and drops human-oriented output chrome — spinners, progress bars, truncation, ANSI colours, interactive prompts — without requiring each agent to know and set the right flags. A GCX_AGENT_MODE=true (or equivalent) env-var override is provided as the escape hatch.

When to use this pattern¶

A CLI is the primary interface for both humans at a keyboard and agents driving the tool programmatically.
The human and agent preferences differ (pretty vs machine-parseable) enough that having one default makes the other uncomfortable.
Agents shouldn't have to set 3–5 flags on every command to get machine-parseable output.

The verbatim canonical statement¶

From the gcx launch post:

"gcx is tuned for the agent case in the ways you'd expect: it auto-detects when it's being driven by Claude Code, Cursor, or similar, and it drops spinners, truncation, and other human-friendly noise (or force it with GCX_AGENT_MODE=true)."

Mechanism¶

The tool, at startup, inspects its environment for signatures that it's running inside an agent harness:

Detection signal	What it tells the tool
Env var set by the harness (`CLAUDE_CODE=1`, `CURSOR_`, `CODEX_`)	Definitive — harness is self-identifying
`TERM=dumb` / no TTY on stdout	Likely non-interactive; drop spinners
Parent process name (`claude`, `cursor`, `codex`)	Supplementary signal
Explicit override env var (`GCX_AGENT_MODE=true`)	Definitive — force agent mode
Explicit human-mode flag	Definitive — force human mode

When any agent signal is present, the CLI switches behaviour:

Human mode (default when no signal)	Agent mode (auto when signal present)
ANSI colour output	Plain text
Spinners, progress bars	Plain start/end messages
Paginated long output	Streamed full output
Truncated `...` on long lists	Full list
Interactive prompts	Non-interactive — require flag or error
Pretty-printed tables	Structured output via `--output`

The agent doesn't have to know any of this. It runs gcx … as if it were git or kubectl, and the tool does the right thing.

Why the env-var override matters¶

Auto-detection isn't perfect. Cases where the override is needed:

Agent running in an unusual harness the tool doesn't know about yet.
CI pipeline that wants agent-mode output regardless of TTY heuristics.
Testing / scripting where the caller wants predictable output.

The env var GCX_AGENT_MODE=true (or equivalent) resolves all of these by letting the caller force the mode.

Contrast with "explicit flag on every command"¶

Approach	Problem
Require `--json` on every command for agent mode	Agent has to remember 1 flag × N commands; easy to miss
Require `--quiet --no-color --no-pager --no-truncate …`	Verbose; different agents will invent different combinations
Require a one-time agent-mode config	Ambient global state — see
concepts/named-contexts-for-multi-stack anti-pattern
Auto-detect + env override	Zero configuration for the common case; escape hatch for edge cases

The auto-detect approach is strictly dominant when the detection signals are reliable.

Tradeoffs¶

Detection false negatives — a new harness that doesn't set a recognised env var gets human mode by default; the env-var override is the compensation.
Detection false positives — a human using TERM=dumb gets agent mode; they can pass a --human flag or set GCX_AGENT_MODE=false to switch back.
Version drift in detection signals — harnesses update their env vars periodically; the tool must keep up.

Composition with other agent-ergonomic-CLI primitives¶

With concepts/json-output-stability and concepts/structured-output-reliability: agent-mode default is structured output with stable fields, so the agent never has to think about output formatting.
With patterns/destructive-operation-confirmation-as-agent-guardrail: in agent mode, interactive confirmation prompts must be replaced with a confirmation flag — so destructive commands fail loudly rather than silently hanging on an absent TTY.
With concepts/machine-readable-command-catalog: the catalog can include per-command agent-mode output schemas, letting the agent validate before parsing.

Seen in¶

sources/2026-04-29-grafana-get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool — canonical statement of auto-detect-agent-context as a shipping mechanism. Grafana's gcx auto-detects Claude Code / Cursor / similar and drops spinners + truncation; GCX_AGENT_MODE=true is the explicit override. First observability-vendor-shipped instance of the pattern as a named mechanism.