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_MODELOverride the model for the lite (lightweight, fast) scenario variant; takes priority over the variantModels.lite setting
CODEBUDDY_BIG_SLOW_MODELOverride the model for the reasoning (enhanced reasoning) scenario variant; takes priority over the variantModels.reasoning setting
CODEBUDDY_CODE_SUBAGENT_MODELBlanket override of the model for all built-in sub-agents (highest priority, overrides the subagents setting). To configure per sub-agent, use the /agents panel or settings.json's subagents.agents.<subagent-name>.model
MAX_THINKING_TOKENSEnable extended thinking and set the token budget for the thinking process. Disabled by default

Relationship between env and settings: Model-related environment variables are for ops/CI-level overrides.

  • Built-in sub-agents: CODEBUDDY_CODE_SUBAGENT_MODEL > the model parameter of the current Agent tool call > project-level subagents > user-global subagents > product built-in declaration > main model.

  • Scenario variants: corresponding variant env var > project-level variantModels > user-global variantModels > main model's relatedModels > applicable product built-in default > main model.

  • CODEBUDDY_CODE_SUBAGENT_MODEL uniformly overrides all sub-agents. To specify individually, use /agents or subagents.agents.<subagent-name>.model; see Sub-Agents for details.

  • CODEBUDDY_SMALL_FAST_MODEL only affects lite, CODEBUDDY_BIG_SLOW_MODEL only affects reasoning. The corresponding persistent settings can be managed via /model or variantModels; see Settings for details.

