# 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`](./settings.md#available-settings) 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 Variable | Description |
|---------|------|
| `CODEBUDDY_API_KEY` | API key. Set this key for model API calls. Always uses this key in non-interactive mode (`-p`) |
| `CODEBUDDY_AUTH_TOKEN` | CodeBuddy platform authentication token for all platform API calls |
| `CODEBUDDY_CUSTOM_HEADERS` | Custom HTTP headers. Format: `Name: Value`, multiple headers separated by newline or `\n` |

## API Endpoints and Proxy

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_BASE_URL` | Override the API endpoint address, typically used with `CODEBUDDY_API_KEY` |
| `CODEBUDDY_INTERNET_ENVIRONMENT` | Network environment configuration (`internal` for China edition, `ioa` for iOA enterprise edition) |
| `HTTP_PROXY` / `http_proxy` | HTTP proxy server address |
| `HTTPS_PROXY` / `https_proxy` | HTTPS proxy server address |
| `NO_PROXY` / `no_proxy` | List of domains and IPs to bypass proxy (comma-separated, e.g., `localhost,.example.com`) |

## Model Configuration

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_MODEL` | Override the default agent model |
| `CODEBUDDY_SMALL_FAST_MODEL` | Small, fast model used for background tasks |
| `CODEBUDDY_BIG_SLOW_MODEL` | Large model used for complex reasoning tasks |
| `CODEBUDDY_CODE_SUBAGENT_MODEL` | Model used by sub-agents |
| `MAX_THINKING_TOKENS` | Enable extended thinking and set the token budget for the thinking process. Disabled by default |

## 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 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_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000) |
| `CODEBUDDY_BASH_ASSISTANT_BUDGET_MS` | Main 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 CodeBuddy Code's `ASSISTANT_BLOCKING_BUDGET_MS` (the official default value is `15000`) |
| `CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED` | Set 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_BYTES` | Total 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. CodeBuddy 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_MODE` | Set 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 elsewhere; this is a CodeBuddy Code fallback to remain compatible with legacy sandbox/PTY paths |

