Environment Variables Reference ​

CodeBuddy Code supports environment variables to control its behavior. These variables can be set before startup, or configured in the env field of settings.json to apply to every session.

Tip: All environment variables can also be set in the env field of settings.json, which automatically applies them to every session or rolls out configuration for an entire team.

Authentication ​

Environment VariableDescription
CODEBUDDY_API_KEYAPI key. Set this key for model API calls. Always uses this key in non-interactive mode (-p)
CODEBUDDY_AUTH_TOKENCodeBuddy platform authentication token for all platform API calls
CODEBUDDY_CUSTOM_HEADERSCustom HTTP headers. Format: Name: Value, multiple headers separated by newline or \n

API Endpoints and Proxy ​

Environment VariableDescription
CODEBUDDY_BASE_URLOverride the API endpoint address, typically used with CODEBUDDY_API_KEY
CODEBUDDY_INTERNET_ENVIRONMENTNetwork environment configuration (internal for China edition, ioa for iOA enterprise edition)
HTTP_PROXY / http_proxyHTTP proxy server address
HTTPS_PROXY / https_proxyHTTPS proxy server address
NO_PROXY / no_proxyList of domains and IPs to bypass proxy (comma-separated, e.g., localhost,.example.com)

Model Configuration ​

Environment VariableDescription
CODEBUDDY_MODELOverride the default agent model
CODEBUDDY_SMALL_FAST_MODELSmall, fast model used for background tasks
CODEBUDDY_BIG_SLOW_MODELLarge model used for complex reasoning tasks
CODEBUDDY_CODE_SUBAGENT_MODELModel used by sub-agents
MAX_THINKING_TOKENSEnable extended thinking and set the token budget for the thinking process. Disabled by default

Bash Tool Configuration ​

Environment VariableDescription
BASH_DEFAULT_TIMEOUT_MSDefault timeout for long-running bash commands (default: 120000)
BASH_MAX_OUTPUT_LENGTHMaximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk
BASH_MAX_TIMEOUT_MSMaximum timeout the model can set for long-running bash commands (default: 600000)
CODEBUDDY_BASH_ASSISTANT_BUDGET_MSMain conversation response budget (milliseconds, default 0=off). When set to >0, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. Aligns with Claude Code's ASSISTANT_BLOCKING_BUDGET_MS (CC's official default value 15000)
CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLEDSet to 1 to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios

Tool Output Externalization ​

Environment VariableDescription
CODEBUDDY_TOOL_RESULT_THRESHOLD_KBSize threshold (KB) for tool result externalization. Non-bash tool results exceeding this threshold are saved to disk and replaced with a placeholder (default: 50)

Note: Bash tool output externalization is controlled by BASH_MAX_OUTPUT_LENGTH. When output is truncated due to exceeding that value, the full output is automatically streamed to disk. CODEBUDDY_TOOL_RESULT_THRESHOLD_KB primarily affects large output handling for other tools (e.g., MCP tools). See the Tool Output Externalization section for details.

Tools and Feature Toggles ​

Environment VariableDescription
CODEBUDDY_DISABLE_HOT_RELOADSet to 1 to disable the hot reload system
CODEBUDDY_SKIP_BUILTIN_MARKETPLACESet to 1 to skip loading the built-in plugin marketplace
CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACESSet to true or 1 to enable automatic updates for third-party plugin marketplaces (default: disabled)
CODEBUDDY_PLUGIN_DIRSColon-separated list of local plugin directory paths (equivalent to --plugin-dir). The bin/ directory of each plugin is automatically injected into PATH
CODEBUDDY_IMAGE_GEN_ENABLEDSet to false or 0 to disable image generation
CODEBUDDY_IMAGE_EDIT_ENABLEDSet to false or 0 to disable image editing
CODEBUDDY_COMPUTER_USE_ENABLEDExperimental: Set to true or 1 to enable the macOS desktop control tool (screenshot, mouse, keyboard). Available only on macOS, disabled by default. The first invocation of keyboard/mouse actions requires authorizing the terminal in System Settings → Privacy & Security → Accessibility and Screen Recording
CODEBUDDY_DEFER_TOOL_LOADINGSet to false or 0 to disable MCP tool deferred loading
CODEBUDDY_SHOW_ALL_DEFERRED_TOOLSSet to true or 1 to show full descriptions for all deferred tools
CODEBUDDY_DISABLE_CRONSet to 1 to disable scheduled tasks
CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFSSet to true to rehydrate image blob references to full base64 data in -p mode streaming output. Useful for downstream integrations that need direct access to image data

Context and Memory ​