Removing the environment variable restores the lower-priority configuration, which may not directly fall back to the main model.

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 (official default value is 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
CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTESTotal byte limit for the on-disk file of stdout+stderr for background bash tasks (default 52428800 = 50MB). When exceeded, the size watchdog fires SIGKILL and marks the task as killed, with a notice injected at the end of stderr. Claude Code in ShellCommand.ts hardcodes the equivalent threshold as a constant; here it is exposed as an env var for operators to tune. Only effective in file fd mode (in pipe mode, child process output is not persisted to disk)
CODEBUDDY_BASH_BG_PIPE_MODESet to 1 to force background tasks back to pipe mode (not using file fds), for rollback or debugging. The default (unset) uses file fd mode, which solves the zombie process issue caused by grandchild processes (e.g., spawned via nohup) holding parent pipe fds; the sandbox path automatically falls back to pipe and does not require explicit setting. There is no equivalent toggle in Claude Code; this is a CodeBuddy fallback to remain compatible with legacy sandbox/PTY paths

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_MARKETPLACE_AUTO_UPDATE_INTERVAL_MSOverride the refresh window for plugin marketplace auto-updates (milliseconds), default 86400000 (24 hours). Set to a smaller value (e.g., 3600000 = 1 hour) to shorten the auto-update detection interval, useful for testing/debugging; invalid values (non-numeric or ≤0) fall back to the default
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_DISABLE_EXTENDED_PLUGIN_HOOKSWhen set to 1 or true, plugin Hook configurations only accept the command type; configurations containing prompt, agent, or http types are treated as incompatible. Used by hosts to temporarily roll back the plugin Hook contract; unset by default
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_ARTIFACT_ENABLEDSet to false or 0 to disable the Artifact / ArtifactControl tool (publishes a local single HTML or Markdown file as a shareable public link; Markdown is server-rendered into a styled page; ArtifactControl currently only supports unpublishing). Enabled by default. Evaluation order: under international endpoints (codebuddy.ai / workbuddy.ai / staging-codebuddy.tencent.com), this capability is always off and this variable cannot override it; in all other scenarios, this variable has the highest priority — when unset (including empty values), falls back to the legacy variable CODEBUDDY_SHARE_LINK_ENABLED, then to the cloud-side productFeatures (if either Artifact or ShareLink is explicitly false, the feature is off; when neither is delivered, defaults to true)
CODEBUDDY_SHARE_LINK_ENABLEDDeprecated (kept for compatibility): The former name of CODEBUDDY_ARTIFACT_ENABLED, the toggle from before the ShareLink tool was renamed to Artifact. Semantics are identical to the new variable, which takes priority; only takes effect when the new variable is unset
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_PUSH_NOTIFICATION_ENABLEDSet to false or 0 to disable the PushNotification tool (the model can proactively trigger a terminal/desktop notification when long-running or background tasks complete). Enabled by default
CODEBUDDY_REPORT_FINDINGS_ENABLEDSet to false or 0 to disable the ReportFindings tool (used by code review Agents to submit findings as structured fields, rendered as a dedicated list component). Enabled by default
CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLEDSet to 0 or false to disable the WaitForMcpServers tool. Enabled by default. In interactive mode, MCP connections are not awaited blockingly; when the LLM needs an MCP tool that is not yet ready, it can proactively call this tool to wait on demand. Set to 0 to disable in WorkBuddy scenarios
CODEBUDDY_DEFERRED_TOOLS_MCP_READY_WAIT_MSMaximum milliseconds to wait for MCP servers to be ready before rendering deferred tool descriptions, default 2500. Set to 0 to skip waiting entirely — if connections are slow, the "still connecting" hint is immediately baked into the description; increase to give remote MCP servers more time to complete the handshake before the first prompt. Continues immediately once the server is ready; the timeout serves only as an upper bound
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_DISABLE_FORK_SUBAGENTSet to 1 to disable the Agent tool's fork sub-agent mode (subagent_type="fork"). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes subagent_type="fork", the runtime falls back to a custom agent named fork (e.g., one defined by the user at .codebuddy/agents/fork.md), or otherwise rewrites it to a general-purpose regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning
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
CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKSSet to 1 / true to disable background tasks for the Agent, Bash, and PowerShell tools (run_in_background=true). When enabled, the run_in_background parameter is hidden from these tools' schemas so the model will not see it; even if historical/cached tool calls or direct callers pass this parameter, the runtime falls back to synchronous (Agent) / foreground (Bash, PowerShell) execution. Suitable for request-response SDK / one-shot task scenarios—where the main process exits immediately after the main turn ends and any background agent/background command results cannot flow back to the final response. Aligns with Claude Code's CLAUDE_CODE_DISABLE_BACKGROUND_TASKS (which also governs Agent + Bash + PowerShell). Unset by default (background tasks remain available). Independent from the print-mode guard (which always blocks background execution under -p)

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_COMPACTForce-control the pre-message compaction toggle. true/1 to enable, false/0 to disable. Takes priority over the product configuration's enablePreMessageCompact and the ContextSummaryAgent toggle
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: 300000, i.e., 5 minutes). Silence mid-stream after tokens have started usually means the connection is broken, so this is decoupled from the first-token timeout and uses a shorter threshold
CODEBUDDY_FIRST_TOKEN_TIMEOUT_MSMaximum time to wait for the first model output (milliseconds) (default: 1200000, i.e., 20 minutes). Slow first-token emission due to long-context prefill is a legitimate scenario
CODEBUDDY_MAX_RETRIESMaximum backoff retry count for model request failures that occur "before generation starts" (429 / 5xx / request timeout / lock timeout) (default: 8, max: 15, auto-clamped when exceeded). Retries use exponential backoff + jitter and respect the server's retry-after; they strictly occur before streaming content is produced and do not resend already-produced content. Quota-exhaustion errors are not retried (handled by model fallback instead)
CODEBUDDY_RETRY_WATCHDOGSet to 1 / true / yes to enable infinite retry mode for unattended / CI scenarios. Only applies to the "before generation starts" failures above; single backoff is capped at 5 minutes. Off by default
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_INCLUDE_PROMPT_SUGGESTIONExplicitly enable prompt suggestions, overriding the headless default (off) and promptSuggestionEnabled=false configuration
CODEBUDDY_PROMPT_SUGGESTION_DISABLEDSet to 1 / true to disable prompt suggestions, takes priority over CODEBUDDY_INCLUDE_PROMPT_SUGGESTION
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

OpenTelemetry Custom Reporting (traces) ​

CodeBuddy Code supports reporting internal traces to your own Collector via the OTLP protocol. Environment variables follow the OpenTelemetry specification. For detailed usage, see Monitoring.

Environment VariableDescription
CODEBUDDY_CODE_ENABLE_TELEMETRYSet to 1 to enable OTel custom reporting; the legacy alias CLAUDE_CODE_ENABLE_TELEMETRY is also accepted for backward compatibility
OTEL_TRACES_EXPORTERotlp (default) / console (output to logs, useful for debugging) / none (off)
OTEL_EXPORTER_OTLP_ENDPOINTGeneric OTLP endpoint; the tool automatically appends /v1/traces
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTTraces-specific endpoint, used as a complete URL; takes priority over the generic variable
OTEL_EXPORTER_OTLP_HEADERSOTLP request headers in the format k1=v1,k2=v2; values support URL encoding
OTEL_EXPORTER_OTLP_TRACES_HEADERSTraces-specific request headers; takes priority over the generic variable
OTEL_EXPORTER_OTLP_PROTOCOLOnly http/protobuf (default) is supported; other values (such as grpc, http/json) fall back and emit a warning
OTEL_SERVICE_NAMEOverride the default service.name
OTEL_RESOURCE_ATTRIBUTESResource attributes in the format k1=v1,k2=v2; merged into the trace resource