## Tool Output Externalization

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | Size 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](#tool-output-externalization-mechanism) section for details.

## Tools and Feature Toggles

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_DISABLE_HOT_RELOAD` | Set to `1` to disable the hot reload system |
| `CODEBUDDY_SKIP_BUILTIN_MARKETPLACE` | Set to `1` to skip loading the built-in plugin marketplace |
| `CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES` | Set to `true` or `1` to enable automatic updates for third-party plugin marketplaces (default: disabled) |
| `CODEBUDDY_PLUGIN_DIRS` | Colon-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_ENABLED` | Set to `false` or `0` to disable image generation |
| `CODEBUDDY_IMAGE_EDIT_ENABLED` | Set to `false` or `0` to disable image editing |
| `CODEBUDDY_COMPUTER_USE_ENABLED` | **Experimental**: 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_WAIT_FOR_MCP_SERVERS_ENABLED` | Set 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_DEFER_TOOL_LOADING` | Set to `false` or `0` to disable MCP tool deferred loading |
| `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | Set to `true` or `1` to show full descriptions for all deferred tools |
| `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
| `CODEBUDDY_DISABLE_FORK_SUBAGENT` | Set 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_REFS` | Set 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 Variable | Description |
|---------|------|
| `CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE` | Set 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_PCT` | Set 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_MEMORY` | Set to `1` to disable auto memory, set to `0` to enable |
| `CODEBUDDY_MEMORY_ENABLED` | Set to `true` or `1` to enable memory functionality |
| `CODEBUDDY_TYPED_MEMORY_ENABLED` | Set to `true` or `1` to enable typed memory mode |
| `CODEBUDDY_TEAM_MEMORY_ENABLED` | Set to `true` or `1` to enable team memory mode |
| `CODEBUDDY_USER_ID` | User ID for team memory mode |

## MCP (Model Context Protocol)

| Environment Variable | Description |
|---------|------|
| `MCP_TIMEOUT` | Timeout for MCP server connections (milliseconds) |
| `MCP_TOOL_TIMEOUT` | Timeout for MCP tool execution (milliseconds) |
| `MAX_MCP_OUTPUT_TOKENS` | Maximum tokens allowed in MCP tool responses (default: 20000) |
| `CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES` | When 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 Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | Set the maximum output tokens for most requests |
| `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads (default: 20000) |
| `CODEBUDDY_STREAM_TIMEOUT_MS` | Maximum silent time between two data chunks in streaming responses (milliseconds) (default: 1200000) |
| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | Maximum time to wait for the first model output (milliseconds) (default: 1200000) |
| `CODEBUDDY_SESSION_MAX_ITEMS` | Maximum 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 Variable | Description |
|---------|------|
| `CODEBUDDY_CONFIG_DIR` | Custom location for CodeBuddy Code to store configuration and data files |
| `CODEBUDDY_CODE_DEBUG_LOGS_DIR` | Debug log directory |
| `CODEBUDDY_SANDBOX_IMAGE` | Container sandbox image (default: `node:20-alpine`) |
| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of the one bundled with CodeBuddy Code |

## Shell Configuration

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_SHELL` | Override automatic shell detection. Supported values: `bash`, `zsh`, `sh`, `powershell` |
| `CODEBUDDY_CODE_SHELL_PREFIX` | Command prefix wrapping all shell commands (e.g., for logging or auditing) |
| `CODEBUDDY_CODE_GIT_BASH_PATH` | Explicitly specify the Git Bash path on Windows; startup fails if the specified path is invalid |
| `CODEBUDDY_SKIP_GIT_BASH_CHECK` | Set to `1` to skip the Windows Git Bash detection and prompt at startup (useful when the upstream already manages the shell) |
| `CODEBUDDY_POWERSHELL_PATH` | Explicitly specify the PowerShell executable path (takes priority over auto-detection) |
| `CODEBUDDY_USE_POWERSHELL_TOOL` | Control PowerShell tool enablement. Enabled by default on Windows, set to `0` to disable |
| `CODEBUDDY_ENV_FILE` | Path to an environment file that is automatically sourced before executing each shell command |
| `CODEBUDDY_DISABLE_SHELL_SNAPSHOT` | Set to `1` to disable shell environment snapshots on all platforms (helpful when bash profile loading is slow) |
| `CODEBUDDY_ENABLE_SHELL_SNAPSHOT` | On Windows without Git Bash, snapshots are skipped by default; set to `1` to force enable (usually not needed) |

## UI and Interaction

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates |
| `CODEBUDDY_PROMPT_SUGGESTION_DISABLED` | Set to `true` to disable prompt suggestions |
| `IS_DEMO` | Set to `true` to enable demo mode: hides email and organization |

## Security and Authentication

| 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` | Passphrase for the mTLS encrypted private key (optional) ⚠️ *Not yet supported* |

## Telemetry and Reporting

| Environment Variable | Description |
|---------|------|
| `DISABLE_TELEMETRY` | Set to `1` to disable telemetry |
| `DISABLE_ERROR_REPORTING` | Set to `1` to disable error reporting |
| `DISABLE_AUTOUPDATER` | Set to `1` to disable auto-updates |
| `DISABLE_FEEDBACK_COMMAND` | Set 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](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). For detailed usage, see [Monitoring](monitoring.md).

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OTel custom reporting; the legacy alias `CLAUDE_CODE_ENABLE_TELEMETRY` is also accepted for backward compatibility |
| `OTEL_TRACES_EXPORTER` | `otlp` (default) / `console` (output to logs, useful for debugging) / `none` (off) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Generic OTLP endpoint; the tool automatically appends `/v1/traces` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Traces-specific endpoint, used as a complete URL; takes priority over the generic variable |
| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP request headers in the format `k1=v1,k2=v2`; values support URL encoding |
| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Traces-specific request headers; takes priority over the generic variable |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Only `http/protobuf` (default) is supported; other values (such as `grpc`, `http/json`) fall back and emit a warning |
| `OTEL_SERVICE_NAME` | Override the default `service.name` |
| `OTEL_RESOURCE_ATTRIBUTES` | Resource 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 Variable | Description |
|---------|------|
| `CODEBUDDY_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality |

## Daemon Mode

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_DAEMON_ALLOW_SLEEP` | Set 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_CHANNELS` | Set 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_CHANNELS` | Set 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 Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_MAX_TURNS` | Maximum execution turns for the main Agent. Priority: CLI `--max-turns` > this environment variable > default (500) |
| `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | Maximum execution turns for sub-Agents. Priority: CLI `--max-turns` > this environment variable > model dynamically passed `max_turns` > default (500) |
| `CODEBUDDY_SUBAGENT_PERMISSION_MODE` | Default 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_DISABLED` | Set 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_MS` | Fallback 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 Variable | Description |
|---------|------|
| `CODEBUDDY_GATEWAY_AUTH` | Gateway authentication mode (`password` or `none`) |
| `CODEBUDDY_GATEWAY_PASSWORD` | Gateway access password |
| `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | Set to `1` to force tunnel mode |
| `CODEBUDDY_DISABLE_REQUEST_VALIDATION` | Set to `1` to disable Gateway custom request header validation (`X-CodeBuddy-Request`). See [HTTP API Security](./http-api.md#security) |
| `CODEBUDDY_CODE_CORS_ORIGINS` | Additional CORS allowed origins (comma-separated). Supports exact origins, `*.domain` subdomain wildcards, and `*` for all. E.g., `https://*.example.com,https://specific.com` |
| `SERVER__HOST` | Listen address for `--serve` mode (default: `127.0.0.1`) |
| `SERVER__PORT` | Listen port for `--serve` mode |

