Configuration

CodeBuddy reads from VS Code settings. Open with Cmd/Ctrl+, and filter by “codebuddy” for the full surface. This page covers the settings you’ll touch day-to-day; the full list lives in the Settings Reference.

Providers

Configure any subset — the extension only initializes providers whose keys are present. Switch active provider via the generativeAi.option setting or the onboarding wizard.

Provider	API key setting	Model setting
Anthropic	anthropic.apiKey	anthropic.model
OpenAI	openai.apiKey	openai.model
Google Gemini	google.gemini.apiKeys	google.gemini.model
Groq	groq.llama3.apiKey	groq.llama3.model
DeepSeek	deepseek.apiKey	deepseek.model
xAI Grok	grok.apiKey	grok.model
Qwen	qwen.apiKey	qwen.model
GLM	glm.apiKey	glm.model
Local	local.apiKey + local.baseUrl	local.model

Keys are stored in the OS keychain via SecretStorageService, not in settings.json. The onboarding wizard writes them there for you; you can also set them via the “CodeBuddy: Set <Provider> API Key” commands.

Local covers Ollama (http://localhost:11434), LM Studio, Docker, and any OpenAI-API-compatible endpoint — set local.baseUrl to point at it.

Agent limits

The safety guard that catches runaway agents:

{
  "codebuddy.agent.recursionLimit": 600,        // deepagents graph depth
  "codebuddy.agent.maxEventCount": 15000,       // total stream events per task
  "codebuddy.agent.maxToolInvocations": 2000,   // total tool calls per task
  "codebuddy.agent.maxDurationMinutes": 60      // minutes
}

Hit any limit and the stream terminates with a “safety guard” error; the diff view stays clean.

Security profiles

{ "codebuddy.permissionScope.defaultProfile": "standard" }

Profile	Behavior
restricted	Read-only. No terminal, no file writes, no browser.
standard	Read/write. Terminal requires modal approval outside a small safe-command list. Default.
trusted	Same tools; auto-approves the safe-command list. Catastrophic patterns still deny.

The catastrophic-pattern deny (rm -rf /, dd if=, mkfs.*, etc.) applies even in trusted.

Access control (team mode)

{
  "codebuddy.accessControl.defaultMode": "open"  // open | allow | deny
}

For team-managed extensions where only some users should reach the agent. See Access Control.

Credential proxy

Centralize API keys behind a localhost proxy instead of shipping them to every editor instance:

{
  "codebuddy.credentialProxy.enabled": true
}

Rate-limited per provider, injects the real key at proxy time. See Credential Proxy.

Project rules

Create .codebuddy/rules.md at the repo root. CodeBuddy appends it to the system prompt in every conversation for this workspace.

# Project rules

- TypeScript strict mode
- Use Zod for input validation
- pnpm, not npm
- Every new function needs a test

Fallback filenames checked in order: .codebuddy/rules.md, .codebuddy/rules/index.md, .codebuddyrules, CODEBUDDY.md. Budget: 2000 tokens (~8000 chars); anything over is truncated with a warning.

Dynamic values are supported via {{js: EXPRESSION}} fragments (e.g. Current branch: {{js: host.gitBranch()}}). See Project Rules.

MCP servers

Server configs go in workspace settings under codebuddy.mcp.servers. First-time launch fires a modal approval showing the exact command + args + env-key names; approval persists per workspace. See MCP.

Environment variables

For CI, shell aliases, or team provisioning, providers can also be set via env:

export CODEBUDDY_ANTHROPIC_API_KEY="sk-ant-..."
export CODEBUDDY_OPENAI_API_KEY="sk-..."
# ... one CODEBUDDY_<PROVIDER>_API_KEY per provider

Extension prefers keychain > env > settings.json.

Next

• Settings Reference — the exhaustive list
• Security — full threat model + invariants
• Quickstart — first task