Configuration

Precedence

Settings resolve from lowest to highest priority:

package defaults  <  ~/.codeagent/settings.json  <  .codeagent/settings.json  <  environment variables

Scaffold a settings file:

use_codeagent_settings(scope = "user")     # ~/.codeagent/settings.json

settings.json

{
  "provider": "openai_compatible",
  "model": "main",
  "env": {
    "CODEAGENT_BASE_URL": "https://YOUR-WORKSPACE.cloud.databricks.net/serving-endpoints",
    "CODEAGENT_MODEL": "your-main-endpoint-name",
    "CODEAGENT_HEAVY_MODEL": "your-heavy-endpoint-name",
    "CODEAGENT_FAST_MODEL": "your-fast-endpoint-name"
  },
  "permissions": { "allow": [], "deny": [], "ask": [], "defaultMode": "default" },
  "sandbox": { "enabled": false, "allow_network": true },
  "effortLevel": "high"
}

The env block is applied before environment variables are read, so it works even under Rscript --vanilla.

Environment variables

Variable	Purpose
CODEAGENT_BASE_URL	OpenAI-compatible endpoint
CODEAGENT_MODEL	Default model (the "main" tier)
CODEAGENT_HEAVY_MODEL	"heavy" tier — most capable model
CODEAGENT_FAST_MODEL	"fast" tier — compaction / classification model
CODEAGENT_API_KEY	API key (never put this in settings.json)
CODEAGENT_MAX_CONTEXT_TOKENS	Override the context window
CODEAGENT_DISABLE_COMPACT	Disable auto-compaction
CODEAGENT_PERMISSION_MODE	Default permission mode

API keys

Keep API keys in ~/.Renviron as CODEAGENT_API_KEY, or use the OS keyring (offered by use_codeagent_setup()). Never store keys in settings.json.

Per-project multi-client config

# codeagent.md
---
client:
  gpt41:    openai/gpt-4.1
  deepseek: openai/deepseek-r1
btw_groups: [docs, git, pkg]
permission_mode: bypass
---
Follow tidyverse style.

client <- codeagent_client_config(alias = "gpt41")