## WeCom Integration

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN` | WeCom Customer Service Token |
| `CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY` | WeCom Customer Service Encryption Key |
| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID` | WeCom Customer Service Corp ID |
| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET` | WeCom Customer Service Corp Secret |
| `CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME` | WeCom Customer Service Account Name |
| `CODEBUDDY_GATEWAY_WECOM_TOKEN` | WeCom Token |
| `CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY` | WeCom Encryption Key |
| `CODEBUDDY_GATEWAY_WECOM_CORP_ID` | WeCom Corp ID |
| `CODEBUDDY_GATEWAY_WECOM_CORP_SECRET` | WeCom Corp Secret |
| `CODEBUDDY_GATEWAY_WECOM_AGENT_ID` | WeCom Agent ID |

## Debugging and Diagnostics

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_DEBUG` | Set to `1`/`true`/`yes`/`on` to enable debug mode (equivalent to `--debug`) |
| `CODEBUDDY_DEBUG_SDK` | Set to `1`/`true`/`yes`/`on` to enable SDK debugging |
| `CODEBUDDY_DEBUG_REQUEST` | Set to `1` to enable request debugging |
| `CODEBUDDY_STARTUP_PROFILE` | Set 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 Variable | Description |
|---------|------|
| `CODEBUDDY_RECORD_DIR` | Record mode: directory where recording files are saved. When set, model responses are saved to `recording.jsonl` in this directory |
| `CODEBUDDY_REPLAY_DIR` | Replay mode: directory from which recording files are read. When set, responses are replayed from `recording.jsonl` without requiring a real API |
| `CODEBUDDY_REPLAY_SPEED` | Replay speed multiplier. `0` means no delay (instant return), `1` means replay at original timing intervals (default: `1`) |
| `CODEBUDDY_REPLAY_STRICT` | Set 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 Variable | Description |
|---------|------|
| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum character count for slash command tool metadata (default: 15000) |
| `CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS` | Interval 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 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)

| Stage | Content | Size |
|------|------|------|
| Disk file (OutputSpiller) | Full raw output | 1,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
                  └── ...
```

### Related Environment Variables

| Environment Variable | Scope | Default |
|---------|---------|--------|
| `BASH_MAX_OUTPUT_LENGTH` | Bash tool memory retention, triggers disk externalization when exceeded | 30000 |
| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | Session-level externalization threshold for non-bash tools (e.g., MCP) | 50 |

## See Also

- [Settings](./settings.md) - Configure environment variables and other settings in `settings.json`
- [CLI Reference](./cli-reference.md) - Complete list of command-line arguments
- [MCP Setup](./mcp.md) - MCP server configuration
- [Sub-Agents](./sub-agents.md) - Sub-agent storage directory documentation