Environment VariableDescription
CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDESet the context capacity percentage for triggering auto-compaction (1-100). Default is determined by product configuration (typically 70-92%). Use a lower value (e.g., 50) to compact earlier
CODEBUDDY_PRE_MESSAGE_COMPACT_PCTSet the context capacity percentage for pre-message compaction check (1-100). Default is 10%. When context exceeds this threshold, it is automatically compacted before processing the user's new message
CODEBUDDY_DISABLE_AUTO_MEMORYSet to 1 to disable auto memory, set to 0 to enable
CODEBUDDY_MEMORY_ENABLEDSet to true or 1 to enable memory functionality
CODEBUDDY_TYPED_MEMORY_ENABLEDSet to true or 1 to enable typed memory mode
CODEBUDDY_TEAM_MEMORY_ENABLEDSet to true or 1 to enable team memory mode
CODEBUDDY_USER_IDUser ID for team memory mode

MCP (Model Context Protocol) ​

Environment VariableDescription
MCP_TIMEOUTTimeout for MCP server connections (milliseconds)
MCP_TOOL_TIMEOUTTimeout for MCP tool execution (milliseconds)
MAX_MCP_OUTPUT_TOKENSMaximum tokens allowed in MCP tool responses (default: 20000)
CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILESWhen set to 1, MCP oversized responses are not persisted to disk (skipping the ~/.codebuddy/projects/.../tool-results/ files), always falling back to content truncation

Performance and Output ​

Environment VariableDescription
CODEBUDDY_CODE_MAX_OUTPUT_TOKENSSet the maximum output tokens for most requests
CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENSOverride the default token limit for file reads (default: 20000)
CODEBUDDY_STREAM_TIMEOUT_MSMaximum silent time between two data chunks in streaming responses (milliseconds) (default: 120000)
CODEBUDDY_FIRST_TOKEN_TIMEOUT_MSMaximum time to wait for the first model output (milliseconds) (default: 120000)
CODEBUDDY_SESSION_MAX_ITEMSMaximum number of history messages to replay during session/load (default: 1000). Stops reading the JSONL in reverse when the threshold is reached and a user message is encountered. Increase (e.g., 2000 or more) when very long sessions need to be supported (such as sandbox scenarios); zero/negative/non-numeric values fall back to the default

Filesystem and Configuration ​

Environment VariableDescription
CODEBUDDY_CONFIG_DIRCustom location for CodeBuddy Code to store configuration and data files
CODEBUDDY_CODE_DEBUG_LOGS_DIRDebug log directory
CODEBUDDY_SANDBOX_IMAGEContainer sandbox image (default: node:20-alpine)
USE_BUILTIN_RIPGREPSet to 0 to use system-installed rg instead of the one bundled with CodeBuddy Code

Shell Configuration ​

Environment VariableDescription
CODEBUDDY_CODE_SHELLOverride automatic shell detection. Supported values: bash, zsh, sh, powershell
CODEBUDDY_CODE_SHELL_PREFIXCommand prefix wrapping all shell commands (e.g., for logging or auditing)
CODEBUDDY_CODE_GIT_BASH_PATHExplicitly specify the Git Bash path on Windows; startup fails if the specified path is invalid
CODEBUDDY_SKIP_GIT_BASH_CHECKSet to 1 to skip the Windows Git Bash detection and prompt at startup (useful when the upstream already manages the shell)
CODEBUDDY_POWERSHELL_PATHExplicitly specify the PowerShell executable path (takes priority over auto-detection)
CODEBUDDY_USE_POWERSHELL_TOOLControl PowerShell tool enablement. Enabled by default on Windows, set to 0 to disable
CODEBUDDY_ENV_FILEPath to an environment file that is automatically sourced before executing each shell command
CODEBUDDY_DISABLE_SHELL_SNAPSHOTSet to 1 to disable shell environment snapshots on all platforms (helpful when bash profile loading is slow)
CODEBUDDY_ENABLE_SHELL_SNAPSHOTOn Windows without Git Bash, snapshots are skipped by default; set to 1 to force enable (usually not needed)

UI and Interaction ​

Environment VariableDescription
CODEBUDDY_CODE_DISABLE_TERMINAL_TITLESet to 1 to disable automatic terminal title updates
CODEBUDDY_PROMPT_SUGGESTION_DISABLEDSet to true to disable prompt suggestions
IS_DEMOSet to true to enable demo mode: hides email and organization

Security and Authentication ​

Environment VariableDescription
CODEBUDDY_CODE_CLIENT_CERTmTLS client certificate file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEYmTLS client private key file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASEPassphrase for the mTLS encrypted private key (optional) ⚠️ Not yet supported

Telemetry and Reporting ​

