Settings Configuration

CodeBuddy Code uses a layered configuration system that enables personalization at different levels, from personal preferences to team standards to project-specific requirements.

Configuration Files

The settings.json file is the official mechanism for configuring CodeBuddy Code, supporting layered settings:

• User settings are defined in ~/.codebuddy/settings.json and apply to all projects
• Project settings are stored in the project directory:
  • .codebuddy/settings.json for settings checked into source control and shared with the team
  • .codebuddy/settings.local.json for settings not checked in, suitable for personal preferences and experiments. CodeBuddy Code automatically configures git to ignore this file

Complete Configuration Example

{
  "language": "English",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "codebuddy:*"
  },
  "model": "gpt-5",
  "subagents": {
    "agents": {
      "Explore": { "model": "lite" },
      "Plan": { "model": "reasoning" }
    }
  },
  "variantModels": {
    "lite": "<fast-model-id>",
    "reasoning": "<reasoning-model-id>"
  },
  "cleanupPeriodDays": 30,
  "includeCoAuthoredBy": false,
  "statusLine": {
    "type": "command",
    "command": "~/.codebuddy/statusline.sh"
  }
}

Available Settings

settings.json supports the following options:

Key	Description	Example
language	Preferred response language. When set, CodeBuddy Code will respond in the specified language. Leave empty to auto-detect based on user input	"English"
apiKeyHelper	Custom script executed in /bin/sh that generates an authentication value. This value is sent as both X-Api-Key and Authorization: Bearer headers for model requests	/bin/generate_temp_api_key.sh
textToImageModel	Model ID used for text-to-image generation	"your-image-model"
imageToImageModel	Model ID used for image-to-image generation	"your-edit-model"
cleanupPeriodDays	How long to locally retain chat history based on last activity date (default: 30 days)	20
env	Environment variables applied to every session	{"FOO": "bar"}
includeCoAuthoredBy	Whether to include co-authored-by CodeBuddy attribution in git commits and pull requests (default: true)	false
permissions	Permission configuration, see table below
autoReview	Review policy for auto permission mode: policy replaces the built-in security policy, extraPolicy appends to it. See Auto Mode Configuration	{"extraPolicy": "Allow dev environment releases"}
autoMode	Legacy natural-language auto rules (environment / allow / soft_deny / hard_deny); still supported and rendered as additional policy. See Auto Mode Configuration	{"allow": ["Allow dev environment releases"]}
hooks	Configure custom commands to run before and after tool execution. See hooks documentation	{"PreToolUse": {"Bash": "echo 'Running command...'"}}
disableAllHooks	Disable all hooks	true
allowUntrustedFrontmatterHooks	Whether to allow execution of frontmatter hooks fields from agents/skills with non-product-builtin sources (including local user .codebuddy/agents|skills/*.md and the plugin marketplace). Defaults to false to prevent untrusted md files from silently launching shell commands; only product-builtin agents/skills are unaffected.	true
model	Override the default model used by CodeBuddy Code. Already opened sessions are not affected after directly editing settings.json (need to restart the process or run /clear to create a new session before the new value takes effect); switching via /model or /config set model takes effect immediately	"gpt-5"
outputStyle	Output style. Already opened sessions are not affected after directly editing settings.json (need to restart the process or run /clear to create a new session before the new value takes effect); switching via the style panel (/output-style) or /config set outputStyle takes effect immediately	"concise"
subagents	Specify models per built-in sub-agent name. Structure: {"agents": {"<sub-agent-name>": {"model": "..."}}}; model supports model ID, name, alias, lite / reasoning or inherit / default. Each sub-agent is independent, supporting both global and project scopes. Can be visually edited in the /agents panel. Priority: CODEBUDDY_CODE_SUBAGENT_MODEL > tool invocation model parameter for this call > project settings > global user settings > built-in declaration > main model. See Sub-Agents Documentation	{"agents": {"Explore": {"model": "lite"}, "Plan": {"model": "reasoning"}}}
variantModels	Map common scenario variants to models. Key is lite or reasoning, value is model ID or alias. This mapping affects all logic using the corresponding variant. Can be edited via /model:lite / /model:reasoning. Priority: corresponding variant environment variable > project settings > global user settings > main model's relatedModels > applicable product built-in default > main model	{"lite": "<fast-model-id>", "reasoning": "<reasoning-model-id>"}
agent	Override the agent name used by the main thread (built-in or custom agent), applying that agent's system prompt, tool restrictions, and model configuration. Priority: product.json default → plugin agent → settings.json agent → CLI --agent	"my-reviewer"
codebuddy.mainAgent	Four main-agent modes (cli / ptc / minimal / create) plus custom agents. Keys: enabled master switch (on by default); allowUnopted whether ACP hosts that do not declare mainAgentSupport (WorkBuddy) use mode resolution (off by default, always native cli); default written only by "set as default"; lastUsed is the last Web chip / TUI /agent-mode / new-agent pick and does not override default. Process --agent overrides lastUsed and does not write default. When neither default nor lastUsed is set, new sessions in the interactive TUI default to PTC, while all other entry points (including Agent View / --bg background sessions) default to cli. Env CODEBUDDY_MAIN_AGENT_ENABLED / CODEBUDDY_MAIN_AGENT_ALLOW_UNOPTED win. CLI: codebuddy config set codebuddy '{"mainAgent":{"enabled":true,"allowUnopted":false}}'	{"enabled": true, "allowUnopted": false, "default": "cli"}
codebuddy.agentHome	Two switches for Agent Home (AI teammates / channels / task board). The Web UI has a single workspace, the contacts directory, with no more "solo / team" mode switch: orchestration is the user-facing autonomy switch (Settings → "AI Teammates → Allow agents to form teams autonomously"), which only controls whether agents can autonomously create teammates, create channels, write to the task board, post, and send direct messages, plus channel reminder injection, mutual wake-up, and the turn watchdog. It is off by default; when off, the contacts directory and existing teammates, channels, and Jobs are still shown as usual. The first time the CLI Web UI is opened in a browser (not an embedded iframe) and it has never been configured, it auto-writes true once; browsers that picked "solo" in older versions are migrated to false once, and values already explicitly configured in settings are never overwritten. enabled is the ops rollback key; when explicitly false, the Web UI falls back to the regular session / Job list (existing room data is untouched). Both keys only affect sessions launched by the Web UI and AI teammates' Jobs; TUI, WorkBuddy, IDE ACP, -p, and SDK stream-json sessions are unaffected. When autonomy is off, teammates are not woken, wake-up tickets are not consumed, team context is not injected, and team tools are not exposed; the wake-up loop, inbox, and watchdog only start after autonomy is enabled, and if autonomy is turned off again in the same process they idle without taking actions, stopping completely after a process restart. When the contacts directory is first built, still-running background Jobs with user-given names are adopted as teammates only if autonomy is on; when autonomy is off, these Jobs are shown as unowned Jobs and behave unchanged. Precedence: CODEBUDDY_AGENT_HOME_ENABLED (=0 disables everything, =1 force-enables everything) > enabled=false > CODEBUDDY_AGENT_HOME_ORCHESTRATION_ENABLED (locks autonomy only) > orchestration. When locked by an environment variable, the settings toggle is grayed out with the reason shown	{"orchestration": true}
statusLine	Configure a custom status line to display context. See statusLine documentation	{"type": "command", "command": "~/.codebuddy/statusline.sh"}
enableAllProjectMcpServers	Auto-approve all MCP servers defined in the project's .mcp.json file	false
enabledMcpjsonServers	List of specific MCP servers approved from .mcp.json files	["memory", "github"]
disabledMcpjsonServers	List of specific MCP servers rejected from .mcp.json files	["filesystem"]
autoCompactEnabled	Enable auto-compaction	true
autoCompactWindow	Context window baseline (tokens) used to calculate auto-compaction. Trigger point = min(this value, effective model budget) × threshold; when unset, follows the model context window, clamped to [100k, 1M] and never exceeding the model's actual context window. The CODEBUDDY_AUTO_COMPACT_WINDOW environment variable takes higher priority	200000
autoUpdates	Auto-update settings	false
daemon.preventSleep	Prevent the system from sleeping automatically; defaults to true while still letting the display turn off normally. The Web UI "Global Settings → Advanced" toggle takes effect immediately at runtime; when off, the system sleeps per its own settings, and wake detection and auto-reconnect remain in place. User-level configuration only; the environment variable CODEBUDDY_DAEMON_ALLOW_SLEEP=1/true takes precedence and forces sleep to be allowed	{"preventSleep": false}
daemon.autoRestartOnUpdate	Whether the daemon automatically restarts into the new version when idle after it auto-installs an update (or detects that the CLI on disk has been upgraded) (default true). When off, it stays pending restart and can be restarted manually from the Web UI / Desktop; the environment variable CODEBUDDY_DAEMON_AUTO_RESTART_DISABLED=1 forces it off. See autoUpdate in GET /api/v1/info for status, and use POST /api/v1/update/check to check immediately	{"autoRestartOnUpdate": false}
alwaysThinkingEnabled	Always enable thinking mode. When explicitly set to false, Chat service gateway requests send reasoning_effort: "none"; the per-session thinking toggle takes precedence over this setting. Third-party Chat and Responses requests keep their original behavior — the actual effect of disabling depends on gateway and model support	true
showTokensCounter	Whether to show the tokens counter in the interface	false
showContextUsage	Whether to always show the current context window usage in the TUI input area (by default it appears only after the reminder threshold)	false
showTurnDuration	Whether to display the turn duration after each response, such as ✔ Worked for 1m 31s; interrupted turns and turns ending in an error are not displayed (default: true)	false
endpoint	Custom server endpoint address	"https://api.example.com"
envRouteMode	Environment routing mode configuration	"production"
sandbox	Bash sandbox configuration, see Bash Sandbox Settings	{"enabled": true}
promptSuggestionEnabled	Enable prompt suggestions, automatically predicting next actions after the agent completes a conversation (default: true)	false
reasoningEffort	Reasoning effort level, controlling the depth of model reasoning. Options: minimal, low, medium, high, xhigh, max. When empty, uses the product configuration default. Can be toggled via the /config panel; selecting auto is equivalent to clearing this setting	"high"
memory	[Experimental] Memory feature configuration, see Memory Configuration	{"enabled": true}
trustedDirectories	List of working directories that have already been trusted. Matching directories will not trigger the "trust this directory" authorization prompt at startup. Usually populated automatically by the first-run popup, but can also be edited manually	["~/workspace/myproj"]
trustAll	Trust all working directories, so the "trust this directory" authorization prompt no longer appears at startup. Only exempts directory trust authorization — does not skip tool execution approval. Whether tool approval is prompted is still governed by permissions.defaultMode / bypassPermissions mode and is independent from this field	true
gateway	Remote Gateway configuration, see Gateway Configuration	{"runTimeoutMs": 1800000}
disableUEAutoExclude	Disable Unreal Engine project auto-exclusion. Default false: when a *.uproject file exists at the top level of the cwd, the Grep/Glob tools automatically exclude the six UE compile-output and IDE cache directories Intermediate/ DerivedDataCache/ Saved/ Binaries/ Build/ .vs/ from ripgrep searches. Set to true to disable this behavior so searches cover those directories	true

Permission Settings

Key	Description	Example
allow	Array of permission rules allowing tool use. Note: Bash rules use prefix matching, not regex	[ "Bash(git diff:*)" ]
ask	Array of permission rules requiring confirmation for tool use	[ "Bash(git push:*)" ]
deny	Array of permission rules denying tool use. Used to exclude CodeBuddy Code from accessing sensitive files. Note: Bash patterns are prefix-matched and can be bypassed (see Bash Permission Limitations)	[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectories	Additional working directories that CodeBuddy can access	[ "../docs/" ]
defaultMode	Default permission mode when opening CodeBuddy Code. Common values: default, acceptEdits, auto, dontAsk, plan, bypassPermissions	"acceptEdits"
disableBypassPermissionsMode	Set to "disable" to prevent activating bypassPermissions mode. This disables -y and --dangerously-skip-permissions, and also prevents CODEBUDDY_IS_SANDBOX from enabling full pass	"disable"
disableAutoMode	Set to "disable" to prevent activating auto mode. When disabled, both --permission-mode auto and defaultMode: "auto" fall back to default	"disable"
subagentPermissionMode	Override the default permission mode for subagents/team members. When set, all subagents use this mode instead of inheriting from the main session's mode. The mode parameter of the Agent tool takes higher priority; however, if the main session is in auto / dontAsk, subagents are still constrained by the parent session's permission ceiling	"bypassPermissions"

Auto Mode Configuration

auto mode's policy lives in two top-level settings fields, neither of which is a subfield of permissions:

Field	Purpose
autoReview	The current policy: policy replaces the built-in security policy, extraPolicy is appended after it
autoMode	Legacy natural-language rules; still supported as additional policy

What fields are in autoReview?

Key	Purpose	Example
policy	Replaces the built-in security policy with the full text	"## Trusted boundary\n- Internal source control: git.example.com"
extraPolicy	Appended after the security policy; every source contributes	"Allow dev namespace releases"

policy replaces only the security policy itself; how your authorization is understood and how risk is graded still comes from the product.

Do legacy autoMode rules still work?

Yes, but they are now additional policy only:

• The four fields environment / allow / soft_deny / hard_deny are appended after autoReview.extraPolicy
• Each item is a natural-language rule for auto, not a regex or a tool pattern
• "$defaults" no longer expands built-in rules and is ignored
• Prefer autoReview.policy / autoReview.extraPolicy for new configuration; autoMode remains for existing settings

Where is the policy read from?

Source	Typical Location	Purpose
user settings	~/.codebuddy/settings.json	Cross-project personal policy
project-local settings	.codebuddy/settings.local.json	Local supplement for a project on a machine
CLI --settings	codebuddy --settings '{...}'	One-time automation or temporary override
request session settings	passed by the SDK / host with the request	Policy the caller applies to this session

Shared project configuration .codebuddy/settings.json is not read: a checked-in repository should not be able to quietly relax the review of its own actions.

Sources merge in the order user → project-local → CLI → session:

• policy: a later source replaces an earlier one
• extraPolicy and legacy autoMode rules: all concatenated

Which model is used?

auto uses the model resolved from the lite variant by default. To pin the model it uses, configure it explicitly:

{
  "subagents": {
    "agents": {
      "autoModeClassifier": { "model": "<fast-model-id>" }
    }
  }
}

• The value can be a model ID or alias, or the lite / reasoning variant name. Set it to inherit / default, or remove the entry, to return to the default
• CODEBUDDY_CODE_SUBAGENT_MODEL overrides the model for all subagents, including auto

Difference from permissions.defaultMode: "auto"

There are two easily confused restrictions here:

1. Policy sources: user / project-local / CLI / session
2. Authorization to enter auto by default: only user / CLI

In other words:

• .codebuddy/settings.local.json can provide autoReview / autoMode
• But it cannot make a session default to auto via permissions.defaultMode: "auto"
• .codebuddy/settings.json can do neither: it can neither provide the policy nor grant defaultMode: "auto"

How to check the current effective result?

codebuddy auto-mode defaults   # print the built-in security policy
codebuddy auto-mode config     # print the policy source and additional policy

Configuration Examples

Append organization rules to the built-in policy

{
  "permissions": {
    "defaultMode": "auto"
  },
  "autoReview": {
    "extraPolicy": "## Organization additions\n- Allow dev namespace releases\n- Do not modify the shared test database schema"
  }
}

Replace the security policy entirely

{
  "autoReview": {
    "policy": "# Security Policy\n\n## Trusted boundary\n- Internal source control: git.example.com and all repos under it\n- Trusted domains: *.internal.example.com\n\n## Allow rules\n- Sending data to the trusted destinations above is not egress\n\n## Deny rules\n- Deny any action that exposes credentials or private repository content to the public internet"
  }
}

Keep using legacy autoMode rules

{
  "autoMode": {
    "environment": [
      "Trusted internal domains: staging.example.com"
    ],
    "soft_deny": [
      "Modify shared test database schema"
    ]
  }
}

Memory Configuration (Experimental)

Memory allows CodeBuddy Code to maintain persistent memory across sessions, automatically managing project context and learning history.

Key	Description	Example
autoMemoryEnabled	Whether to enable Auto Memory (default: true). Auto Memory allows CodeBuddy to automatically manage persistent cross-session memory, stored in ~/.codebuddy/memories/	true
typedMemory	Whether to enable Typed Memory mode (default: true). When enabled, uses 4 memory types (user/feedback/project/reference) + YAML frontmatter format for memory management	true
relevanceSelection	Whether to enable memory relevance selection (default: true). When enabled, automatically selects up to 5 relevant memories to inject into context based on user queries	true
memoryExtraction	Whether to enable background memory extraction (default: false). When enabled, automatically extracts information worth remembering from conversations at the end of a session	true
parentDiscovery	Whether to recursively search upward beyond the startup directory for project instruction files CODEBUDDY.md/AGENTS.md (default: true). When set to false, only the main file and rules directory of the startup directory itself are loaded, and instructions from parent directories (including those outside the workspace) are not inherited	false
teamMemory.enabled	Whether to enable team memory mode (default: false). When enabled, project memories are stored in the project directory for team sharing	true
teamMemory.userId	Team user ID for isolating different users' memories. Defaults to auto-detection (git user.name > system username)	"yangsubo"

Configuration example:

{
  "memory": {
    "autoMemoryEnabled": true,
    "typedMemory": true,
    "relevanceSelection": true,
    "memoryExtraction": false,
    "parentDiscovery": true,
    "teamMemory": {
      "enabled": true,
      "userId": "yangsubo"
    }
  }
}

Memory storage locations:

• Personal mode (default): ~/.codebuddy/memories/{project-id}/
• Team mode: {project}/.codebuddy/memories/@{user-id}/
• Global memory: ~/.codebuddy/memories/global/

This feature can also be enabled via the /config command in the settings panel.

Bash Sandbox Settings

Configure advanced sandbox behavior. The sandbox isolates bash commands from your filesystem and network. See Bash Sandbox Documentation for details.

Filesystem and network restrictions are configured via Read, Edit, and WebFetch permission rules, not through these sandbox settings.

Key	Description	Example
enabled	Enable bash sandbox (macOS/Linux only). Default: false	true
autoAllowBashIfSandboxed	Auto-approve bash commands in sandbox environment. Default: true	true
excludedCommands	Commands that should run outside the sandbox; WorkBuddy Desktop ignores this setting, so commands continue through the normal sandbox and approval flow	["git", "docker"]
allowUnsandboxedCommands	Allow running commands outside sandbox via dangerouslyDisableSandbox parameter. Set to false to completely disable
network.allowUnixSockets	Unix socket paths accessible in sandbox (for SSH agents, etc.)	["~/.ssh/agent-socket"]
network.allowLocalBinding	Allow binding to localhost ports (macOS only). Default: false	true
network.httpProxyPort	HTTP proxy port if you want to use your own proxy. If unspecified, CodeBuddy runs its own proxy	8080
network.socksProxyPort	SOCKS5 proxy port if you want to use your own proxy. If unspecified, CodeBuddy runs its own proxy	8081
enableWeakerNestedSandbox	Enable weaker sandbox for unprivileged Docker environments (Linux only). Reduces security. Default: false	true

Configuration example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

Filesystem access is controlled via Read/Edit permissions:

• Read deny rules block file reads in sandbox
• Edit allow rules permit file writes (beyond defaults like the current working directory)
• Edit deny rules block writes within allowed paths

Note: The sandbox adds CodeBuddy configuration files (settings.json, settings.local.json) to a write-protection list by default, preventing commands or tools inside the sandbox from tampering with configuration. See Bash Sandbox - Configuration File Protection for details.

Network access is controlled via WebFetch permissions:

• WebFetch allow rules permit network domains
• WebFetch deny rules block network domains

Settings Priority

Settings are applied in priority order (highest to lowest):

1. Command-line arguments

   • Temporary overrides for a specific session

2. Local project settings (.codebuddy/settings.local.json)

   • Personal project-specific settings

3. Shared project settings (.codebuddy/settings.json)

   • Team-shared project settings in source control

4. User settings (~/.codebuddy/settings.json)

   • Personal global settings

This hierarchy ensures teams can establish shared standards while still allowing individual customization.

Configuration System Key Points

• Memory files (CODEBUDDY.md): Contain instructions and context that CodeBuddy loads at startup
• Settings files (JSON): Configure permissions, environment variables, and tool behavior
• Slash commands: Custom commands callable via /command-name during sessions
• MCP servers: Extend CodeBuddy Code with additional tools and integrations
• Priority: Higher-level configurations override lower-level ones
• Inheritance: Settings are merged; more specific settings add to or override broader ones

Excluding Sensitive Files

To prevent CodeBuddy Code from accessing files containing sensitive information (such as API keys, secrets, environment files), use the permissions.deny setting in .codebuddy/settings.json:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

Files matching these patterns will be completely invisible to CodeBuddy Code, preventing any accidental exposure of sensitive data.

Gateway Configuration

The gateway field configures the behavior of the Remote Gateway (which exposes endpoints such as /api/v1/runs over HTTP/SSE in --serve mode).

{
  "gateway": {
    "auth": "none",
    "maxConnections": 5,
    "tokenTtlMs": 86400000,
    "runTimeoutMs": 1800000
  }
}

Field	Description	Default
auth	Authentication mode. "password" requires the client to present a password; "none" performs no authentication. Defaults to "password" for --serve when not explicitly configured; explicitly set to "none" to disable (any process on the same machine can execute commands and read/write files through this service, recommended only for isolated environments / CI)	"password" (--serve)
password	The password used when auth: "password". If empty, one is automatically generated and printed to the log on first launch	Auto-generated
corsOrigins	Additional Origins allowed for cross-origin Gateway access. The loopback origin from the service's own listening port is automatically allowed; localhost pages from other ports must be explicitly declared here (e.g., a local development Vite dev server)	[]
maxConnections	Maximum concurrent ACP protocol connections. The environment variable CODEBUDDY_ACP_MAX_CONNECTIONS takes higher priority	5
tokenTtlMs	ACP session token lifetime (milliseconds). The environment variable CODEBUDDY_ACP_TOKEN_TTL_MS takes higher priority	86400000 (24 hours)
runTimeoutMs	Execution timeout for /api/v1/runs tasks (milliseconds). On timeout, returns {code:'EXECUTION_ERROR', message:'Task timed out after Xmin'}	1800000 (30 minutes)

runTimeoutMs Override Priority

Long-running tasks (such as complex agent multi-round searches or large-file processing) may exceed the default 30 minutes. Two override mechanisms are supported:

1. HTTP request header X-Codebuddy-Run-Timeout (in milliseconds) — per-request override, highest priority
2. gateway.runTimeoutMs in settings.json — process-level default
3. Built-in default — 30 minutes

Example:

# Give a single request 60 minutes
curl -X POST http://127.0.0.1:7890/api/v1/runs \
  -H "Content-Type: application/json" \
  -H "X-Codebuddy-Run-Timeout: 3600000" \
  -d '{"id":"run-1","type":"message","payload":{"text":"..."}}'

Set to 0 or a negative value to disable timeout protection (not recommended; an unfinished long-running task will keep occupying the SSE long connection).

Sub-Agent Configuration

CodeBuddy Code supports independently selecting models for built-in sub-agents, as well as creating custom sub-agents via Markdown files.

Built-in sub-agents and scenario models can be combined in user-level or project-level settings.json:

{
  "subagents": {
    "agents": {
      "Explore": { "model": "lite" },
      "Plan": { "model": "reasoning" }
    }
  },
  "variantModels": {
    "lite": "<fast-model-id>",
    "reasoning": "<reasoning-model-id>"
  }
}

• Use /agents to edit built-in sub-agent mappings; use /model:lite / /model:reasoning to edit lite and reasoning mappings.
• Global writes to user settings, Project writes to shared project settings.
• subagents merges by sub-agent name, variantModels merges by variant name. Project-level overriding Explore will not delete other sub-agent configurations at the user level; project-level overriding reasoning will not delete user-level lite either.
• Selecting Inherit / Default in /agents, or selecting Default in /model, will delete the corresponding entry for the selected scope and restore the lower-priority resolution chain.

Custom sub-agents are stored as Markdown files with YAML frontmatter:

• User sub-agents: ~/.codebuddy/agents/ - Available across all projects
• Project sub-agents: .codebuddy/agents/ - Project-specific, shareable with the team

Sub-agent files define specialized prompts, models, and tool permissions. For complete configuration methods and priority, see Sub-Agents Documentation.

Plugin Configuration

CodeBuddy Code supports a plugin system that allows you to extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at user and project levels.

Plugin Settings

Plugin-related settings in settings.json:

{
  "enabledPlugins": {
    "formatter@company-tools": true,
    "deployer@company-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company/codebuddy-plugins"
      }
    }
  }
}

enabledPlugins

Controls which plugins are enabled. Format: "plugin-name@marketplace-name": true/false

Scopes:

• User settings (~/.codebuddy/settings.json): Personal plugin preferences
• Project settings (.codebuddy/settings.json): Project-specific plugins shared with the team
• Local settings (.codebuddy/settings.local.json): Per-machine overrides (not committed)

Example:

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

extraKnownMarketplaces

Defines additional marketplaces that should be available for the project. Typically used in project-level settings to ensure team members can access required plugin sources.

When a project includes extraKnownMarketplaces:

1. Team members are prompted to install marketplaces when trusting the folder
2. Team members are then prompted to install plugins from that marketplace
3. Users can skip unwanted marketplaces or plugins (stored in user settings)
4. Installation respects trust boundaries and requires explicit consent

Example:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "company-org/codebuddy-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/security/plugins.git"
      }
    }
  }
}

Marketplace source types:

• github: GitHub repository (using repo)
• git: Any git URL (using url)
• directory: Local filesystem path (using path, for development only)

Managing Plugins

Use the /plugin command to interactively manage plugins:

• Browse available plugins in marketplaces
• Install/uninstall plugins
• Enable/disable plugins
• View plugin details (provided commands, agents, hooks)
• Add/remove marketplaces

See Plugin Documentation for details.

Environment Variables

CodeBuddy Code supports environment variables to control its behavior. All environment variables can also be configured in the env field of settings.json, which automatically applies them to every session or rolls out configuration for an entire team.

For the complete environment variable reference, see Environment Variables Reference.

Quick Start

Basic authentication configuration:

# Using API key
export CODEBUDDY_API_KEY="your-api-key"
codebuddy

# Or using auth token
export CODEBUDDY_AUTH_TOKEN="your-token"
codebuddy

Setting up proxy:

export HTTPS_PROXY="https://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
codebuddy

Enabling advanced features:

# Extended thinking
export MAX_THINKING_TOKENS="10000"

# Auto memory
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

codebuddy -p "your query"

Configuring in settings.json

Environment variables can also be set in the env field of settings.json:

{
  "env": {
    "CODEBUDDY_API_KEY": "your-api-key",
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "MAX_THINKING_TOKENS": "10000"
  }
}

For more configuration examples and advanced usage, see Environment Variables Reference and Usage Examples.

Status Line Configuration

Configure the status line displayed at the bottom of the terminal, which can show current session, model, cost, and other information:

Key	Type	Description
statusLine.type	string	Status line type, currently supports "command"
statusLine.command	string	Command path to execute, supports ~ path expansion

{
  "statusLine": {
    "type": "command",
    "command": "~/.codebuddy/statusline-script.sh"
  }
}

The status line command receives JSON data containing session information via stdin, including:

• session_id: Session ID
• model: Current model information
• workspace: Workspace path information
• cost: Cost statistics
• version: Application version

Use the /statusline command to quickly configure the status line.

Configuration Management Commands

Use the codebuddy config command to manage configuration:

Basic Syntax

codebuddy config [command] [options]

Available Commands

Command	Syntax	Description
get	codebuddy config get <key>	Get a configuration value
set	codebuddy config set [options] <key> <value>	Set a configuration value
list	codebuddy config list (alias: ls)	List all configuration
add	codebuddy config add <key> <values...>	Add items to an array configuration
remove	codebuddy config remove <key> [values...] (alias: rm)	Remove configuration or array items

Options

Option	Description	Applicable Commands
-g, --global	Set global configuration	set

Usage Examples

Viewing Configuration

# List all configuration
codebuddy config list

# Get a specific configuration value
codebuddy config get model
codebuddy config get permissions

Setting Configuration

# Set project-level model (no -g flag needed)
codebuddy config set model gpt-5

# Set global model (requires -g flag)
codebuddy config set -g model gpt-4

# Set project-level permission configuration (no -g flag needed)
codebuddy config set permissions '{"allow": ["Read", "Edit"], "deny": ["Bash(rm:*)"]}'

# Set project-level environment variables (no -g flag needed)
codebuddy config set env '{"NODE_ENV": "development", "DEBUG": "true"}'

# Set global-only configuration (requires -g flag)
codebuddy config set -g cleanupPeriodDays 30
codebuddy config set -g includeCoAuthoredBy false

Local Data Cleanup Command

Use codebuddy cleanup to manually clean up expired local data. By default, it uses the local chat-history retention period; when not configured, data is retained for 30 days.

The cleanup includes expired session records, session-generated files, traces, logs, diagnostics, and cache.

# 按默认保留天数清理
codebuddy cleanup

# 清理 7 天以前的本地数据
codebuddy cleanup --days 7

# 只预览，不删除
codebuddy cleanup --days 7 --dry-run

Tools Available to CodeBuddy

CodeBuddy Code has access to a powerful set of tools to help it understand and modify your codebase:

Tool	Description	Requires Permission
AskUserQuestion	Ask the user multiple-choice questions to gather information or clarify ambiguities	No
Bash	Execute shell commands in your environment	Yes
TaskOutput	Retrieve output from running or completed background tasks	No
Edit	Make targeted edits to specific files	Yes
MultiEdit	Make multiple edits to a single file in one operation	Yes
ExitPlanMode	Prompt the user to exit plan mode and begin coding	Yes
Glob	Find files using pattern matching	No
Grep	Search for patterns in file contents	No
TaskStop	Terminate a running background task by ID	No
LSP	Interact with LSP servers for code intelligence features (go-to-definition, find references, hover information, etc.)	No
NotebookEdit	Modify Jupyter notebook cells	Yes
Read	Read file contents	No
Skill	Execute a skill in the main conversation	Yes
SlashCommand	Run custom slash commands	Yes
Task	Run sub-agents to handle complex multi-step tasks	No
TaskOutput	Retrieve output from running or completed background tasks	No
TaskCreate	Create tasks to track work progress	No
TaskUpdate	Update task status (pending/in_progress/completed)	No
TaskList	List current tasks	No
TaskGet	Get specific task details	No
WebFetch	Fetch content from a specified URL	Yes
WebSearch	Perform web search with domain filtering	Yes
Write	Create or overwrite files	Yes

Permission rules can be configured using /permissions or in Permission Settings. See also Tool-Specific Permission Rules.

Extending Tools with Hooks

You can use CodeBuddy Code hooks to run custom commands before and after any tool execution.

For example, you can automatically run a Python formatter after CodeBuddy modifies Python files, or prevent modifications to production configuration files by blocking Write operations to certain paths.

Common Configuration Scenarios

Team Collaboration Configuration

Shared project configuration (.codebuddy/settings.json):

{
  "model": "gpt-5",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)", "Bash(npm:*)"],
    "ask": ["WebFetch", "Bash(docker:*)"],
    "deny": ["Bash(rm:*)", "Bash(sudo:*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Personal local configuration (.codebuddy/settings.local.json):

{
  "model": "gpt-4",
  "env": {
    "DEBUG": "myapp:*"
  }
}

Security Configuration

Restrict sensitive operations and file access:

{
  "permissions": {
    "allow": ["Read", "Edit(src/**)", "Bash(git:status,git:diff)"],
    "ask": ["WebFetch", "Bash(curl:*)"],
    "deny": [
      "Edit(**/*.env)",
      "Edit(**/*.key)",
      "Edit(**/*.pem)",
      "Bash(wget:*)",
      "Read(/etc/**)",
      "Read(~/.ssh/**)"
    ],
    "defaultMode": "default"
  }
}

Sandbox Security Configuration

Enable sandbox and configure filesystem and network access:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "allow": [
      "Edit(src/**)",
      "WebFetch(https://api.github.com/**)"
    ],
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)",
      "Edit(**/*.env)"
    ]
  }
}

See Also

• Identity and Access Management - Learn about CodeBuddy Code's permission system
• Bash Sandbox - Learn about sandbox isolation
• Troubleshooting - Solutions for common configuration issues

---

The right configuration makes CodeBuddy Code better understand your needs