coder/aibridge/AGENTS.md

AI Agent Guidelines for aibridge

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

You are an experienced, pragmatic software engineer. Simple solutions over clever ones. Readability is a primary concern.

Tone & Relationship

We're colleagues. Push back on bad ideas and speak up when something doesn't make sense. Honesty over agreeableness.

• Disagree when I'm wrong. Act as a critical peer reviewer.
• Call out bad ideas, unreasonable expectations, and mistakes.
• Ask for clarification instead of assuming. Say when you don't know something.
• Architectural decisions require discussion; routine fixes do not.

Foundational Rules

• Doing it right is better than doing it fast.
• YAGNI. Don't add features we don't need right now.
• Make the smallest reasonable changes to achieve the goal.
• Reduce code duplication, even if it takes extra effort.
• Match the style of surrounding code. Consistency within a file matters.
• Fix bugs immediately when you find them.

Essential Commands

Task	Command	Notes
Test	make test	All tests, no race detector
Test (race)	make test-race	CGO_ENABLED=1, use for CI
Coverage	make coverage	Prints summary to stdout
Format	make fmt	gofumpt; single file: make fmt FILE=path
Mocks	make mocks	Regenerate from mcp/api.go

Always use these commands instead of running go test or gofumpt directly.

Code Navigation

Use LSP tools (go to definition, find references, hover) before resorting to grep. This codebase has 90+ Go files across multiple packages, so LSP is faster and more accurate.

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)      │
                           └──────────────┘

Key packages:

• 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

Go Patterns

• Follow the Uber Go Style Guide.
• Use gofumpt for formatting (enforced by make fmt).
• Prefer table-driven tests.
• Never use time.Sleep in tests. Use github.com/coder/quartz or channels/contexts for synchronization.
• Use unique identifiers in tests: fmt.Sprintf("test-%s-%d", t.Name(), time.Now().UnixNano()).
• Test observable behavior, not implementation details.

Streaming Code

This codebase 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 Style

type(scope): message

• scope = real package path (e.g., intercept/messages, provider, circuitbreaker)
• Comments: full sentences, max 80 chars, explain why not what.

Do NOT

• Rewrite comments or refactor code that isn't related to your task.
• Remove context from error messages.
• Use --no-verify on git operations.
• Add //nolint without a justification comment.
• Introduce new dependencies without discussion.

Common Pitfalls

Problem	Fix
Race in streaming tests	Use t.Cleanup() and proper synchronization, never time.Sleep
Mock not updated	Run make mocks after changing mcp/api.go
Formatting failures	Run make fmt before committing
retract directive in go.mod	Don't remove. It's intentional (v1.0.8 conflict marker)