Environment VariableDescription
DISABLE_TELEMETRYSet to 1 to disable telemetry
DISABLE_ERROR_REPORTINGSet to 1 to disable error reporting
DISABLE_AUTOUPDATERSet to 1 to disable auto-updates
DISABLE_FEEDBACK_COMMANDSet to 1 to disable the /feedback command

Tasks and Background Work ​

Environment VariableDescription
CODEBUDDY_DISABLE_BACKGROUND_TASKSSet to 1 to disable all background task functionality

Daemon Mode ​

Environment VariableDescription
CODEBUDDY_DAEMON_ALLOW_SLEEPSet to 1 or true to disable the daemon's sleep prevention (allows the system to enter idle sleep normally). Auto-reconnect after wake is not affected
CODEBUDDY_DAEMON_AUTO_CONNECT_CHANNELSSet to 0 or false to disable automatic channel connection (WeChat/WeCom) on daemon startup. Can also be configured via daemonAutoConnectChannels: false in settings.json. Individual instances can set autoConnect: false in instances.json
CODEBUDDY_DAEMON_RESTORE_CHANNELSSet by the system during daemon auto-restart, containing the list of channels to restore (comma-separated, e.g., wechat:abc,wecom:default). Users typically do not need to set this manually

Agent Execution Control ​

Environment VariableDescription
CODEBUDDY_CODE_MAX_TURNSMaximum execution turns for the main Agent. Priority: CLI --max-turns > this environment variable > default (500)
CODEBUDDY_CODE_SUBAGENT_MAX_TURNSMaximum execution turns for sub-Agents. Priority: CLI --max-turns > this environment variable > model dynamically passed max_turns > default (500)
CODEBUDDY_SUBAGENT_PERMISSION_MODEDefault permission mode for sub-agents/team members (e.g., bypassPermissions, acceptEdits, default, plan). Priority: Agent tool mode parameter > CLI --subagent-permission-mode > this environment variable > Settings permissions.subagentPermissionMode > mapping table default
CODEBUDDY_TEAM_IDLE_DETECTION_DISABLEDSet to 1 to disable teammate idle awareness (enabled by default). When disabled, "wait for teammate idle"-type APIs return true immediately without blocking, and progress snapshots are no longer recorded
CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MSFallback timeout (in milliseconds) for graceful team member shutdown, default 15000. After this duration without a response from the teammate, the process is forcibly terminated. Set to 0 to disable the forced fallback (pure wait for response)

Gateway and Remote Access ​

Environment VariableDescription
CODEBUDDY_GATEWAY_AUTHGateway authentication mode (password or none)
CODEBUDDY_GATEWAY_PASSWORDGateway access password
CODEBUDDY_GATEWAY_FORCE_TUNNELSet to 1 to force tunnel mode
CODEBUDDY_DISABLE_REQUEST_VALIDATIONSet to 1 to disable Gateway custom request header validation (X-CodeBuddy-Request). See HTTP API Security
CODEBUDDY_CODE_CORS_ORIGINSAdditional CORS allowed origins (comma-separated). Supports exact origins, *.domain subdomain wildcards, and * for all. E.g., https://*.example.com,https://specific.com
SERVER__HOSTListen address for --serve mode (default: 127.0.0.1)
SERVER__PORTListen port for --serve mode

WeCom Integration ​

Environment VariableDescription
CODEBUDDY_GATEWAY_WECHAT_KF_TOKENWeCom Customer Service Token
CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEYWeCom Customer Service Encryption Key
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_IDWeCom Customer Service Corp ID
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRETWeCom Customer Service Corp Secret
CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAMEWeCom Customer Service Account Name
CODEBUDDY_GATEWAY_WECOM_TOKENWeCom Token
CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEYWeCom Encryption Key
CODEBUDDY_GATEWAY_WECOM_CORP_IDWeCom Corp ID
CODEBUDDY_GATEWAY_WECOM_CORP_SECRETWeCom Corp Secret
CODEBUDDY_GATEWAY_WECOM_AGENT_IDWeCom Agent ID

Debugging and Diagnostics ​

Environment VariableDescription
CODEBUDDY_DEBUGSet to 1 to enable debug mode
CODEBUDDY_DEBUG_REQUESTSet to 1 to enable request debugging
CODEBUDDY_STARTUP_PROFILESet to 1 to enable startup profiling

E2E Testing (Record/Replay) ​

Record/replay functionality for model responses in E2E tests. In record mode, real model responses are captured; in replay mode, recorded files are used in place of real API calls.

