settings.json file is the official mechanism for configuring CodeBuddy Code, supporting layered settings:~/.codebuddy/settings.json and apply to all projects..codebuddy/settings.json file is used for settings that are checked into source control and shared with the team..codebuddy/settings.local.json file is used for settings that are not checked in, making it suitable for personal preferences and experiments. CodeBuddy Code automatically configures git to ignore this file.{"language": "Simplified Chinese","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"}}
settings.json file supports the following options:Configuration Key | Description | Example |
language | Preferred response language. After it is set, CodeBuddy Code will reply in the specified language. If left empty, the language is automatically determined based on user input. | "Simplified Chinese" |
apiKeyHelper | A custom script executed in /bin/sh to generate an authentication value. This value is sent as the X-Api-Key and Authorization: Bearer headers in model requests. | /bin/generate_temp_api_key.sh |
textToImageModel | Model ID used by the text-to-image feature | "your-image-model" |
imageToImageModel | Model ID used by the image-to-image feature | "your-edit-model" |
cleanupPeriodDays | Duration for retaining chat history locally based on the last activity date (default: 30 days) | 20 |
env | Environment variables applied to each session | {"FOO": "bar"} |
includeCoAuthoredBy | Whether to include the co-authored-by CodeBuddy attribution in git commits and pull requests (default: true) | false |
permissions | Permission configuration. See the table below. | |
autoMode | {"allow": ["$defaults", "Allow publishing in dev environment"]} | |
hooks | Configure custom commands to run before and after tool execution. For details, see the hooks documentation. | {"PreToolUse": {"Bash": "echo 'Running command...'"}} |
disableAllHooks | Disable all hooks | true |
allowUntrustedFrontmatterHooks | Whether to allow execution of the frontmatter hooks field from agents/skills from non-product built-in sources (including user-local .codebuddy/agents|skills/*.md and the plugin marketplace). Defaults to false to prevent untrusted md files from silently launching shell commands; only product built-in agents/skills are unaffected. | true |
model | Overrides the default model used by CodeBuddy Code. After directly editing settings.json, existing sessions do not take effect (restart the process or run /clear (create a new session) to apply the new value); switching via /model or /config set model takes effect immediately. | "gpt-5" |
outputStyle | Output style. After directly editing settings.json, existing sessions do not take effect (restart the process or run /clear (create a new session) to apply the new value); switching via the style panel (/output-style) or /config set outputStyle takes effect immediately. | "concise" |
subagents | Specifies models by built-in subagent name. The format is {"agents": {"<subagent name>": {"model": "..."}}}; model supports model IDs, aliases, lite / reasoning, or inherit / default. Subagents do not affect each other and support both user-global and project scopes, and can be edited in /agents. Priority: CODEBUDDY_CODE_SUBAGENT_MODEL > the model parameter of this Agent tool call > project settings > user-global settings > built-in declarations > main model. For details, see the subagent documentation. | {"agents": {"Explore": {"model": "lite"}, "Plan": {"model": "reasoning"}}} |
variantModels | Maps generic scenario variants to models, with keys being lite or reasoning and values being model IDs or aliases. This mapping affects all logic that uses the corresponding variants and can be edited via /model:lite / /model:reasoning. Priority: corresponding variant environment variables > project settings > user-global settings > relatedModels of the main model > applicable product built-in defaults > main model. | {"lite": "<fast-model-id>", "reasoning": "<reasoning-model-id>"} |
agent | Overrides the agent name used by the main thread (built-in or custom agent) and applies the 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 the [statusLine documentation](#status-line-configuration). | {"type": "command", "command": "~/.codebuddy/statusline.sh"} |
enableAllProjectMcpServers | Automatically approve all MCP servers defined in the project .mcp.json file. | false |
enabledMcpjsonServers | List of specific MCP servers approved from the .mcp.json file | ["memory", "github"] |
disabledMcpjsonServers | List of specific MCP servers rejected from the .mcp.json file | ["filesystem"] |
autoCompactEnabled | Enable automatic compaction. | true |
autoUpdates | Automatic update settings | false |
alwaysThinkingEnabled | Always enable thinking mode. | true |
showTokensCounter | Whether to display the Tokens counter in the interface | false |
endpoint | Custom service endpoint URL | "https://api.example.com" |
envRouteMode | Environment routing mode configuration | "production" |
sandbox | Bash sandbox configuration. See Bash sandbox settings | {"enabled": true} |
promptSuggestionEnabled | Enable the Prompt suggestion feature to automatically predict the next action after the Agent completes a conversation (default: true). | false |
reasoningEffort | Reasoning effort level configuration, which controls the depth of model reasoning. Optional values: minimal, low, medium, high, xhigh, max. If left empty, the product default value is used. You can switch it in the /config panel. Selecting auto is equivalent to clearing this setting. | "high" |
memory | [Experimental] Memory feature configuration. See Memory feature configuration | {"enabled": true} |
trustedDirectories | List of trusted working directories. When a directory in this list is opened at startup, the authorization prompt asking whether to trust this directory is not displayed. This list is usually written automatically by the pop-up at first startup, and can also be edited manually. | ["~/workspace/myproj"] |
trustAll | Trust all working directories and no longer display the authorization prompt asking whether to trust this directory at startup. This only exempts directory trust authorization and does not skip tool execution permissions. Whether to display tool approval is still determined by the permissions.defaultMode / bypassPermissions mode and is independent of this field. | true |
gateway | Remote Gateway configuration. See Gateway configuration. | {"runTimeoutMs": 1800000} |
disableUEAutoExclude | Disable automatic exclusion for Unreal Engine projects. Default: false. When a *.uproject file exists at the top level of the cwd, the Grep/Glob tools automatically exclude the six UE build artifacts and IDE cache directories, Intermediate/ DerivedDataCache/ Saved/ Binaries/ Build/ .vs/, from ripgrep searches. Setting this to true disables this behavior and allows searches to cover these directories. | true |
Configuration Key | Description | Example |
allow | An array of permission rules that allows tools to be used. Note: Bash rules use prefix matching, not regular expressions. | [ "Bash(git diff:*)" ] |
ask | [ "Bash(git push:*)" ] | |
deny | An array of permission rules that denies tool usage. It is used to prevent CodeBuddy Code from accessing sensitive files. Note: Bash patterns use prefix matching and can be bypassed (see Bash permission limitations). | [ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ] |
additionalDirectories | [ "../docs/" ] | |
defaultMode | Default permission mode when CodeBuddy Code is opened. Common values: default, acceptEdits, auto, dontAsk, plan, bypassPermissions | "acceptEdits" |
disableBypassPermissionsMode | Set to "disable" to prevent the bypassPermissions mode from being activated. This disables the -y and --dangerously-skip-permissions command-line flags. | "disable" |
disableAutoMode | Set to "disable" to prevent the auto mode from being activated. After it is disabled, both --permission-mode auto and defaultMode: "auto" fall back to default. | "disable" |
subagentPermissionMode | Overrides the default permission mode for subagents/team members. After it is set, all subagents use this mode instead of inheriting the mode from the main session. The mode parameter of the Agent tool has a higher priority; however, if the main session is in auto / dontAsk, subagents are still constrained by the parent session's permission upper limit. | "bypassPermissions" |
autoMode is a top-level settings field, not a subfield of permissions. It defines the classifier context and rules used by the auto permission mode.autoMode?Configuration Key | Function | Example |
environment | Describes which repositories, domains, services, and storage locations belong to your trust boundary, helping the classifier determine what counts as "internal". | ["$defaults", "Trusted internal domains: staging.example.com"] |
allow | Natural language rules that supplement "actions that are typically allowed automatically in auto mode" | ["$defaults", "Allow publishing in dev namespace"] |
soft_deny | Rule descriptions that supplement "actions that should typically be blocked but can be retried with explicit user intent" | ["$defaults", "Modify shared test database schema"] |
hard_deny | Supplement high-risk rule descriptions for actions that must be blocked by default | ["$defaults", "Publish private repository content to public network"] |
autoMode From?autoMode only from the following sources:Source | Typical Location | Purpose |
user settings | ~/.codebuddy/settings.json | Cross-project personal trust boundary |
project-local settings | .codebuddy/settings.local.json | Local supplementary rules for a project on a specific machine |
CLI --settings | codebuddy --settings '{...}' | One-time automation or temporary override |
.codebuddy/settings.jsonautoMode defines a local security boundary, and configurations committed to the repository should not silently alter your local judgment of what is considered internal and what actions are allowed.permissions.defaultMode: "auto"autoMode rule sources: allowed from user / project-local / CLIauto mode: only user / CLI are allowed..codebuddy/settings.local.json can supplement autoMode.environment / allow / soft_deny / hard_deny.codebuddy/settings.local.json cannot make a session enter auto by default through permissions.defaultMode: "auto".codebuddy/settings.json works: it can neither provide autoMode nor grant defaultMode: "auto"autoMode are merged in source order:"$defaults" is processed uniformly.environment does not affect the default values of allow / soft_deny / hard_deny."$defaults" Work?"$defaults" is a special placeholder that means "insert the built-in default rules here."{"autoMode": {"environment": ["$defaults","Trusted internal domains: staging.example.com"]}}
environment default rules.staging.example.com."$defaults", the default rules are expanded at that position."$defaults", it means that the built-in default rules for this field are completely replaced."$defaults", the built-in rules are expanded only once and are not injected repeatedly."$defaults" in soft_deny / hard_deny, you are actively giving up the built-in security rules.codebuddy auto-mode defaultscodebuddy auto-mode configcodebuddy auto-mode critique
defaults: Print the built-in default rules.config: Print the final effective rules, including the results after merging multiple sources and expanding "$defaults".critique: Have the lite model review whether your custom allow / soft_deny / hard_deny rules are vague, redundant, or prone to false positives.codebuddy auto-mode defaults.codebuddy auto-mode config to check the final result.{"autoMode": {"environment": ["$defaults","Source control: git.example.com/acme and all repos under it","Trusted internal domains: staging.example.com, api.internal.example.com","Trusted buckets: s3://acme-build-artifacts"]}}
{"permissions": {"defaultMode": "auto"},"autoMode": {"environment": ["$defaults","Trusted internal domains: staging.example.com"],"allow": ["$defaults",Allow publishing from the dev namespace.],"soft_deny": ["$defaults",Modify the shared test database schema.],"hard_deny": ["$defaults",Publish the content of a private repository to the public network.]}}
Configuration Key | Description | Example |
autoMemoryEnabled | Whether to enable the Auto Memory feature (default: true). Auto Memory allows CodeBuddy to automatically manage persistent cross-session memories, stored in the ~/.codebuddy/memories/ directory. | true |
typedMemory | Whether to enable Typed Memory mode (default: true). After enabled, the system uses 4 memory types (user/feedback/project/reference) + YAML frontmatter format to manage memories. | true |
relevanceSelection | Whether to enable memory relevance selection (default: true). After enabled, the system automatically selects up to 5 relevant memories based on user queries and injects them into the context. | true |
memoryExtraction | Whether to enable background memory extraction (default: false). After enabled, the system automatically extracts memorable information from the conversation at the end of the conversation. | true |
teamMemory.enabled | Whether to enable team memory mode (default: false). After enabled, project memories are stored in the project directory for team sharing. | true |
teamMemory.userId | Team user ID, used to isolate memories of different users. Obtained automatically by default (git user.name > system username). | "yangsubo" |
{"memory": {"autoMemoryEnabled": true,"typedMemory": true,"relevanceSelection": true,"memoryExtraction": false,"teamMemory": {"enabled": true,"userId": "yangsubo"}}}
~/.codebuddy/memories/{project-id}/{project}/.codebuddy/memories/@{user-id}/~/.codebuddy/memories/global//config command.Configuration Key | Description | Example |
enabled | Enable the bash sandbox (macOS/Linux only). Default: false. | true |
autoAllowBashIfSandboxed | Automatically approve bash commands in the sandbox environment. Default: true. | true |
excludedCommands | Commands that should run outside the sandbox | ["git", "docker"] |
allowUnsandboxedCommands | Allows running commands outside the sandbox through the dangerouslyDisableSandbox parameter. When set to false, it is completely disabled. | - |
network.allowUnixSockets | Unix socket paths accessible in the sandbox (for SSH agents and similar purposes) | ["~/.ssh/agent-socket"] |
network.allowLocalBinding | Allows 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 not specified, CodeBuddy runs its own proxy. | 8080 |
network.socksProxyPort | SOCKS5 proxy port to use if you want to use your own proxy. If not specified, CodeBuddy runs its own proxy. | 8081 |
enableWeakerNestedSandbox | Enable a weaker sandbox for unprivileged Docker environments (Linux only). Reduces security. Default: false. | true |
{"sandbox": {"enabled": true,"autoAllowBashIfSandboxed": true,"excludedCommands": ["docker"],"network": {"allowUnixSockets": ["/var/run/docker.sock"],"allowLocalBinding": true}},"permissions": {"deny": ["Read(.envrc)","Read(~/.aws/**)"]}}
settings.json and settings.local.json) to the write protection list to prevent commands or tools within the sandbox from tampering with the configuration. For details, see Bash Sandbox - Configuration File Protection..codebuddy/settings.local.json).codebuddy/settings.json)~/.codebuddy/settings.json)/command-namepermissions.deny setting in the .codebuddy/settings.json file:{"permissions": {"deny": ["Read(./.env)","Read(./.env.*)","Read(./secrets/**)","Read(./config/credentials.json)","Read(./build)"]}}
gateway field configures the behavior of 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 Value |
auth | Authentication mode. "password" requires the client to provide a password, and "none" performs no authentication. Defaults to "password" when --serve is not explicitly configured. Explicitly setting it to "none" disables authentication, in which case any process on the same machine can run commands and read or write files through this service, so this is recommended only for isolated environments / CI use. | "password"(--serve) |
password | Password used when auth: "password". If left empty, a password is automatically generated and printed to the log on first startup. | Automatically generated |
corsOrigins | Additional Origin list allowed to access Gateway across origins. loopback sources on the port the service listens on are automatically allowed. Pages from localhost on other ports must be explicitly declared here (such as a local Vite dev server). | [] |
maxConnections | Maximum concurrent connections for the ACP protocol. The CODEBUDDY_ACP_MAX_CONNECTIONS environment variable has a higher priority. | 5 |
tokenTtlMs | Validity period of the ACP session token (in milliseconds). The CODEBUDDY_ACP_TOKEN_TTL_MS environment variable has a higher priority. | 86400000 (24 hours) |
runTimeoutMs | Task execution timeout for /api/v1/runs in milliseconds. On timeout, {code:'EXECUTION_ERROR', message:'Task timed out after Xmin'} is returned. | 1800000 (30 minutes) |
runTimeoutMs Override PriorityX-Codebuddy-Run-Timeout (in milliseconds): overrides the timeout for a single request and has the highest priority.gateway.runTimeoutMs in settings.json — process-level default value# Give 60 minutes for a single requestcurl -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":"..."}}'
0 or a negative number to disable timeout protection. This is not recommended because unfinished long-running tasks will keep occupying the SSE long connection.settings.json:{"subagents": {"agents": {"Explore": { "model": "lite" },"Plan": { "model": "reasoning" }}},"variantModels": {"lite": "<fast-model-id>","reasoning": "<reasoning-model-id>"}}
/agents to edit built-in subagent mappings. Use /model:lite / /model:reasoning to edit the lite and reasoning mappings.subagents are merged by subagent name, and variantModels are merged by variant name. A project-level override of Explore does not delete other subagent configurations at the user level, and a project-level override of reasoning does not delete the user-level lite./agents or selecting Default in /model deletes the corresponding entries in the selected scope and restores the lower-priority resolution chain.~/.codebuddy/agents/ - available in all projects.codebuddy/agents/ - project-specific and shareable with the teamsettings.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"plugin-name@marketplace-name": true/false~/.codebuddy/settings.json): personal plugin preferences.codebuddy/settings.json): project-specific plugins shared with the team.codebuddy/settings.local.json): per-machine overrides (not committed){"enabledPlugins": {"code-formatter@team-tools": true,"deployment-tools@team-tools": true,"experimental-features@personal": false}}
extraKnownMarketplacesextraKnownMarketplaces:{"extraKnownMarketplaces": {"company-tools": {"source": {"source": "github","repo": "company-org/codebuddy-plugins"}},"security-plugins": {"source": {"source": "git","url": "https://git.company.com/security/plugins.git"}}}}
github: GitHub repository (uses repo)git: Any git URL (uses url)directory: A local file system path (uses path, for development only)/plugin command to manage plugins interactively:env field of settings.json, which automatically applies them to each session or rolls out configurations for the entire team.# Use the API keyexport CODEBUDDY_API_KEY="your-api-key"codebuddy# Or use an authorization token.export CODEBUDDY_AUTH_TOKEN="your-token"codebuddy
export HTTPS_PROXY="https://proxy.example.com:8080"export NO_PROXY="localhost,127.0.0.1"codebuddy
# Extended thinkingexport MAX_THINKING_TOKENS="10000"# Automatic memoryexport CODEBUDDY_DISABLE_AUTO_MEMORY="0"codebuddy -p "Your query"
env field of settings.json:{"env": {"CODEBUDDY_API_KEY": "your-api-key","HTTPS_PROXY": "https://proxy.example.com:8080","MAX_THINKING_TOKENS": "10000"}}
Configuration Key | Type | Description |
statusLine.type | string | Status line type. Currently supports "command". |
statusLine.command | string | Command path to execute, supporting ~ path expansion. |
{"statusLine": {"type": "command","command": "~/.codebuddy/statusline-script.sh"}}
session_id: Session IDmodel: Current model informationworkspace: Workspace path informationcost: Cost statisticsversion: Application version/statusline command.codebuddy config command to manage configurations:codebuddy config [command] [options]
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 |
Option | Description | Applicable Command |
-g, --global | Set global configuration | set |
# List all configurations.codebuddy config list# Get a specific configuration value.codebuddy config get modelcodebuddy config get permissions
# Set a project-level model (the -g flag is not required)codebuddy config set model gpt-5# Set a global model (the -g flag is required)codebuddy config set -g model gpt-4# Set project-level permission configuration (the -g flag is not required)codebuddy config set permissions '{"allow": ["Read", "Edit"], "deny": ["Bash(rm:*)"]}'# Set project-level environment variables (the -g flag is not required)codebuddy config set env '{"NODE_ENV": "development", "DEBUG": "true"}'# Set global dedicated configuration (the -g flag is required)codebuddy config set -g cleanupPeriodDays 30codebuddy config set -g includeCoAuthoredBy false
Tool | Description | Permission Required |
AskUserQuestion | Ask the user multiple-choice questions to collect information or clarify ambiguities. | No |
Bash | Execute shell commands in your environment. | Yes |
TaskOutput | Retrieve output from running or completed background tasks | No |
Edit | Perform targeted edits on specific files. | Yes |
MultiEdit | Perform multiple edits on a single file in a single operation. | Yes |
ExitPlanMode | Prompt the user to exit plan mode and start coding. | Yes |
Glob | Find files based on pattern matching | No |
Grep | Search for patterns in file content. | No |
TaskStop | Terminate the running background task by ID. | No |
LSP | Interact with the LSP server to obtain code intelligence features (go to definition, find references, hover information, and more). | No |
NotebookEdit | Modify Jupyter notebook cells. | Yes |
Read | Read file content. | No |
Skill | Execute skills in the main conversation. | Yes |
SlashCommand | Yes | |
Task | Run a subagent to handle complex multi-step tasks. | No |
TaskOutput | Retrieve output from running or completed background tasks. | No |
TaskCreate | Create a task to track work progress. | No |
TaskUpdate | Update task status (pending/in_progress/completed). | No |
TaskList | List current tasks. | No |
TaskGet | Get details of a specific task. | No |
WebFetch | Fetch content from a specified URL. | Yes |
WebSearch | Perform a web search with domain filtering. | Yes |
Write | Create or overwrite a file. | Yes |
/permissions command or in permission settings. See also tool-specific permission rules..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"}}
.codebuddy/settings.local.json):{"model": "gpt-4","env": {"DEBUG": "myapp:*"}}
{"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": {"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)"]}}
フィードバック