Settings

CodeBuddy Code uses a layered configuration system, allowing you to customize settings at different levels, from personal preferences to team standards and specific project requirements.

🏗️ Configuration Hierarchy

CodeBuddy Code uses a layered configuration system, with settings merged according to the following priority (latter settings override earlier ones):

bash

Command-line parameters (highest priority)
├── Project local settings (./.codebuddy/settings.local.json)
├── Project shared settings (./.codebuddy/settings.json)  
└── User settings (~/.codebuddy/settings.json) (lowest priority)

Configuration File Locations

Level	File Path	Purpose	Version Control
User-level	`~/.codebuddy/settings.json`	Personal preference settings	Not committed
Project Shared	`./.codebuddy/settings.json`	Team-shared configuration	Committed to Git
Project Local	`./.codebuddy/settings.local.json`	Personal project settings	Not committed (add to .gitignore)

Configuration Scope Explanation

User-level configuration: Affects the default behavior for all projects
Project shared configuration: Shared project standards for the team
Project local configuration: Personal custom settings for a specific project

⚙️ Configuration Options Reference

Full Configuration Example

json

{
  "model": "gpt-5",
  "cleanupPeriodDays": 30,
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  },
  "includeCoAuthoredBy": false,
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git:*)"],
    "deny": ["Bash(rm:*)", "Bash(sudo:*)"],
    "additionalDirectories": ["/tmp", "/var/log"],
    "defaultMode": "default"
  },
  "hooks": {
    "PreToolUse": "echo 'About to use tool: $TOOL_NAME'"
  },
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["filesystem", "git"],
  "disabledMcpjsonServers": ["dangerous-tool"],
  "autoCompactEnabled": true,
  "autoUpdates": true,
  "apiKeyHelper": "/usr/local/bin/get-api-key.sh"
}

Configuration Option Detailed Explanation

Config Key	Type	Default Value	Description
`model`	string	-	Default AI model (`gpt-5`, `gpt-4`)
`cleanupPeriodDays`	number	30	Days to retain local chat records
`includeCoAuthoredBy`	boolean	false	Whether to include co-authored-by in Git commits
`autoCompactEnabled`	boolean	-	Enable auto-compaction feature
`autoUpdates`	boolean	-	Auto-update setting
`apiKeyHelper`	string	-	Path to the script for obtaining authentication keys

Environment Variable Configuration

Set environment variables for each session via the env object:

json

{
  "env": {
    "NODE_ENV": "development",
    "API_URL": "https://api.example.com",
    "DEBUG": "codebuddy:*"
  }
}

Permission System

CodeBuddy Code uses a fine-grained permission system to control tool access:

Permission Configuration Options

Config Key	Type	Description
`allow`	string[]	List of allowed tools and operations
`deny`	string[]	List of disallowed tools and operations
`additionalDirectories`	string[]	Additional directories allowed for access
`defaultMode`	string	Default permission mode
`disableBypassPermissionsMode`	string	Disable permission bypass mode

Permission Rule Syntax

json

{
  "permissions": {
    "allow": [
      "Read",                           // Allow reading files
      "Edit",                          // Allow editing files
      "Bash(git:*)",                   // Allow all git commands
      "Bash(npm:install,npm:test)",    // Allow specific npm commands
      "Edit(src/**/*.js)"              // Allow editing only JS files in src directory
    ],
    "ask": [
      "Bash(curl:*)",                  // Ask before allowing curl commands
      "WebFetch",                      // Ask before allowing network requests
      "Bash(docker:*)"                 // Ask before allowing Docker commands
    ],
    "deny": [
      "Bash(rm:*)",                    // Deny delete commands
      "Bash(sudo:*)",                  // Deny sudo commands
      "Edit(**/*.env)",                // Deny editing environment variable files
      "Read(/etc/**)"                  // Deny reading system configuration files
    ],
    "additionalDirectories": ["/tmp", "/var/log"],
    "defaultMode": "default"
  }
}

Permission Modes

Mode	Description
`default`	Standard permission check
`acceptEdits`	Automatically accept edit operations
`plan`	Only plan, no operations executed
`bypassPermissions`	Bypass permission checks (use with caution)

Dynamic Permission Mode Management

Starting with the current version, the permission mode supports dynamic switching at the session level:

Set at CLI launch: Use the --permission-mode parameter to specify the initial permission mode
Dynamically updated at runtime: The permission mode will be dynamically updated in the session and displayed in the UI
Priority order: CLI parameters > defaultMode in configuration files > system default (default)
UI Status Display: When the permission mode is not default, the current permission mode will be displayed in the UI

bash

# Set permission mode at startup
codebuddy --permission-mode acceptEdits

# The permission mode will persist during the session and can be viewed in the UI

MCP Server Management

Control the enabling and disabling of Model Context Protocol (MCP) servers:

Config Key	Type	Description
`enableAllProjectMcpServers`	boolean	Automatically approve all MCP servers in the project's .mcp.json
`enabledMcpjsonServers`	string[]	Explicitly enabled MCP server list
`disabledMcpjsonServers`	string[]	Explicitly disabled MCP server list

json

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["filesystem", "git"],
  "disabledMcpjsonServers": ["experimental-tool"]
}

🌍 Environment Variables

CodeBuddy Code supports configuration via environment variables.

Environment Variable	Description
`CODEBUDDY_AUTH_TOKEN`	CodeBuddy authentication token
`CODEBUDDY_API_KEY`	API key for authentication requests
`CODEBUDDY_CUSTOM_HEADERS`	Custom HTTP request headers, supports multi-line format

Runtime Environment

Environment Variable	Description
`CODEBUDDY_INTERNET_ENVIRONMENT`	Network environment configuration
`ENV_PRODUCT_CLI_ACCOUNT_TYPE`	CLI account type