Environment VariableDescription
CODEBUDDY_RECORD_DIRRecord mode: directory where recording files are saved. When set, model responses are saved to recording.jsonl in this directory
CODEBUDDY_REPLAY_DIRReplay mode: directory from which recording files are read. When set, responses are replayed from recording.jsonl without requiring a real API
CODEBUDDY_REPLAY_SPEEDReplay speed multiplier. 0 means no delay (instant return), 1 means replay at original timing intervals (default: 1)
CODEBUDDY_REPLAY_STRICTSet to 1 to enable strict mode: throws an error when recordings are exhausted instead of falling through to the real API

Note: CODEBUDDY_RECORD_DIR and CODEBUDDY_REPLAY_DIR are mutually exclusive and cannot be set at the same time.

Miscellaneous ​

Environment VariableDescription
SLASH_COMMAND_TOOL_CHAR_BUDGETMaximum character count for slash command tool metadata (default: 15000)
CODEBUDDY_CODE_API_KEY_HELPER_TTL_MSInterval for refreshing credentials (milliseconds) (default: 300000)

Usage Examples ​

Basic Authentication Configuration ​

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

# Set proxy server
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

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

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

# Start CodeBuddy
codebuddy

Using Third-Party Model Services ​

bash
# Use a custom API endpoint
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_BASE_URL="https://api.example.com/v1"
codebuddy --model your-model-name

Connecting to DeepSeek Example ​

To connect to any third-party model service compatible with the Anthropic protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional models.json modifications are required:

bash
# Endpoint and key
export CODEBUDDY_BASE_URL="https://api.deepseek.com"
export CODEBUDDY_API_KEY="<your-deepseek-api-key>"

# Default model for the main Agent
export CODEBUDDY_MODEL="deepseek-v4-pro"

# Large model used for complex reasoning
export CODEBUDDY_BIG_SLOW_MODEL="deepseek-v4-pro"

# Small model for background/lightweight tasks
export CODEBUDDY_SMALL_FAST_MODEL="deepseek-v4-flash"

# Model used by sub-agents (inherits from the main Agent when unset)
export CODEBUDDY_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

# Optionally specify the main model explicitly via --model at startup
codebuddy --model deepseek-v4-pro

Tip: The variables above can also be written into the env field of settings.json so they automatically apply to each session, making team-wide configuration easier.

China Edition Configuration ​

bash
# Set China edition environment identifier
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

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

# Start CodeBuddy
codebuddy

Enabling Advanced Features ​

bash
# Enable auto memory
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

# Enable extended thinking
export MAX_THINKING_TOKENS="10000"

# Run in non-interactive mode
codebuddy -p -y "your query"

Debugging and Profiling ​

bash
# Enable debug mode
export CODEBUDDY_DEBUG="1"

# Enable startup profiling
export CODEBUDDY_STARTUP_PROFILE="1"

# Start CodeBuddy
codebuddy

Configuring in settings.json ​

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

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

Tool Output Externalization Mechanism ​

When tool execution produces output exceeding the threshold, CodeBuddy Code automatically saves the full output to disk and sends only truncated content with a file path pointer to the model, which can read the full content on demand.

Data Flow ​

Shell output
  ├─→ OutputSpiller (full output streamed to disk)
  └─→ TruncateBuffer (head + tail retained in memory, ~30KB)
                          ↓
                  Truncation detected → generate placeholder (~2KB preview + file path)
                          ↓
                  Model receives placeholder, can read full file via Read tool on demand

Data Size at Each Stage (using 1.3MB output as example) ​

StageContentSize
Disk file (OutputSpiller)Full raw output1,355,099 bytes
Memory buffer (TruncateBuffer)head 6KB + tail 24KB~30KB
Sent to model (placeholder)File path + preview~2KB

Storage Directory ​

Tool output files are stored in the project data directory:

~/.codebuddy/projects/{projectDir}/
  └── {sessionId}/
      ├── tool-results/                          ← Main session tool results
      │   ├── {callId}.txt
      │   └── ...
      └── subagents/                             ← Sub-agent data
          ├── agent-{agentId}.jsonl              ← Sub-agent conversation history
          └── agent-{agentId}/
              └── tool-results/                  ← Sub-agent tool results
                  ├── {callId}.txt
                  └── ...
Environment VariableScopeDefault
BASH_MAX_OUTPUT_LENGTHBash tool memory retention, triggers disk externalization when exceeded30000
CODEBUDDY_TOOL_RESULT_THRESHOLD_KBSession-level externalization threshold for non-bash tools (e.g., MCP)50

See Also ​

  • Settings - Configure environment variables and other settings in settings.json
  • CLI Reference - Complete list of command-line arguments
  • MCP Setup - MCP server configuration
  • Sub-Agents - Sub-agent storage directory documentation