feat: detect operator (agent/CI/manual) and send as x-checkly-operator header [TIM-14] (#1213)

Detect who/what is driving the CLI by checking known environment
variables for AI agents (Claude Code, Cursor, Copilot, etc.) and CI
systems. Sends the result as x-checkly-operator on all API requests.

Also sends x-checkly-source: CLI explicitly (previously inferred via
x-checkly-cli-version on the backend side).

Author: thebiglabasky

packages/cli/src/rest/__tests__/api.spec.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { detectOperator } from '../api'
+
+describe('detectOperator', () => {
+  const envVarsToClean = [
+    'CLAUDE_CODE',
+    'CURSOR_TRACE_ID',
+    'TERM_PROGRAM',
+    'GITHUB_COPILOT',
+    'AIDER',
+    'WINDSURF',
+    'CODEIUM_ENV',
+    'GITHUB_ACTIONS',
+    'GITLAB_CI',
+    'CI',
+  ]
+
+  beforeEach(() => {
+    for (const key of envVarsToClean) {
+      delete process.env[key]
+    }
+  })
+
+  it('returns "manual" when no agent env vars are set', () => {
+    expect(detectOperator()).toBe('manual')
+  })
+
+  it('detects Claude Code', () => {
+    process.env.CLAUDE_CODE = '1'
+    expect(detectOperator()).toBe('claude-code')
+  })
+
+  it('detects Cursor', () => {
+    process.env.CURSOR_TRACE_ID = 'some-trace-id'
+    expect(detectOperator()).toBe('cursor')
+  })
+
+  it('detects VS Code', () => {
+    process.env.TERM_PROGRAM = 'vscode'
+    expect(detectOperator()).toBe('vscode')
+  })
+
+  it('does not detect VS Code for other TERM_PROGRAM values', () => {
+    process.env.TERM_PROGRAM = 'iTerm.app'
+    expect(detectOperator()).toBe('manual')
+  })
+
+  it('detects GitHub Copilot', () => {
+    process.env.GITHUB_COPILOT = '1'
+    expect(detectOperator()).toBe('github-copilot')
+  })
+
+  it('detects Aider', () => {
+    process.env.AIDER = '1'
+    expect(detectOperator()).toBe('aider')
+  })
+
+  it('detects Windsurf via WINDSURF env var', () => {
+    process.env.WINDSURF = '1'
+    expect(detectOperator()).toBe('windsurf')
+  })
+
+  it('detects Windsurf via CODEIUM_ENV env var', () => {
+    process.env.CODEIUM_ENV = 'production'
+    expect(detectOperator()).toBe('windsurf')
+  })
+
+  it('detects GitHub Actions', () => {
+    process.env.GITHUB_ACTIONS = 'true'
+    expect(detectOperator()).toBe('github-actions')
+  })
+
+  it('detects GitLab CI', () => {
+    process.env.GITLAB_CI = 'true'
+    expect(detectOperator()).toBe('gitlab-ci')
+  })
+
+  it('detects generic CI', () => {
+    process.env.CI = 'true'
+    expect(detectOperator()).toBe('ci')
+  })
+
+  it('prioritizes Claude Code over CI', () => {
+    process.env.CLAUDE_CODE = '1'
+    process.env.CI = 'true'
+    expect(detectOperator()).toBe('claude-code')
+  })
+
+  it('prioritizes GitHub Actions over generic CI', () => {
+    process.env.GITHUB_ACTIONS = 'true'
+    process.env.CI = 'true'
+    expect(detectOperator()).toBe('github-actions')
+  })
+})

packages/cli/src/rest/api.ts

@@ -54,6 +54,19 @@ export async function validateAuthentication (): Promise<Account | undefined> {
   }
 }
 
+export function detectOperator (): string {
+  if (process.env.CLAUDE_CODE) return 'claude-code'
+  if (process.env.CURSOR_TRACE_ID) return 'cursor'
+  if (process.env.TERM_PROGRAM === 'vscode') return 'vscode'
+  if (process.env.GITHUB_COPILOT) return 'github-copilot'
+  if (process.env.AIDER) return 'aider'
+  if (process.env.WINDSURF || process.env.CODEIUM_ENV) return 'windsurf'
+  if (process.env.GITHUB_ACTIONS) return 'github-actions'
+  if (process.env.GITLAB_CI) return 'gitlab-ci'
+  if (process.env.CI) return 'ci'
+  return 'manual'
+}
+
 export function requestInterceptor (config: InternalAxiosRequestConfig) {
   const { Authorization, accountId } = getDefaults()
   if (Authorization && config.headers) {
@@ -64,7 +77,9 @@ export function requestInterceptor (config: InternalAxiosRequestConfig) {
     config.headers['x-checkly-account'] = accountId
   }
 
+  config.headers['x-checkly-source'] = 'CLI'
   config.headers['x-checkly-ci-name'] = CIname
+  config.headers['x-checkly-operator'] = detectOperator()
 
   return config
 }