Example Usage

bash

# Set authentication token
export CODEBUDDY_AUTH_TOKEN="your-auth-token"

# Set API key
export CODEBUDDY_API_KEY="your-api-key"

# Set custom request headers
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1
X-Another-Header: value2"

# Start CodeBuddy
codebuddy

🔧 Configuration Management Commands

Use codebuddy config commands to manage configurations:

Basic Syntax

bash

codebuddy config [command] [options]

Available Commands

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

Options

Option	Description	Applicable Command
`-g, --global`	Set global configuration	`set`

Example Usage

View Configuration

bash

# List all configurations
codebuddy config list

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

Set Configuration

bash

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

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

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

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

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

Array Operations

bash

# Add environment variable
codebuddy config add env '{"DEBUG": "true"}'

# Remove configuration
codebuddy config remove model

Supported Configuration Keys

Based on the code implementation, configuration keys are categorized into two types by scope:

Global Configuration Keys (requires `-g/--global` flag)

Config Key	Type	Description
`model`	string	AI model setting
`cleanupPeriodDays`	number	Days to retain local chat records
`env`	object	Environment variables
`includeCoAuthoredBy`	boolean	Whether to include co-authored-by in Git commits
`permissions`	object	Permissions configuration
`hooks`	object	Tool execution hooks
`statusLine`	object	Status line configuration
`enableAllProjectMcpServers`	boolean	Automatically enable all project MCP servers
`enabledMcpjsonServers`	string[]	Enabled MCP server list
`disabledMcpjsonServers`	string[]	Disabled MCP server list
`autoCompactEnabled`	boolean	Auto-compaction feature
`autoUpdates`	boolean	Auto-update setting
`apiKeyHelper`	string	API key helper script path

Project Configuration Keys (set at project level)

Config Key	Type	Description
`permissions`	object	Permissions configuration
`model`	string	AI model setting
`env`	object	Environment variables
`apiKeyHelper`	string	API key helper script path

Note:
Global configuration keys can only be set at the user level with the -g/--global flag
Project configuration keys can be set at the project level without the -g flag
If attempting to set a configuration key in the wrong scope, an error message will be shown

Complete Example

bash

# View current all configurations
codebuddy config list

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

# Set project-level model (no need for -g flag)
codebuddy config set model gpt-4

# Configure global permission system (requires -g flag)
codebuddy config set -g permissions '{
  "allow": ["Read", "Edit", "Bash(git:*)"],
  "deny": ["Bash(rm:*)", "Bash(sudo:*)"],
  "defaultMode": "default"
}'

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

# Set global environment variables (requires -g flag)
codebuddy config set -g env '{
"DEBUG": "codebuddy:*",
  "API_URL": "https://api.example.com"
}'

# Set global configuration item (requires -g flag)
codebuddy config set -g cleanupPeriodDays 7
codebuddy config set -g includeCoAuthoredBy true
codebuddy config set -g autoUpdates false

# Verify settings
codebuddy config get model
codebuddy config get permissions

📋 Common Configuration Scenarios

Team Collaboration Configuration

Project Shared Configuration (./.codebuddy/settings.json):

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):

json

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

Security Configuration

json

Limit 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"
  }
}

Development Environment Configuration

Configuration for different development stages:

json

{
  "model": "gpt-5",
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": [
      "Read", "Edit", 
      "Bash(npm:*)", "Bash(yarn:*)",
      "Bash(git:*)", "Bash(docker:ps,docker:logs)"
    ],
    "additionalDirectories": ["/tmp", "./logs"]
  },
  "enabledMcpjsonServers": ["filesystem", "git"]
}

🚀 Next Steps

Once configuration is complete, you can:

Learn Slash Commands - Master all built-in features
Explore MCP Extensions - Add custom tools and services
View Troubleshooting - Resolve common issues

Proper configuration makes CodeBuddy Code better tailored to your needs ⚙️

Settings ​

🏗️ Configuration Hierarchy ​

Configuration File Locations ​

Configuration Scope Explanation ​

⚙️ Configuration Options Reference ​

Full Configuration Example ​

Configuration Option Detailed Explanation ​

Environment Variable Configuration ​

Permission System ​

Permission Configuration Options ​

Permission Rule Syntax ​

Permission Modes ​

Dynamic Permission Mode Management ​

MCP Server Management ​

🌍 Environment Variables ​

Authentication-related ​

Runtime Environment ​

Example Usage ​

🔧 Configuration Management Commands ​

Basic Syntax ​

Available Commands ​

Options ​

Example Usage ​

View Configuration ​

Set Configuration ​

Array Operations ​

Supported Configuration Keys ​

Global Configuration Keys (requires -g/--global flag) ​

Project Configuration Keys (set at project level) ​

Complete Example ​

📋 Common Configuration Scenarios ​

Team Collaboration Configuration ​

Security Configuration ​

Development Environment Configuration ​

Settings

🏗️ Configuration Hierarchy

Configuration File Locations

Configuration Scope Explanation

⚙️ Configuration Options Reference

Full Configuration Example

Configuration Option Detailed Explanation

Environment Variable Configuration

Permission System

Permission Configuration Options

Permission Rule Syntax

Permission Modes

Dynamic Permission Mode Management

MCP Server Management

🌍 Environment Variables

Authentication-related

Runtime Environment

Example Usage

🔧 Configuration Management Commands

Basic Syntax

Available Commands

Options

Example Usage

View Configuration

Set Configuration

Array Operations

Supported Configuration Keys

Global Configuration Keys (requires `-g/--global` flag)

Project Configuration Keys (set at project level)

Complete Example

📋 Common Configuration Scenarios

Team Collaboration Configuration

Security Configuration

Development Environment Configuration