Use gcx with AI agents
Both people and AI coding agents use the same gcx commands. However, when gcx detects that an agent is running it, it switches to agent mode, which has different defaults, such as the output format and how confirmation prompts behave.
Before you begin
- Install
gcxwhere your agent runs. - Authenticate
gcx. If the agent runs without a person present, refer to Sign in for agents.
How agent mode works
gcx turns on agent mode automatically when it finds an environment variable set by a supported agent tool, such as Claude Code, Cursor, GitHub Copilot, Codex, or Gemini CLI.
The main differences between modes are the following:
You can override these defaults with explicit flags. For example, -o text prints a table in agent mode, and -o json prints JSON without agent mode. For manual overrides and output details, refer to Customize detection, output, and error handling.
Install agent skills
gcx ships agent skills: task-specific instructions that teach an agent common workflows, such as setting up gcx, creating dashboards, investigating alerts, and managing SLOs. For the full list, refer to the skill inventory.
For Claude Code, install the gcx plugin:
/plugin marketplace add grafana/gcx
/plugin install gcx@gcx-marketplaceFor other tools that use the .agents skill convention, such as OpenAI Codex, OpenCode, and Pi, use gcx agent skills:
# List the bundled skills and whether they're installed
gcx agent skills list
# Install all skills into ~/.agents/skills (use --dir for another .agents root)
gcx agent skills install --all
# Refresh installed skills after you upgrade gcx
gcx agent skills update
# Remove a skill
gcx agent skills uninstall <SKILL>gcx agent skills update doesn’t add skills that are new in the bundle. To add them, run gcx agent skills install --all again.
Discover skills and commands on demand
If your tool doesn’t use the Claude Code plugin or ~/.agents/skills (for example in Cursor, GitHub Copilot, or a custom agent integration), you don’t need to install any files. Your agent can read bundled skills on demand and discover commands progressively:
# Print a bundled skill without writing files to disk
gcx agent skills get <SKILL>
# Orient on top-level command groups in a compact text tree
gcx help-tree --depth 1 -o text
# Drill into one command group with inline arguments, flags, and agent hints
gcx help-tree resources -o text
# Output the full JSON catalog of commands, cost estimates, and resource types
gcx commandsSign in for agents
An agent can do anything that its gcx credential allows, so make sure you use a credential with only the permissions the agent’s tasks need. Refer to Roles and permissions.
When a person is present, use browser-based OAuth. gcx opens a browser and waits for you to approve the sign-in:
gcx login my-stack --server https://my-stack.grafana.net --oauth- If the agent’s environment can’t receive the browser callback, add
--oauth-manual.gcxprints the URL, and you paste back the redirect URL. - If the agent runs
gcxin a sandbox that blocks writes to the operating system credential store,gcxstops before the browser opens. Approve the command to run outside the sandbox. Refer to Restricted execution sessions.
When no person is present, such as in CI or a scheduled job, use a service account token. Set it with environment variables, or save it to a context:
gcx login my-stack --server https://my-stack.grafana.net --token <SERVICE_ACCOUNT_TOKEN> --yesAllow destructive operations
Agent mode never approves a destructive operation by itself. Commands that require a confirmation prompt to a person fail in agent mode unless you allow the operation in one of these ways:
- Pass
--forceto that command. - Set
GCX_AUTO_APPROVE=truein the agent’s environment.GCX_AUTO_APPROVEaccepts1,t, ortrue. Other values, such asyes, make the command fail.
gcx resources delete uses its own guard instead of a prompt: deleting every resource of a type requires --force or --yes.
Ask your agent to check with you before it adds --force, and avoid setting GCX_AUTO_APPROVE in a shell that people also use.
Customize detection, output, and error handling
Override agent mode detection
If your tool isn’t detected automatically, set GCX_AGENT_NAME to a supported label in the agent’s command environment:
GCX_AGENT_NAME=crush gcx resources get dashboardsSet the label only in the agent’s environment, not in a shell that people also use. Supported labels for GCX_AGENT_NAME (and the shared AI_AGENT variable) are aider, amazon-q, amp, augment, claude-code, cline, codex, crush, cursor, devin, factory-droid, gemini-cli, github-copilot, goose, hermes, junie, kilo-code, kiro, openclaw, opencode, openhands, pi, and qwen-code. Refer to Environment variables for variable details and precedence.
To turn agent mode on or off regardless of detection:
The --agent flag takes precedence over environment variables. GCX_AGENT_MODE accepts 1, true, or yes to turn agent mode on, and 0, false, or no to turn it off. Other values, such as off, are ignored.
Select fields instead of parsing output
Use --json and --jq to shape the output inside gcx, instead of piping it to other tools:
# List the fields that the command can return
gcx resources get dashboards --json list
# Return only some fields
gcx resources get dashboards --json metadata.name,spec.title
# Transform the output with a jq expression
gcx resources get dashboards --jq '.items | length'Large results
When a result is larger than 100 KiB, gcx writes the full result to a temporary file named gcx-results-*.json and prints a short receipt to stdout instead:
{
"type": "gcx.spill_reference",
"schema_version": "1",
"spilled_to": "/tmp/gcx-results-3781234567.json",
"bytes": 143200,
"content_format": "json",
"total_items": 312,
"preview_sample": [
{
"metadata": {
"name": "prod-overview"
}
}
],
"message": "Response too large for stdout (143200 bytes). Full data written to /tmp/gcx-results-3781234567.json. Read that file for complete results, or rerun with -o json to force inline output."
}For list responses, preview_sample contains only the first 3 items (or sorted top-level keys for objects)—never the complete result. Read the file at spilled_to for the full data. When --jq is combined with -o agents, oversized jq streams spill to gcx-results-*.jsonl with content_format set to "jsonl", total_values instead of total_items, and preview_sample set to null.
To control this behavior:
- Pass
-o jsonto write the full JSON tostdoutwithout spilling. - Redirect
stdoutto a file, for examplegcx resources get dashboards > dashboards.json, to write the full result to that file. - Set
GCX_AGENT_SPILL_BYTESto change the threshold in bytes. Set it to0to turn off spilling. - Run
gcx agent pruneto remove spill files older than 30 minutes, for example at the end of an agent session.
Errors
In agent mode, a failed command writes one JSON error document to stdout, and the exitCode field matches the process exit code:
{"type": "gcx.error", "schema_version": "1", "error": {"summary": "Resource not found", "exitCode": 1}}The error object can also include details, suggestions, and docsLink. When a batch operation partly succeeds, the document has the type gcx.partial_result and includes the successful items alongside the error.
To record failed agent-mode calls locally for debugging, enable diagnostics.agent-invocation-log in your configuration:
gcx config set diagnostics.agent-invocation-log trueWhen enabled, gcx writes failed agent-mode invocations (up to 1,000 JSONL records) to ~/.local/state/gcx/agent-invocation-errors.jsonl ($XDG_STATE_HOME/gcx/agent-invocation-errors.jsonl), or to diagnostics.log-dir if configured.
Learn more
- Diagnose missing telemetry: An example workflow that uses an agent with
gcxskills. - Usage statistics: What
gcxreports about agent use, and how to opt out.


