Skip to content

feat: detect AI coding agents in the user agent - #419

Merged
zentron merged 11 commits into
mainfrom
robe/claude-ua
Nov 22, 2026
Merged

zentron merged 11 commits into
mainfrom
robe/claude-ua

Conversation

@zentron

@zentron zentron commented May 14, 2026 •

Copy link
Copy Markdown
Contributor

Background

AI coding agents increasingly drive the Octopus CLI, the Terraform provider and other tools built on this SDK, but none of that traffic is identifiable today. Agents don't change the headers of the tools they run; they only export environment variables to the processes they launch. Reading those variables here gives the server a signal for agent-driven API usage.

Results

When an agent is detected, an (ai-agent=<Name>) comment is appended to the very end of the user agent:

go-octopusdeploy/v2.x.x (linux; amd64) go/go1.24.7 GitHubActions octopus/2.x.x (release;deploy) (ai-agent=ClaudeCode)
  • Appended last, as a comment. Everything before it is byte-for-byte what the SDK sent before, so anything that matches on the start of the header keeps working. An RFC 9110 comment describes the request rather than presenting the agent as a product/version pair.
  • AI_AGENT first. This is the emerging cross-vendor convention (@vercel/detect-agent). Its value is mapped to a known name by prefix, e.g. claude-code_2-1-322_agent → ClaudeCode, github_copilot_vscode_agent → GitHubCopilot. A prefix only matches when followed by the end of the value, a separator (-, @, .) or a digit, so amp doesn't match amplitude-mcp. The raw value is never sent, since it is free-form and user-settable. An unrecognised value reports as (ai-agent=Other).
  • Vendor variables as a fallback, checked in a fixed order so nested agents give a stable answer: Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, OpenCode, Antigravity, Goose, Amp, Cline, Roo Code, Augment, Qwen Code, Factory Droid, Kimi CLI, Trae, Aider and OpenHands. Each agent is one entry in a single list, with an optional AI_AGENT prefix and its vendor variables.
  • Noisy variables excluded. CURSOR_TRACE_ID, COPILOT_GITHUB_TOKEN, GOOSE_PROVIDER, REPL_ID and ZED_TERM are set in ordinary human sessions, so they would label people as agents.
  • Self-reported identifiers are matched after lowercasing and replacing runs of underscores and whitespace with a hyphen, so Claude Code and claude_code map the same way.
  • Nothing is added when no agent is detected, so existing user agents are unchanged.

Testing

  • ai_agent_provider_test.go covers the edge cases: value-matched rules, excluded variables, nested agents, AI_AGENT formats and precedence, the prefix boundary, and that the raw AI_AGENT value never appears. ai_agent_provider_internal_test.go checks that appending the agent leaves the existing user agent as an exact prefix. The existing CI detection tests still pass.
  • The same test cases, and a shared set of inputs including the prefix boundary cases, give identical results in the Go, .NET and TypeScript clients.
  • Detected as (ai-agent=ClaudeCode) in a real Claude Code session.
  • main is merged in and golangci-lint passes.

How to review this PR

The logic is all in pkg/services/api/ai_agent_provider.go. api.go builds the user agent exactly as before and then calls appendAIAgent. The agent list is the part most worth a second opinion: the variable names come from other detectors (.NET Aspire's CodingAgentDetector, @vercel/detect-agent, is-ai-agent) and are mostly undocumented vendor internals. This file is the reference copy of the list: the TypeScript port (api-client.ts#294) and the .NET port point back to it in a comment.

Caveats

  • Detection is self-reported and spoofable. It's suitable for analytics, not for authorisation or audit decisions.
  • Coverage depends on the list. A new agent shows up as Other (if it sets AI_AGENT) or not at all until it is added and an SDK release ships.
  • AGENT=amp comes from a secondary source. If Amp doesn't set it, that rule never fires.

Generated by Claude Code

@NickJosevski NickJosevski left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you still want this in?

@CLAassistant

CLAassistant commented Nov 12, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@zentron zentron changed the title Add ClaudeCode environment variable support feat: detect AI coding agents in the user agent Nov 12, 2026
zentron and others added 2 commits November 13, 2026 08:57
Report the AI agent driving a process as its own user agent token,
separate from the automation (CI) environment, so an agent running in
CI or on an Octopus worker reports both rather than one at random.

- Honour the emerging AI_AGENT convention, mapping known values to a
  canonical name and passing the sanitised raw value through as a comment
- Fall back to vendor variables for Claude Code, Cursor, Codex, Gemini
  CLI, GitHub Copilot, OpenCode, Antigravity, Goose, Amp, Cline, Roo
  Code, Augment, Qwen Code, Factory Droid, Kimi CLI, Trae, Aider and
  OpenHands, checked in a fixed order
- Exclude variables that are set without an agent driving the process
  (e.g. CURSOR_TRACE_ID, COPILOT_GITHUB_TOKEN, REPL_ID)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Map AI_AGENT to one of the known agent names instead of passing the raw
value through as a user agent comment. Unrecognised values report as
AIAgent/Other. The raw value is free-form and user-settable, so it is now
only used for matching, which also removes the need to sanitise it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Collapse runs of underscores and whitespace into a single hyphen before
matching a self-reported agent identifier, so a name such as
"Claude Code" maps the same way in all three clients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
zentron and others added 3 commits November 19, 2026 06:07
Merge the AI_AGENT prefix table into the agent list so each agent is one
entry, keeping two lookups (prefix, then vendor variables) so a
self-reported identity still wins. Rename the AI_AGENT local and trim the
tests to edge cases plus a happy path, matching review on the .NET port.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Match the .NET and TypeScript clients, which keep the full set. Drops the 200-character AI_AGENT case, which dated from when the raw value was sent and length-capped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Keep edge cases that guard real behaviour plus a happy path, and drop the per-agent table that restated the agent list. The same cases are used in the Go, .NET and TypeScript clients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2

@egorpavlikhin egorpavlikhin left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks to be doing the same thing as the ts client 👍

zentron and others added 4 commits November 19, 2026 14:51
A self-reported identifier now only matches an agent's prefix when the prefix is followed by the end of the identifier or a separator (-, @, .) or digit. Previously a short prefix such as "amp" matched an unrelated identifier such as "amplitude-mcp", and because self-reported identifiers take precedence, that also hid a correct match from vendor variables. Applied the same way in the Go, .NET and TypeScript clients.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
Report the agent as an RFC 9110 comment, (ai-agent=Name), appended at the very end of the User-Agent. Everything before it is byte-for-byte what the client sent before, so servers and tools that match on the start of the header keep working (Octopus Server identifies the local MCP server by the "ts-octopusdeploy octopus-mcp-server" prefix). A comment also avoids presenting the agent as a product/version pair. Applied the same way in the Go, .NET and TypeScript clients.

Also normalise AI_AGENT the same way as the .NET and TypeScript clients, and group imports per golangci-lint's gci sections now that main is merged in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T4ijpGHFpAqBBMhn5WKUq2
@zentron
zentron merged commit d22c1f8 into main Nov 22, 2026
6 checks passed
@zentron
zentron deleted the robe/claude-ua branch November 22, 2026 00:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants