Settings Configuration

CodeBuddy Code uses a layered configuration system that allows you to customize 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 hierarchical settings:

• User settings defined in ~/.codebuddy/settings.json, applied to all projects
• Project settings 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 experimentation. CodeBuddy Code automatically configures git to ignore this file

Complete Configuration Example

{
  "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:

Configuration Key	Description	Example
language	Preferred response language. When set, CodeBuddy Code will respond in the specified language. Leave empty for automatic language detection based on user input	"简体中文"
apiKeyHelper	Custom script executed in /bin/sh to generate authentication values. This value will be sent as X-Api-Key and Authorization: Bearer headers in model requests	/bin/generate_temp_api_key.sh
textToImageModel	Model ID used for text-to-image feature	"your-image-model"
imageToImageModel	Model ID used for image-to-image feature	"your-edit-model"
cleanupPeriodDays	How long to retain chat history locally based on last activity date (default: 30 days)	20
env	Environment variables applied to each 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"
statusLine	Configure custom status line to display context. See statusLine documentation	{"type": "command", "command": "~/.codebuddy/statusline.sh"}
enableAllProjectMcpServers	Automatically approve all MCP servers defined in the project's .mcp.json file	true
enabledMcpjsonServers	List of specific MCP servers approved from the .mcp.json file	["memory", "github"]
disabledMcpjsonServers	List of specific MCP servers denied from the .mcp.json file	["filesystem"]
autoCompactEnabled	Enable auto-compact feature	true
autoUpdates	Auto-update settings	false
alwaysThinkingEnabled	Always enable thinking mode	true
showTokensCounter	Whether to show tokens counter in the interface	false
endpoint	Custom service 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 suggestion feature, automatically predicts next steps after Agent completes conversation (default: true)	false
memory	[Experimental] Memory feature configuration, see Memory Configuration	{"enabled": true}

Permission Settings

Configuration Key	Description	Example
allow	Array of permission rules allowing tool usage. Note: Bash rules use prefix matching, not regular expressions	[ "Bash(git diff:*)" ]
ask	Array of permission rules requesting confirmation when tool is used	[ "Bash(git push:*)" ]
deny	Array of permission rules denying tool usage. Used to exclude CodeBuddy Code access to sensitive files. Note: Bash patterns use prefix matching and can be bypassed (see Bash Permission Limitations)	[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]
additionalDirectories	Additional working directories 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 command-line flags	"disable"

Memory Configuration (Experimental)

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

Configuration Key	Description	Example
enabled	Whether to enable memory feature (default: false)	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, used to isolate different users' memories. Auto-detected by default (git user.name > system username)	"yangsubo"

Configuration Example:

{
  "memory": {
    "enabled": 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/

You can also enable this feature 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 through Read, Edit, and WebFetch permission rules, not through these sandbox settings.

Configuration Key	Description	Example
enabled	Enable bash sandbox (macOS/Linux only). Default: false	true
autoAllowBashIfSandboxed	Automatically approve bash commands in sandboxed environment. Default: true	true
excludedCommands	Commands that should run outside the sandbox	["git", "docker"]
allowUnsandboxedCommands	Allow commands to run outside sandbox via dangerouslyDisableSandbox parameter. When set to false, completely disables unsandboxed command execution	false
network.allowUnixSockets	Unix socket paths accessible in the sandbox (for SSH agent, etc.)	["~/.ssh/agent-socket"]
network.allowLocalBinding	Allow binding to localhost ports (macOS only). Default: false	true
network.httpProxyPort	HTTP proxy port to use if you want to use your own proxy. If unspecified, CodeBuddy will run its own proxy	8080
network.socksProxyPort	SOCKS5 proxy port to use if you want to use your own proxy. If unspecified, CodeBuddy will run 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 through Read/Edit permissions:

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

Network access is controlled through WebFetch permissions:

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

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

Settings Priority

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

1. Command-line arguments

   • Temporary overrides for specific sessions

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 individuals to customize their experience.

Configuration System Essentials

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

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 your .codebuddy/settings.json file:

{
  "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 that can be configured at both user and project levels. These sub-agents are stored as Markdown files with YAML frontmatter:

• User sub-agents: ~/.codebuddy/agents/ - Available in all projects
• Project sub-agents: .codebuddy/agents/ - Project-specific, can be shared with the team

Sub-agent files define specialized AI assistants with custom prompts and tool permissions. See sub-agent 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 both 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

Scope:

• 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 have access to 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 (use repo)
• git: Any git URL (use url)
• directory: Local filesystem path (use 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 the following environment variables to control its behavior:

Note: All environment variables can also be configured in settings.json. This is useful for automatically setting environment variables for each session, or for rolling out a set of environment variables to an entire team or organization.

Authentication Related

Environment Variable	Description
CODEBUDDY_API_KEY	Recommended. API key, can be either CodeBuddy platform API Key or third-party model provider (like OpenRouter) API Key. Only used for model interface calls, sufficient for most cases
CODEBUDDY_AUTH_TOKEN	CodeBuddy platform authentication token, used for all CodeBuddy platform interface calls (including model interface, token refresh interface, billing interface, configuration distribution interface, admin control interface, etc.). If you want equivalent full functionality to using CLI after local login authentication, configure this
CODEBUDDY_CUSTOM_HEADERS	Custom HTTP request headers. Multiple headers separated by \n or newline, format: Header1: value1\nHeader2: value2

Usage Scenarios:

• CODEBUDDY_API_KEY: Recommended for most scenarios, only used for model interface calls, will not call token refresh, billing queries, or other platform interfaces. Can configure CodeBuddy platform API Key or use with CODEBUDDY_BASE_URL for third-party model services
• CODEBUDDY_AUTH_TOKEN: If you need full CodeBuddy platform functionality (token refresh, billing queries, configuration distribution, admin control, etc.), use this environment variable, equivalent to using CLI after local login authentication. Must be CodeBuddy platform API Key

Runtime Environment

Environment Variable	Description
CODEBUDDY_BASE_URL	Custom model service base URL, usually used with CODEBUDDY_API_KEY. Requirement: compatible with OpenAI interface protocol
CODEBUDDY_INTERNET_ENVIRONMENT	Network environment configuration (internal for China version, iOA for iOA account)
ENV_PRODUCT_CLI_ACCOUNT_TYPE	CLI account type

Bash Tool Configuration

Environment Variable	Description
BASH_DEFAULT_TIMEOUT_MS	Default timeout for long-running bash commands (default: 120000)
BASH_MAX_OUTPUT_LENGTH	Maximum characters of bash output before truncating in the middle (default: 20000, max: 100000)
BASH_MAX_TIMEOUT_MS	Maximum timeout the model can set for long-running bash commands (default: 600000)
CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR	Return to original working directory after each Bash command ⚠️ Not yet supported

Feature Switches

Environment Variable	Description
CODEBUDDY_IMAGE_GEN_ENABLED	Set to false or 0 to disable image generation feature (ImageGen tool)
CODEBUDDY_DEFER_TOOL_LOADING	Set to false or 0 to disable MCP tool lazy loading. Enabled by default, tools are loaded on demand to save context space
CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS	Set to true or 1 to show full descriptions of all deferred tools in ToolSearch description (default only shows first 50 tools)
CODEBUDDY_MEMORY_ENABLED	Set to true or 1 to enable memory feature (Experimental)
CODEBUDDY_TEAM_MEMORY_ENABLED	Set to true or 1 to enable team memory mode
CODEBUDDY_USER_ID	User ID in team memory mode
CODEBUDDY_TASK_LIST_ID	When set, uses ~/.codebuddy/tasks/{CODEBUDDY_TASK_LIST_ID}/ to store task list, enabling cross-session task sharing. Example: CODEBUDDY_TASK_LIST_ID=my-project codebuddy

Other Configuration

Environment Variable	Description
CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS	Interval for refreshing credentials in milliseconds (when using apiKeyHelper) (default: 300000)
CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE	Set to 1 to disable automatic terminal title updates based on conversation context
CODEBUDDY_CODE_IDE_SKIP_AUTO_INSTALL	Skip automatic installation of IDE extensions ⚠️ Not yet supported
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS	Set maximum output token count for most requests
DISABLE_AUTOUPDATER	Set to 1 to disable auto-updates
DISABLE_COST_WARNINGS	Set to 1 to disable cost warning messages ⚠️ Not yet supported
HTTP_PROXY / http_proxy	HTTP proxy server address (e.g., http://proxy.example.com:8080)
HTTPS_PROXY / https_proxy	HTTPS proxy server address (e.g., https://proxy.example.com:8080)
MAX_MCP_OUTPUT_TOKENS	Maximum tokens allowed in MCP tool responses. CodeBuddy Code shows warning when output exceeds 10,000 tokens (default: 25000)
MCP_TIMEOUT	Timeout for MCP server connection (milliseconds). Applies to all transport types (stdio/sse/http)
MCP_TOOL_TIMEOUT	MCP tool execution timeout (milliseconds)
NO_PROXY / no_proxy	List of domains and IPs that will bypass the proxy for direct requests (supports comma-separated format, e.g., localhost,.example.com)
SLASH_COMMAND_TOOL_CHAR_BUDGET	Maximum characters of slash command metadata shown to SlashCommand tool (default: 15000)
USE_BUILTIN_RIPGREP	Set to 0 to use system-installed rg instead of CodeBuddy Code's bundled rg

mTLS Authentication Configuration

Environment Variable	Description
CODEBUDDY_CODE_CLIENT_CERT	mTLS client certificate file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY	mTLS client private key file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE	Password for mTLS encrypted private key (optional) ⚠️ Not yet supported

Shell Configuration

Environment Variable	Description
CODEBUDDY_CODE_SHELL	Override automatic shell detection. Supported values: bash, zsh, sh, powershell, cmd. Useful when login shell differs from preferred working shell
CODEBUDDY_CODE_SHELL_PREFIX	Command prefix that wraps all bash commands (e.g., for logging or auditing). Example: /path/to/logger.sh will execute /path/to/logger.sh <command> ⚠️ Not yet supported
CODEBUDDY_CODE_GIT_BASH_PATH	Explicitly specify Git Bash path on Windows
CODEBUDDY_ENV_FILE	Path to environment file that is automatically sourced before executing each shell command. Solves the issue of non-login shells not loading /etc/profile, ~/.bash_profile, etc. Suitable for scenarios requiring environment variables, aliases, or functions defined in login shells. Example: /etc/profile

Model Configuration

Environment Variable	Description
CODEBUDDY_MODEL	Override default agent model. Takes priority over model setting in settings
CODEBUDDY_SMALL_FAST_MODEL	Small fast model for background tasks (lite variant)
CODEBUDDY_BIG_SLOW_MODEL	Large model for complex reasoning tasks (reasoning variant)
CODEBUDDY_CODE_SUBAGENT_MODEL	Model used by sub-agents, takes priority over Task tool's model parameter
MAX_THINKING_TOKENS	Enable extended thinking and set token budget for thinking process. Extended thinking can improve performance on complex reasoning and coding tasks, but affects prompt caching efficiency. Disabled by default

Prompt Caching Configuration

Environment Variable	Description
DISABLE_PROMPT_CACHING	Set to 1 to disable prompt caching for all models (takes precedence over individual model settings) ⚠️ Not yet supported

Telemetry and Reporting Configuration

Environment Variable	Description
CODEBUDDY_CODE_DISABLE_NONESSENTIAL_TRAFFIC	Equivalent to setting DISABLE_AUTOUPDATER, DISABLE_ERROR_REPORTING, and DISABLE_TELEMETRY together ⚠️ Not yet supported
DISABLE_ERROR_REPORTING	Set to 1 to disable error reporting ⚠️ Not yet supported
DISABLE_TELEMETRY	Set to 1 to disable telemetry (telemetry events do not contain user data like code, file paths, or bash commands) ⚠️ Not yet supported
DISABLE_NON_ESSENTIAL_MODEL_CALLS	Set to 1 to disable non-critical path model calls (such as decorative text) ⚠️ Not yet supported
DISABLE_BUG_COMMAND	Set to 1 to disable the /bug command ⚠️ Not yet supported

Interface Configuration

Environment Variable	Description
CODEBUDDY_CODE_HIDE_ACCOUNT_INFO	Set to 1 to hide your email address and organization name in the CodeBuddy Code interface. Useful for livestreaming or screen recording ⚠️ Not yet supported

File Read Configuration

Environment Variable	Description
CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS	Override the default token limit for file reads. Useful when you need to read large files in full ⚠️ Not yet supported

Other Environment Variables (Supplementary)

Environment Variable	Description
CODEBUDDY_CONFIG_DIR	Custom location for CodeBuddy Code to store configuration and data files ⚠️ Not yet supported
CODEBUDDY_INTERNET_ENVIROMENT	Old spelling of CODEBUDDY_INTERNET_ENVIRONMENT (kept for compatibility)
CODEBUDDY_CODE_DEBUG_LOGS_DIR	Debug log directory (overrides default directory)
CODEBUDDY_SANDBOX_IMAGE	Container sandbox image (default: node:20-alpine)
SERVER__HOST	--serve mode listen address (default: 127.0.0.1)
SERVER__PORT	--serve mode listen port

Usage Examples

Basic Authentication Configuration

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

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

# Set proxy server (supports both uppercase and lowercase)
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

# Set proxy bypass list (optional)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# Set custom request headers (multiple headers separated by \n)
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"

# Start CodeBuddy
codebuddy

International Version Using API KEY

International version users can directly use API KEY to use CodeBuddy Code without setting the CODEBUDDY_INTERNET_ENVIRONMENT variable:

# Set API KEY (recommended method, sufficient for most cases)
export CODEBUDDY_API_KEY="your-api-key"

# Start CodeBuddy
codebuddy

Get API KEY: International version users can visit https://www.codebuddy.ai/profile/keys to get API KEY.

China Version Using API KEY

China version users need to configure the CODEBUDDY_INTERNET_ENVIRONMENT=internal environment variable:

# Set China version environment identifier
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

# Set API KEY (recommended method, sufficient for most cases)
export CODEBUDDY_API_KEY="your-api-key"

# Start CodeBuddy
codebuddy

Can also complete configuration in one command:

CODEBUDDY_INTERNET_ENVIRONMENT=internal \
CODEBUDDY_API_KEY="your-api-key" \
codebuddy

Get API KEY: China version users can visit https://copilot.tencent.com/profile/ to get API KEY.

iOA Account Using API KEY

iOA account users can use CodeBuddy Code via API KEY by configuring the following environment variables:

# Set iOA environment identifier
export CODEBUDDY_INTERNET_ENVIRONMENT=iOA

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

# Start CodeBuddy
codebuddy

Can also complete configuration in one command:

CODEBUDDY_INTERNET_ENVIRONMENT=iOA \
CODEBUDDY_API_KEY="your-api-key" \
codebuddy

Get API KEY: iOA account users can visit https://tencent.sso.copilot.tencent.com/profile/keys to get API KEY.

Note: Please keep your API KEY secure and do not expose it in code repositories or public places.

Using OpenRouter Custom Models

# Use OpenRouter service, start custom model with one command
CODEBUDDY_API_KEY=sk-or-v1-9a951951428092casdffs702bsdf2513c292680cd621b9d0e39cf \
CODEBUDDY_BASE_URL=https://openrouter.ai/api/v1 \
codebuddy --model openai/gpt-5-codex

# Or set environment variables first
export CODEBUDDY_API_KEY="sk-or-v1-your-openrouter-api-key"
export CODEBUDDY_BASE_URL="https://openrouter.ai/api/v1"
codebuddy --model openai/gpt-5-codex

Note: When CODEBUDDY_API_KEY is configured:

• Only used for model interface calls
• No longer calls token refresh interface, billing interface, or other service interfaces
• Can configure CodeBuddy platform API Key or use with CODEBUDDY_BASE_URL for third-party model services
• Model service configured via CODEBUDDY_BASE_URL must be compatible with OpenAI interface protocol

Using DeepSeek Models

# Use DeepSeek Chat model (standard dialogue model)
CODEBUDDY_API_KEY=sk-your-deepseek-api-key \
CODEBUDDY_BASE_URL=https://api.deepseek.com/v1 \
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS=8000 \
codebuddy --model deepseek-chat

# Use DeepSeek Reasoner model (reasoning model, supports longer output)
CODEBUDDY_API_KEY=sk-your-deepseek-api-key \
CODEBUDDY_BASE_URL=https://api.deepseek.com/v1 \
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS=64000 \
codebuddy --model deepseek-reasoner

Note:

• CODEBUDDY_CODE_MAX_OUTPUT_TOKENS is used to set the maximum output token count, different models support different maximum values
• DeepSeek Chat is recommended to be set to 8000
• DeepSeek Reasoner, as a reasoning model, supports longer output and can be set to 64000

Status Line Configuration

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

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

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

The status line command receives JSON data containing session information as stdin input, 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 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 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 configurations
codebuddy config list

# Get 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 dedicated 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 set of powerful tools that help it understand and modify your codebase:

Tool	Description	Requires Permission
AskUserQuestion	Ask users multiple-choice questions to gather information or clarify ambiguities	No
Bash	Execute shell commands in your environment	Yes
BashOutput	Retrieve output from background bash shells	No
Edit	Make targeted edits to specific files	Yes
MultiEdit	Make multiple edits to a single file in one operation	Yes
ExitPlanMode	Prompt user to exit plan mode and start coding	Yes
Glob	Find files based on pattern matching	No
Grep	Search for patterns in file contents	No
KillShell	Terminate running background bash shells by ID	No
NotebookEdit	Modify Jupyter notebook cells	Yes
Read	Read file contents	No
Skill	Execute skills in the main conversation	Yes
SlashCommand	Run custom slash commands	Yes
Task	Run sub-agents to handle complex multi-step tasks	No
TodoWrite	Create and manage structured task lists	No
WebFetch	Fetch content from specified URLs	Yes
WebSearch	Perform web searches with domain filtering	Yes
Write	Create or overwrite files	Yes

Permission rules can be configured using /permissions or in permission settings. Also see 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 modification of production configuration files by blocking Write operations to certain paths.

Common Configuration Scenarios

Team Collaboration Configuration

Project shared 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 capabilities
• Troubleshooting - Solutions to common configuration issues

---

Proper configuration makes CodeBuddy Code better understand your needs ⚙️