coder/aibridge/AGENTS.md

AI Agent Guidelines for aibridge

This is a package-level guide for the aibridge/ subdirectory inside the coder/coder repository.

Read the repo-root AGENTS.md and CLAUDE.md first. They are the source of truth for all shared conventions: tone, foundational rules, essential commands, git hooks, code style, Go patterns, testing patterns, LSP navigation, and PR style. This file documents only what is specific to the aibridge/ package; it never relaxes a root rule.

For local overrides, create AGENTS.local.md (gitignored).

Architecture Overview

AI Bridge is a smart gateway that sits between AI clients (Claude Code, Cursor, etc.) and upstream providers (Anthropic, OpenAI). It intercepts all AI traffic to provide centralized authn/z, auditing, token attribution, and MCP tool administration. It runs as part of coderd (the Coder control plane). Users authenticate with their Coder session tokens.

┌─────────────┐     ┌──────────────────────────────────────────┐
│  AI Client   │     │               aibridge                   │
│ (Claude Code,│────▶│  RequestBridge (http.Handler)             │
│  Cursor)     │     │    ├── Provider (Anthropic/OpenAI)        │
└─────────────┘     │    ├── Interceptor (streaming/blocking)   │
                    │    ├── Recorder (tokens, prompts, tools)  │
                    │    └── MCP Proxy (tool injection)         │
                    └──────────────┬───────────────────────────┘
                                   │
                                   ▼
                           ┌──────────────┐
                           │ Upstream API  │
                           │ (Anthropic,   │
                           │  OpenAI)      │
                           └──────────────┘

The wire-up between aibridge and coderd lives in enterprise/aibridged/. That package is outside the scope of this guide.

Key packages within aibridge/:

• intercept/: request/response interception, per-provider subdirs (messages/, responses/, chatcompletions/)
• provider/: upstream provider definitions (Anthropic, OpenAI, Copilot)
• mcp/: MCP protocol integration
• circuitbreaker/: circuit breaker for upstream calls
• context/: request-scoped context helpers
• internal/integrationtest/: integration tests with mock upstreams

Commands

Use the repo-root commands documented in the root AGENTS.md. The notes below are aibridge-specific:

• Run only aibridge tests with go test ./aibridge/.... The root make test runs the full coder/coder suite.
• Regenerate the MCP mock with go generate ./aibridge/mcpmock/ after changing aibridge/mcp/api.go. The repo-root make gen does not include this target.

Streaming Code

This package heavily uses SSE streaming. When modifying interceptors:

• Always handle both blocking and streaming paths.
• Test with *_test.go files in the same package. They cover edge cases for chunked responses.
• Be careful with goroutine lifecycle. Ensure proper cleanup on context cancellation.

Commit and PR Scope

Follow the commit and PR style in the root AGENTS.md and .claude/docs/PR_STYLE_GUIDE.md. Format: type(scope): message. The scope must be a real filesystem path containing every changed file.

For changes inside aibridge/, the scope is the path from the repo root, for example:

• feat(aibridge/intercept/messages): add cache token tracking
• fix(aibridge/provider): handle nil response body
• refactor(aibridge/mcp): extract tool filtering

Use a broader scope, or omit the scope, when changes span beyond aibridge/.

Common Pitfalls

Problem	Fix
Race in streaming tests	Use t.Cleanup() and proper synchronization, never time.Sleep.
mcpmock out of date	Run go generate ./aibridge/mcpmock/ after changing aibridge/mcp/api.go.
Formatting failures	Run make fmt from the repo root before committing.