When DISABLE_TELEMETRY=1, OTel reporting is turned off regardless of the variables above.

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_CODE_MAX_SUBAGENTS_PER_SESSIONPer-session sub-agent spawn budget limit (positive integer, default 200, adjustable up or down, cannot be disabled). Nested spawns share the same budget; when the limit is exceeded, the Agent tool returns an error and suggests using its own tools to complete the remaining work; resets after /clear creates a new session
CODEBUDDY_CODE_DISABLE_AUTO_MEMORYSet to a truthy value to disable agent-level persistent memory (the frontmatter memory field no longer injects memory paragraphs). Unset by default (enabled)
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). Highest priority, overrides --auth and settings gateway.auth. --serve defaults to password; setting to none disables authentication, allowing any process on the same machine to execute commands and read/write files via this service. Only recommended in isolated environments or CI
CODEBUDDY_GATEWAY_PASSWORDGateway access password. When unset, a random password is automatically generated on first startup and written to settings
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. When unset, if the service is bound to 0.0.0.0 (--host 0.0.0.0), all origins are automatically allowed
SERVER__HOSTListen address for --serve mode (default: 127.0.0.1)
SERVER__PORTListen port for --serve mode; set to 0 for a kernel-assigned port — the variable is updated to the actual listening port once the server is bound

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

Channel Auto-Connect ​

Environment VariableDescription
CODEBUDDY_CHANNEL_AUTO_CONNECTSet to 1 or true to automatically connect all configured channels (WeCom + WeChat) on startup
CODEBUDDY_WECOM_AUTO_CONNECTSet to 1 or true to automatically connect all configured WeCom bot instances on startup
CODEBUDDY_WECHAT_AUTO_CONNECTSet to 1 or true to automatically connect all configured WeChat bot instances on startup
CODEBUDDY_WECOM_BOT_IDWeCom AI Assistant Bot ID. When set, a default instance is automatically created and appears in the /remote-control list
CODEBUDDY_WECOM_BOT_SECRETWeCom AI Assistant Secret. Must be used together with CODEBUDDY_WECOM_BOT_ID

Tip: CODEBUDDY_CHANNEL_AUTO_CONNECT is the master toggle, while CODEBUDDY_WECOM_AUTO_CONNECT and CODEBUDDY_WECHAT_AUTO_CONNECT are per-type toggles. Any one of the three being set will take effect. Works in all modes (interactive, --serve, daemon).

Debugging and Diagnostics ​

Environment VariableDescription
CODEBUDDY_DEBUGSet to 1/true/yes/on to enable debug mode (equivalent to --debug)
CODEBUDDY_DEBUG_SDKSet to 1/true/yes/on to enable SDK debugging
CODEBUDDY_DEBUG_REQUESTSet to 1 to enable request debugging
CODEBUDDY_STARTUP_PROFILESet to 1 to enable startup profiling
CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCTOOM forensics (off by default). When enabled, if the process heap crosses the V8 heap limit high-water mark, a heap snapshot is automatically written to ~/.codebuddy/diagnostics/<date>/oom-nearlimit-<pid>-<ts>.heapsnapshot (written only once per process). Values: on/true/1 for the default 85% threshold; 0.9 or 90 for a custom threshold; unset / 0 / off / false to disable. ⚠️ Snapshot files are ~1.5× the heapUsed at that time (multi-GB heaps produce multi-GB files); only enable when troubleshooting OOM. See Troubleshooting · OOM
CBC_HEAP_SNAPSHOT_ON_WORKFLOW_ENDSet to 1 to write a heap snapshot after each workflow (e.g., ultracode) completes, saved to ~/.codebuddy/diagnostics/<date>/. Off by default (consumes disk); only enable when troubleshooting workflow memory leaks

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"

# Ops-level blanket override for all sub-agents.
# When unset, per-invocation, per-sub-agent settings, and product built-in orchestration are used.
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