@tencent-ai/agent-sdk 0.3.98 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/settings.md

@@ -0,0 +1,602 @@
+# Settings Configuration
+
+CodeBuddy Code uses a layered configuration system that enables personalization at different levels, from personal preferences to team standards to project-specific requirements.
+
+## Configuration Files
+
+The `settings.json` file is the official mechanism for configuring CodeBuddy Code, supporting layered settings:
+
+* **User settings** are defined in `~/.codebuddy/settings.json` and apply to all projects
+* **Project settings** are stored in the project directory:
+  * `.codebuddy/settings.json` for settings checked into source control and shared with the team
+  * `.codebuddy/settings.local.json` for settings not checked in, suitable for personal preferences and experiments. CodeBuddy Code automatically configures git to ignore this file
+
+### Complete Configuration Example
+
+```json
+{
+  "language": "English",
+  "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",
+  "cleanupPeriodDays": 30,
+  "includeCoAuthoredBy": false,
+  "statusLine": {
+    "type": "command",
+    "command": "~/.codebuddy/statusline.sh"
+  }
+}
+```
+
+## Available Settings
+
+`settings.json` supports the following options:
+
+| Key | Description | Example |
+|:------|:-----|:-----|
+| `language` | Preferred response language. When set, CodeBuddy Code will respond in the specified language. Leave empty to auto-detect based on user input | `"English"` |
+| `apiKeyHelper` | Custom script executed in `/bin/sh` that generates an authentication value. This value is sent as both `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |
+| `textToImageModel` | Model ID used for text-to-image generation | `"your-image-model"` |
+| `imageToImageModel` | Model ID used for image-to-image generation | `"your-edit-model"` |
+| `cleanupPeriodDays` | How long to locally retain chat history based on last activity date (default: 30 days) | `20` |
+| `env` | Environment variables applied to every session | `{"FOO": "bar"}` |
+| `includeCoAuthoredBy` | Whether to include `co-authored-by CodeBuddy` attribution in git commits and pull requests (default: `true`) | `false` |
+| `permissions` | Permission configuration, see table below | |
+| `hooks` | Configure custom commands to run before and after tool execution. See [hooks documentation](hooks.md) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
+| `disableAllHooks` | Disable all [hooks](hooks.md) | `true` |
+| `model` | Override the default model used by CodeBuddy Code | `"gpt-5"` |
+| `statusLine` | Configure a custom status line to display context. See [statusLine documentation](#status-line-configuration) | `{"type": "command", "command": "~/.codebuddy/statusline.sh"}` |
+| `enableAllProjectMcpServers` | Auto-approve all MCP servers defined in the project's `.mcp.json` file | `true` |
+| `enabledMcpjsonServers` | List of specific MCP servers approved from `.mcp.json` files | `["memory", "github"]` |
+| `disabledMcpjsonServers` | List of specific MCP servers rejected from `.mcp.json` files | `["filesystem"]` |
+| `autoCompactEnabled` | Enable auto-compaction | `true` |
+| `autoUpdates` | Auto-update settings | `false` |
+| `alwaysThinkingEnabled` | Always enable thinking mode | `true` |
+| `showTokensCounter` | Whether to show the tokens counter in the interface | `false` |
+| `endpoint` | Custom server endpoint address | `"https://api.example.com"` |
+| `envRouteMode` | Environment routing mode configuration | `"production"` |
+| `sandbox` | Bash sandbox configuration, see [Bash Sandbox Settings](#bash-sandbox-settings) | `{"enabled": true}` |
+| `promptSuggestionEnabled` | Enable prompt suggestions, automatically predicting next actions after the agent completes a conversation (default: `true`) | `false` |
+| `reasoningEffort` | Reasoning effort level, controlling the depth of model reasoning. Options: `low`, `medium`, `high`, `xhigh`. When empty, uses the product configuration default. Can be toggled via the `/config` panel; selecting `auto` is equivalent to clearing this setting | `"high"` |
+| `memory` | [Experimental] Memory feature configuration, see [Memory Configuration](#memory-configuration-experimental) | `{"enabled": true}` |
+
+### Permission Settings
+
+| Key | Description | Example |
+|:------|:-----|:-----|
+| `allow` | Array of [permission rules](iam.md#configuring-permissions) allowing tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |
+| `ask` | Array of [permission rules](iam.md#configuring-permissions) requiring confirmation for tool use | `[ "Bash(git push:*)" ]` |
+| `deny` | Array of [permission rules](iam.md#configuring-permissions) denying tool use. Used to exclude CodeBuddy Code from accessing sensitive files. **Note:** Bash patterns are prefix-matched and can be bypassed (see [Bash Permission Limitations](iam.md#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |
+| `additionalDirectories` | Additional [working directories](iam.md#working-directories) that CodeBuddy can access | `[ "../docs/" ]` |
+| `defaultMode` | Default [permission mode](iam.md#permission-modes) when opening CodeBuddy Code | `"acceptEdits"` |
+| `disableBypassPermissionsMode` | Set to `"disable"` to prevent activating `bypassPermissions` mode. This disables the `-y` and `--dangerously-skip-permissions` CLI flags | `"disable"` |
+
+### Memory Configuration (Experimental)
+
+Memory allows CodeBuddy Code to maintain persistent memory across sessions, automatically managing project context and learning history.
+
+| Key | Description | Example |
+|:------|:-----|:-----|
+| `enabled` | Whether to enable memory (default: `false`) | `true` |
+| `autoMemoryEnabled` | Whether to enable Auto Memory (default: `true`). Auto Memory allows CodeBuddy to automatically manage persistent cross-session memory, stored in `~/.codebuddy/memories/` | `true` |
+| `typedMemory` | [Experimental] Whether to enable Typed Memory mode (default: `false`). When enabled, uses 4 memory types (user/feedback/project/reference) + YAML frontmatter format | `true` |
+| `teamMemory.enabled` | Whether to enable team memory mode (default: `false`). When enabled, project memories are stored in the project directory for team sharing | `true` |
+| `teamMemory.userId` | Team user ID for isolating different users' memories. Defaults to auto-detection (git user.name > system username) | `"yangsubo"` |
+
+**Configuration example:**
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "autoMemoryEnabled": true,
+    "typedMemory": false,
+    "teamMemory": {
+      "enabled": true,
+      "userId": "yangsubo"
+    }
+  }
+}
+```
+
+**Memory storage locations:**
+
+- **Personal mode** (default): `~/.codebuddy/memories/{project-id}/`
+- **Team mode**: `{project}/.codebuddy/memories/@{user-id}/`
+- **Global memory**: `~/.codebuddy/memories/global/`
+
+This feature can also be enabled via the `/config` command in the settings panel.
+
+### Bash Sandbox Settings
+
+Configure advanced sandbox behavior. The sandbox isolates bash commands from your filesystem and network. See [Bash Sandbox Documentation](bash-sandboxing.md) for details.
+
+**Filesystem and network restrictions** are configured via Read, Edit, and WebFetch permission rules, not through these sandbox settings.
+
+| Key | Description | Example |
+|:------|:-----|:-----|
+| `enabled` | Enable bash sandbox (macOS/Linux only). Default: false | `true` |
+| `autoAllowBashIfSandboxed` | Auto-approve bash commands in sandbox environment. Default: true | `true` |
+| `excludedCommands` | Commands that should run outside the sandbox | `["git", "docker"]` |
+| `allowUnsandboxedCommands` | Allow running commands outside sandbox via `dangerouslyDisableSandbox` parameter. Set to `false` to completely disable |
+| `network.allowUnixSockets` | Unix socket paths accessible in sandbox (for SSH agents, etc.) | `["~/.ssh/agent-socket"]` |
+| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |
+| `network.httpProxyPort` | HTTP proxy port if you want to use your own proxy. If unspecified, CodeBuddy runs its own proxy | `8080` |
+| `network.socksProxyPort` | SOCKS5 proxy port if you want to use your own proxy. If unspecified, CodeBuddy runs its own proxy | `8081` |
+| `enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux only). **Reduces security.** Default: false | `true` |
+
+**Configuration example:**
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true,
+    "excludedCommands": ["docker"],
+    "network": {
+      "allowUnixSockets": [
+        "/var/run/docker.sock"
+      ],
+      "allowLocalBinding": true
+    }
+  },
+  "permissions": {
+    "deny": [
+      "Read(.envrc)",
+      "Read(~/.aws/**)"
+    ]
+  }
+}
+```
+
+**Filesystem access** is controlled via Read/Edit permissions:
+
+* Read deny rules block file reads in sandbox
+* Edit allow rules permit file writes (beyond defaults like the current working directory)
+* Edit deny rules block writes within allowed paths
+
+> **Note**: The sandbox adds CodeBuddy configuration files (`settings.json`, `settings.local.json`) to a write-protection list by default, preventing commands or tools inside the sandbox from tampering with configuration. See [Bash Sandbox - Configuration File Protection](bash-sandboxing.md#configuration-file-protection) for details.
+
+**Network access** is controlled via WebFetch permissions:
+
+* WebFetch allow rules permit network domains
+* WebFetch deny rules block network domains
+
+### Settings Priority
+
+Settings are applied in priority order (highest to lowest):
+
+1. **Command-line arguments**
+   * Temporary overrides for a specific session
+
+2. **Local project settings** (`.codebuddy/settings.local.json`)
+   * Personal project-specific settings
+
+3. **Shared project settings** (`.codebuddy/settings.json`)
+   * Team-shared project settings in source control
+
+4. **User settings** (`~/.codebuddy/settings.json`)
+   * Personal global settings
+
+This hierarchy ensures teams can establish shared standards while still allowing individual customization.
+
+### Configuration System Key Points
+
+* **Memory files (CODEBUDDY.md)**: Contain instructions and context that CodeBuddy loads at startup
+* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior
+* **Slash commands**: Custom commands callable via `/command-name` during sessions
+* **MCP servers**: Extend CodeBuddy Code with additional tools and integrations
+* **Priority**: Higher-level configurations override lower-level ones
+* **Inheritance**: Settings are merged; more specific settings add to or override broader ones
+
+### Excluding Sensitive Files
+
+To prevent CodeBuddy Code from accessing files containing sensitive information (such as API keys, secrets, environment files), use the `permissions.deny` setting in `.codebuddy/settings.json`:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Read(./config/credentials.json)",
+      "Read(./build)"
+    ]
+  }
+}
+```
+
+Files matching these patterns will be completely invisible to CodeBuddy Code, preventing any accidental exposure of sensitive data.
+
+## Sub-Agent Configuration
+
+CodeBuddy Code supports custom AI sub-agents configurable at user and project levels. These sub-agents are stored as Markdown files with YAML frontmatter:
+
+* **User sub-agents**: `~/.codebuddy/agents/` - Available across all projects
+* **Project sub-agents**: `.codebuddy/agents/` - Project-specific, shareable with the team
+
+Sub-agent files define specialized AI assistants with custom prompts and tool permissions. See [Sub-Agents Documentation](sub-agents.md) for details.
+
+## Plugin Configuration
+
+CodeBuddy Code supports a plugin system that allows you to extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at user and project levels.
+
+### Plugin Settings
+
+Plugin-related settings in `settings.json`:
+
+```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`
+
+Controls which plugins are enabled. Format: `"plugin-name@marketplace-name": true/false`
+
+**Scopes**:
+
+* **User settings** (`~/.codebuddy/settings.json`): Personal plugin preferences
+* **Project settings** (`.codebuddy/settings.json`): Project-specific plugins shared with the team
+* **Local settings** (`.codebuddy/settings.local.json`): Per-machine overrides (not committed)
+
+**Example**:
+
+```json
+{
+  "enabledPlugins": {
+    "code-formatter@team-tools": true,
+    "deployment-tools@team-tools": true,
+    "experimental-features@personal": false
+  }
+}
+```
+
+#### `extraKnownMarketplaces`
+
+Defines additional marketplaces that should be available for the project. Typically used in project-level settings to ensure team members can access required plugin sources.
+
+**When a project includes `extraKnownMarketplaces`**:
+
+1. Team members are prompted to install marketplaces when trusting the folder
+2. Team members are then prompted to install plugins from that marketplace
+3. Users can skip unwanted marketplaces or plugins (stored in user settings)
+4. Installation respects trust boundaries and requires explicit consent
+
+**Example**:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": {
+        "source": "github",
+        "repo": "company-org/codebuddy-plugins"
+      }
+    },
+    "security-plugins": {
+      "source": {
+        "source": "git",
+        "url": "https://git.company.com/security/plugins.git"
+      }
+    }
+  }
+}
+```
+
+**Marketplace source types**:
+
+* `github`: GitHub repository (using `repo`)
+* `git`: Any git URL (using `url`)
+* `directory`: Local filesystem path (using `path`, for development only)
+
+### Managing Plugins
+
+Use the `/plugin` command to interactively manage plugins:
+
+* Browse available plugins in marketplaces
+* Install/uninstall plugins
+* Enable/disable plugins
+* View plugin details (provided commands, agents, hooks)
+* Add/remove marketplaces
+
+See [Plugin Documentation](plugins.md) for details.
+
+## Environment Variables
+
+CodeBuddy Code supports environment variables to control its behavior. All environment variables can also be configured in the `env` field of [`settings.json`](#available-settings), which automatically applies them to every session or rolls out configuration for an entire team.
+
+For the complete environment variable reference, see [**Environment Variables Reference**](./env-vars.md).
+
+### Quick Start
+
+**Basic authentication configuration**:
+
+```bash
+# Using API key
+export CODEBUDDY_API_KEY="your-api-key"
+codebuddy
+
+# Or using auth token
+export CODEBUDDY_AUTH_TOKEN="your-token"
+codebuddy
+```
+
+**Setting up proxy**:
+
+```bash
+export HTTPS_PROXY="https://proxy.example.com:8080"
+export NO_PROXY="localhost,127.0.0.1"
+codebuddy
+```
+
+**Enabling advanced features**:
+
+```bash
+# Extended thinking
+export MAX_THINKING_TOKENS="10000"
+
+# Auto memory
+export CODEBUDDY_DISABLE_AUTO_MEMORY="0"
+
+codebuddy -p "your query"
+```
+
+### 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"
+  }
+}
+```
+
+For more configuration examples and advanced usage, see [**Environment Variables Reference**](./env-vars.md) and [**Usage Examples**](./env-vars.md#usage-examples).
+
+## Status Line Configuration
+
+Configure the status line displayed at the bottom of the terminal, which can show current session, model, cost, and other information:
+
+| Key | Type | Description |
+|--------|------|------|
+| `statusLine.type` | string | Status line type, currently supports "command" |
+| `statusLine.command` | string | Command path to execute, supports ~ path expansion |
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "~/.codebuddy/statusline-script.sh"
+  }
+}
+```
+
+The status line command receives JSON data containing session information via stdin, including:
+- `session_id`: Session ID
+- `model`: Current model information
+- `workspace`: Workspace path information
+- `cost`: Cost statistics
+- `version`: Application version
+
+Use the `/statusline` command to quickly configure the status line.
+
+## Configuration Management Commands
+
+Use the `codebuddy config` command to manage configuration:
+
+### Basic Syntax
+```bash
+codebuddy config [command] [options]
+```
+
+### Available Commands
+
+| Command | Syntax | Description |
+|------|------|------|
+| `get` | `codebuddy config get <key>` | Get a configuration value |
+| `set` | `codebuddy config set [options] <key> <value>` | Set a configuration value |
+| `list` | `codebuddy config list` (alias: `ls`) | List all configuration |
+| `add` | `codebuddy config add <key> <values...>` | Add items to an array configuration |
+| `remove` | `codebuddy config remove <key> [values...]` (alias: `rm`) | Remove configuration or array items |
+
+### Options
+
+| Option | Description | Applicable Commands |
+|------|------|----------|
+| `-g, --global` | Set global configuration | `set` |
+
+### Usage Examples
+
+#### Viewing Configuration
+```bash
+# List all configuration
+codebuddy config list
+
+# Get a specific configuration value
+codebuddy config get model
+codebuddy config get permissions
+```
+
+#### Setting Configuration
+```bash
+# Set project-level model (no -g flag needed)
+codebuddy config set model gpt-5
+
+# Set global model (requires -g flag)
+codebuddy config set -g model gpt-4
+
+# Set project-level permission configuration (no -g flag needed)
+codebuddy config set permissions '{"allow": ["Read", "Edit"], "deny": ["Bash(rm:*)"]}'
+
+# Set project-level environment variables (no -g flag needed)
+codebuddy config set env '{"NODE_ENV": "development", "DEBUG": "true"}'
+
+# Set global-only configuration (requires -g flag)
+codebuddy config set -g cleanupPeriodDays 30
+codebuddy config set -g includeCoAuthoredBy false
+```
+
+## Tools Available to CodeBuddy
+
+CodeBuddy Code has access to a powerful set of tools to help it understand and modify your codebase:
+
+| Tool | Description | Requires Permission |
+|:-----|:-----|:---------|
+| **AskUserQuestion** | Ask the user multiple-choice questions to gather information or clarify ambiguities | No |
+| **Bash** | Execute shell commands in your environment | Yes |
+| **TaskOutput** | Retrieve output from running or completed background tasks | No |
+| **Edit** | Make targeted edits to specific files | Yes |
+| **MultiEdit** | Make multiple edits to a single file in one operation | Yes |
+| **ExitPlanMode** | Prompt the user to exit plan mode and begin coding | Yes |
+| **Glob** | Find files using pattern matching | No |
+| **Grep** | Search for patterns in file contents | No |
+| **TaskStop** | Terminate a running background task by ID | No |
+| **LSP** | Interact with LSP servers for code intelligence features (go-to-definition, find references, hover information, etc.) | No |
+| **NotebookEdit** | Modify Jupyter notebook cells | Yes |
+| **Read** | Read file contents | No |
+| **Skill** | Execute a skill in the main conversation | Yes |
+| **SlashCommand** | Run [custom slash commands](slash-commands.md#slashcommand-tool) | Yes |
+| **Task** | Run sub-agents to handle complex multi-step tasks | No |
+| **TaskOutput** | Retrieve output from running or completed background tasks | No |
+| **TaskCreate** | Create tasks to track work progress | No |
+| **TaskUpdate** | Update task status (pending/in_progress/completed) | No |
+| **TaskList** | List current tasks | No |
+| **TaskGet** | Get specific task details | No |
+| **WebFetch** | Fetch content from a specified URL | Yes |
+| **WebSearch** | Perform web search with domain filtering | Yes |
+| **Write** | Create or overwrite files | Yes |
+
+Permission rules can be configured using `/permissions` or in [Permission Settings](#permission-settings). See also [Tool-Specific Permission Rules](iam.md#tool-specific-permission-rules).
+
+### Extending Tools with Hooks
+
+You can use [CodeBuddy Code hooks](hooks.md) to run custom commands before and after any tool execution.
+
+For example, you can automatically run a Python formatter after CodeBuddy modifies Python files, or prevent modifications to production configuration files by blocking Write operations to certain paths.
+
+## Common Configuration Scenarios
+
+### Team Collaboration Configuration
+
+**Shared project configuration** (`.codebuddy/settings.json`):
+```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"
+  }
+}
+```
+
+**Personal local configuration** (`.codebuddy/settings.local.json`):
+```json
+{
+  "model": "gpt-4",
+  "env": {
+    "DEBUG": "myapp:*"
+  }
+}
+```
+
+### Security Configuration
+
+Restrict sensitive operations and file access:
+
+```json
+{
+  "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 Security Configuration
+
+Enable sandbox and configure filesystem and network access:
+
+```json
+{
+  "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)"
+    ]
+  }
+}
+```
+
+## See Also
+
+* [Identity and Access Management](iam.md#configuring-permissions) - Learn about CodeBuddy Code's permission system
+* [Bash Sandbox](bash-sandboxing.md) - Learn about sandbox isolation
+* [Troubleshooting](troubleshooting.md) - Solutions for common configuration issues
+
+---
+
+*The right configuration makes CodeBuddy Code better understand your needs*