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)

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

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)

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

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

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)

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

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

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