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",
  "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
hooks	Configure custom commands to run before and after tool execution. See hooks documentation	{"PreToolUse": {"Bash": "echo 'Running command...'"}}
disableAllHooks	Disable all hooks	true
model	Override the default model used by CodeBuddy Code	"gpt-5"
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"
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	true
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
autoUpdates	Auto-update settings	false
alwaysThinkingEnabled	Always enable thinking mode	true
showTokensCounter	Whether to show the tokens counter in the interface	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: low, medium, high, xhigh. 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}

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	"acceptEdits"
disableBypassPermissionsMode	Set to "disable" to prevent activating bypassPermissions mode. This disables the -y and --dangerously-skip-permissions CLI flags	"disable"

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
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,
    "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	["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.

Sub-Agent Configuration

CodeBuddy Code supports custom AI sub-agents configurable at user and project levels. These 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 AI assistants with custom prompts and tool permissions. See Sub-Agents Documentation for details.

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

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