vtcode.toml

# VT Code Configuration File
# This file was generated by /settings interactive save.
# Every field includes description, possible values (when known), and default.

[acp]
# Globally enable the ACP bridge
# Default: false
# Type: `boolean`
enabled = true

[acp.zed]
# Enable Zed integration
# Default: false
# Type: `boolean`
enabled = true

# Transport used to communicate with the Zed client
# Default: "stdio"
# Type: `string`
transport = "stdio"

# Desired workspace trust level when running under ACP
# Default: "full_auto"
# Type: `string`
workspace_trust = "full_auto"

[acp.zed.auth]
# Default authentication method for ACP agents Options: "agent" (default - agent handles auth),
# "env_var", "terminal"
# Possible values: agent, env_var, terminal
# Default: "agent"
# Type: `string`
default_method = "agent"


[acp.zed.tools]
# Toggle the list_files function bridge
# Default: true
# Type: `boolean`
list_files = true

# Toggle the read_file function bridge
# Default: true
# Type: `boolean`
read_file = true


[agent]
# Environment variable that stores the API key for the active provider
# Default: "ANTHROPIC_API_KEY"
# Type: `string`
api_key_env = "OLLAMA_API_KEY"

# Enable autonomous mode - auto-approve safe tools with reduced HITL prompts When true, the agent
# operates with fewer confirmation prompts for safe tools.
# Default: false
# Type: `boolean`
autonomous_mode = true

credential_storage_mode = "keyring"

# Default editing mode on startup: "edit" (default) or "plan" Codex-inspired: Encourages structured
# planning before execution.
# Possible values: default
# Default: "edit"
# Type: `string`
default_editing_mode = "edit"

# Default model to use
# Default: "claude-sonnet-4-5"
# Type: `string`
default_model = "gpt-oss:20b-cloud"

# Enable an extra self-review pass to refine final responses
# Default: false
# Type: `boolean`
enable_self_review = false

# Enable split tool results for massive token savings (Phase 4) When enabled, tools return
# dual-channel output: - llm_content: Concise summary sent to LLM (token-optimized, 53-95% reduction)
# - ui_content: Rich output displayed to user (full details preserved) Applies to: grep_file,
# list_files, read_file, run_pty_cmd, write_file, edit_file Default: true (opt-out for compatibility),
# recommended for production use
# Default: true
# Type: `boolean`
enable_split_tool_results = true

# Include current date/time in system prompt for temporal awareness Helps LLM understand context for
# time-sensitive tasks (default: true)
# Default: true
# Type: `boolean`
include_temporal_context = true

# Include current working directory in system prompt (default: true)
# Default: true
# Type: `boolean`
include_working_directory = true

# Additional instruction files or globs to merge into the hierarchy
# Default: []
# Type: `array`
instruction_files = []

# Maximum bytes of instruction content to load from AGENTS.md hierarchy
# Default: 16384
# Type: `integer`
instruction_max_bytes = 16384

# Maximum number of conversation turns before auto-termination
# Default: 150
# Type: `integer`
max_conversation_turns = 193

# Maximum number of self-review passes
# Default: 1
# Type: `integer`
max_review_passes = 1

# Maximum number of retries for agent task execution (default: 2) When an agent task fails due to
# retryable errors (timeout, network, 503, etc.), it will be retried up to this many times with
# exponential backoff
# Default: 2
# Type: `integer`
max_task_retries = 2

# Maximum bytes of AGENTS.md content to load from project hierarchy
# Default: 16384
# Type: `integer`
project_doc_max_bytes = 16384

# AI provider for single agent mode (gemini, openai, anthropic, openrouter, zai)
# Possible values: anthropic, gemini, openai, openrouter, zai
# Default: "anthropic"
# Type: `string`
provider = "ollama"

# Reasoning effort level for models that support it (none, low, medium, high) Applies to: Claude,
# GPT-5, GPT-5.1, Gemini, Qwen3, DeepSeek with reasoning capability
# Possible values: high, low, medium, none
# Default: "medium"
# Type: `string`
reasoning_effort = "low"

# Enable prompt refinement pass before sending to LLM
# Default: false
# Type: `boolean`
refine_prompts_enabled = false

# Max refinement passes for prompt writing
# Default: 1
# Type: `integer`
refine_prompts_max_passes = 1

# Optional model override for the refiner (empty = auto pick efficient sibling)
# Default: ""
# Type: `string`
refine_prompts_model = ""

# Temperature for prompt refinement (0.0-1.0, default: 0.3) Lower values ensure prompt refinement is
# more deterministic/consistent Keep lower than main temperature for stable prompt improvement
# Possible values: 0.0-1.0
# Default: 0.30000001192092896
# Type: `number`
refine_temperature = 0.3

# Require user confirmation before executing a plan generated in plan mode When true, exiting plan
# mode shows the implementation blueprint and requires explicit user approval before enabling edit
# tools.
# Default: true
# Type: `boolean`
require_plan_confirmation = true

# System prompt mode controlling verbosity and token overhead Options: minimal (~500-800 tokens),
# lightweight (~1-2k), default (~6-7k), specialized (~7-8k) Inspired by pi-coding-agent: modern models
# often perform well with minimal prompts
# Default: "default"
# Type: `string`
system_prompt_mode = "default"

# Temperature for main LLM responses (0.0-1.0) Lower values = more deterministic, higher values = more
# creative Recommended: 0.7 for balanced creativity and consistency Range: 0.0 (deterministic) to 1.0
# (maximum randomness)
# Possible values: 0.0-1.0
# Default: 0.699999988079071
# Type: `number`
temperature = 0.7

# Use UTC instead of local time for temporal context in system prompts
# Default: false
# Type: `boolean`
temporal_context_use_utc = false

# UI theme identifier controlling ANSI styling
# Default: "ciapre"
# Type: `string`
theme = "ansi-classic"

# Enable TODO planning helper mode for structured task management
# Default: true
# Type: `boolean`
todo_planning_mode = false

# Tool documentation mode controlling token overhead for tool definitions Options: minimal (~800
# tokens), progressive (~1.2k), full (~3k current) Progressive: signatures upfront, detailed docs
# on-demand (recommended) Minimal: signatures only, pi-coding-agent style (power users) Full: all
# documentation upfront (current behavior, default)
# Default: "full"
# Type: `string`
tool_documentation_mode = "minimal"

# Preferred rendering surface for the interactive chat UI (auto, alternate, inline)
# Possible values: alternate, auto, inline
# Default: "auto"
# Type: `string`
ui_surface = "auto"

# Verbosity level for output text (low, medium, high) Applies to: GPT-5.1 and other models that
# support verbosity control
# Possible values: high, low, medium
# Default: "medium"
# Type: `string`
verbosity = "medium"

[agent.checkpointing]
# Enable automatic checkpoints after each successful turn
# Default: true
# Type: `boolean`
enabled = false

# Maximum age in days before checkpoints are removed automatically (None disables)
# Default: 30
# Type: `integer | null`
max_age_days = 30

# Maximum number of checkpoints to retain on disk
# Default: 50
# Type: `integer`
max_snapshots = 50


[agent.circuit_breaker]
# Enable circuit breaker functionality
# Default: true
# Type: `boolean`
enabled = true

# Number of consecutive failures before opening circuit
# Default: 5
# Type: `integer`
failure_threshold = 5

# Number of open circuits before triggering pause
# Default: 3
# Type: `integer`
max_open_circuits = 3

# Pause and ask user when circuit opens (vs auto-backoff)
# Default: true
# Type: `boolean`
pause_on_open = true

# Cooldown period between recovery prompts (seconds)
# Possible values: seconds
# Default: 60
# Type: `integer`
recovery_cooldown = 60


[agent.harness]
auto_compaction_enabled = false

# Maximum number of tool calls allowed per turn
# Default: 48
# Type: `integer`
max_tool_calls_per_turn = 32

# Maximum retries for retryable tool errors
# Default: 2
# Type: `integer`
max_tool_retries = 2

# Maximum wall clock time (seconds) for tool execution in a turn
# Possible values: seconds
# Default: 600
# Type: `integer`
max_tool_wall_clock_secs = 600


[agent.onboarding]
# Toggle onboarding message rendering
# Default: true
# Type: `boolean`
enabled = true

# Maximum number of guideline bullets to surface
# Default: 3
# Type: `integer`
guideline_highlight_limit = 3

# Whether to include AGENTS.md highlights in onboarding message
# Default: true
# Type: `boolean`
include_guideline_highlights = true

# Whether to include language summary in onboarding message
# Default: false
# Type: `boolean`
include_language_summary = false

# Whether to include project overview in onboarding message
# Default: true
# Type: `boolean`
include_project_overview = true

# Whether to surface suggested actions inside the welcome text banner
# Default: false
# Type: `boolean`
include_recommended_actions_in_welcome = false

# Whether to surface usage tips inside the welcome text banner
# Default: false
# Type: `boolean`
include_usage_tips_in_welcome = false

# Introductory text shown at session start
# Default: "Let's get oriented. I preloaded workspace context so we can move fast."
# Type: `string`
intro_text = "Let's get oriented. I preloaded workspace context so we can move fast."

# Recommended follow-up actions to display
# Default: ["Review the highlighted guidelines and share the task you want to tackle.", "Ask for a workspace tour if you need mo...
# Type: `array`
recommended_actions = [
    "Review the highlighted guidelines and share the task you want to tackle.",
    "Ask for a workspace tour if you need more context.",
]

# Tips for collaborating with the agent effectively
# Default: ["Describe your current coding goal or ask for a quick status overview.", "Reference AGENTS.md guidelines when propos...
# Type: `array`
usage_tips = [
    "Describe your current coding goal or ask for a quick status overview.",
    "Reference AGENTS.md guidelines when proposing changes.",
    "Prefer asking for targeted file reads or diffs before editing.",
]


[agent.open_responses]
# Emit Open Responses events to the event sink When true, streaming events follow Open Responses
# format (response.created, response.output_item.added, response.output_text.delta, etc.)
# Possible values: etc., response.created, response.output_item.added, response.output_text.delta
# Default: true
# Type: `boolean`
emit_events = true

# Enable Open Responses specification compliance layer When true, VT Code emits semantic streaming
# events alongside internal events Default: false (opt-in feature)
# Default: false
# Type: `boolean`
enabled = false

# Include VT Code extension items (vtcode:file_change, vtcode:web_search, etc.) When false, extension
# items are omitted from the Open Responses output
# Possible values: etc.
# Default: true
# Type: `boolean`
include_extensions = true

# Include reasoning items in Open Responses output When true, model reasoning/thinking is exposed as
# reasoning items
# Default: true
# Type: `boolean`
include_reasoning = true

# Map internal tool calls to Open Responses function_call items When true, command executions and MCP
# tool calls are represented as function_call items
# Default: true
# Type: `boolean`
map_tool_calls = true


[agent.small_model]
# Enable small model tier for efficient operations
# Default: true
# Type: `boolean`
enabled = false

# Small model to use (e.g., claude-4-5-haiku, "gpt-4-mini", "gemini-2.0-flash") Leave empty to
# auto-select a lightweight sibling of the main model
# Possible values: claude-4-5-haiku, e.g., gemini-2.0-flash, gpt-4-mini
# Default: ""
# Type: `string`
model = ""

# Temperature for small model responses
# Default: 0.30000001192092896
# Type: `number`
temperature = 0.3

# Enable small model for git history processing
# Default: true
# Type: `boolean`
use_for_git_history = true

# Enable small model for large file reads (>50KB)
# Default: true
# Type: `boolean`
use_for_large_reads = true

# Enable small model for web content summarization
# Default: true
# Type: `boolean`
use_for_web_summary = true


[agent.vibe_coding]
# Enable conversation memory for pronoun resolution
# Default: true
# Type: `boolean`
enable_conversation_memory = true

# Enable fuzzy entity resolution
# Default: true
# Type: `boolean`
enable_entity_resolution = true

# Enable proactive context gathering
# Default: true
# Type: `boolean`
enable_proactive_context = true

# Enable pronoun resolution (it, that, this)
# Possible values: it, that, this
# Default: true
# Type: `boolean`
enable_pronoun_resolution = true

# Enable relative value inference (by half, double, etc.)
# Possible values: double, etc.
# Default: true
# Type: `boolean`
enable_relative_value_inference = true

# Enable vibe coding support
# Default: false
# Type: `boolean`
enabled = false

# Entity index cache file path (relative to workspace)
# Default: ".vtcode/entity_index.json"
# Type: `string`
entity_index_cache = ".vtcode/entity_index.json"

# Maximum files to gather for context (default: 3)
# Default: 3
# Type: `integer`
max_context_files = 3

# Maximum code snippets per file (default: 20 lines)
# Default: 20
# Type: `integer`
max_context_snippets_per_file = 20

# Maximum entity matches to return (default: 5)
# Default: 5
# Type: `integer`
max_entity_matches = 5

# Maximum conversation turns to remember (default: 50)
# Default: 50
# Type: `integer`
max_memory_turns = 50

# Maximum recent files to track (default: 20)
# Default: 20
# Type: `integer`
max_recent_files = 20

# Maximum search results to include (default: 5)
# Default: 5
# Type: `integer`
max_search_results = 5

# Minimum prompt length for refinement (default: 5 chars)
# Default: 5
# Type: `integer`
min_prompt_length = 5

# Minimum prompt words for refinement (default: 2 words)
# Default: 2
# Type: `integer`
min_prompt_words = 2

# Track value history for inference
# Default: true
# Type: `boolean`
track_value_history = true

# Track workspace state (file activity, value changes)
# Default: true
# Type: `boolean`
track_workspace_state = true


[auth]
[auth.openrouter]
# Whether to automatically refresh tokens when they expire. If false, the user will be prompted to
# re-authenticate.
# Default: true
# Type: `boolean`
auto_refresh = true

# Port for the local OAuth callback server. The server listens on localhost for the OAuth redirect.
# Default: 8484
# Type: `integer`
callback_port = 8484

# Timeout in seconds for the OAuth flow. If the user doesn't complete authentication within this time,
# the flow is cancelled.
# Default: 300
# Type: `integer`
flow_timeout_secs = 300

# Whether to use OAuth instead of API key for authentication. When enabled, VT Code will prompt for
# OAuth login if no valid token exists.
# Default: false
# Type: `boolean`
use_oauth = false


[automation]
[automation.full_auto]
# Allow-list of tools that may execute automatically.
# Default: ["read_file", "list_files", "grep_file"]
# Type: `array`
allowed_tools = [
    "read_file",
    "list_files",
    "grep_file",
]

# Enable the runtime flag once the workspace is configured for autonomous runs.
# Default: false
# Type: `boolean`
enabled = true

# Maximum number of autonomous agent turns before the exec runner pauses.
# Default: 30
# Type: `integer`
max_turns = 30

# Require presence of a profile/acknowledgement file before activation.
# Default: true
# Type: `boolean`
require_profile_ack = true


[chat]
[chat.askQuestions]
# Enable the Ask Questions tool in interactive chat
# Default: true
# Type: `boolean`
enabled = true


[commands]
# Glob patterns allowed for shell commands (applies to Bash)
# Default: []
# Type: `array`
allow_glob = [
    "git *",
    "cargo *",
    "rustc *",
    "python *",
    "python3 *",
    "pip *",
    "pip3 *",
    "node *",
    "npm *",
    "npm run *",
    "yarn *",
    "yarn run *",
    "pnpm *",
    "pnpm run *",
    "bun *",
    "bun run *",
    "npx *",
    "go *",
    "gcc *",
    "g++ *",
    "clang *",
    "clang++ *",
    "javac *",
    "java *",
    "mvn *",
    "gradle *",
    "make *",
    "cmake *",
    "ninja *",
    "docker *",
    "docker-compose *",
    "virtualenv *",
    "tar *",
    "zip *",
    "unzip *",
    "gzip *",
    "gunzip *",
]

# Commands that can be executed without prompting
# Default: []
# Type: `array`
allow_list = [
    "ls",
    "pwd",
    "cat",
    "grep",
    "find",
    "head",
    "tail",
    "wc",
    "git status",
    "git diff",
    "git log",
    "git show",
    "git branch",
    "git remote",
    "cargo check",
    "cargo build",
    "cargo build --release",
    "cargo build --profile release",
    "cargo test",
    "cargo run",
    "cargo clippy",
    "cargo fmt",
    "cargo tree",
    "cargo metadata",
    "cargo doc",
    "rustc",
    "which",
    "echo",
    "printf",
    "date",
    "tree",
    "stat",
    "file",
    "sort",
    "uniq",
    "cut",
    "awk",
    "sed",
    "tar",
    "zip",
    "unzip",
    "gzip",
    "gunzip",
    "make",
    "cmake",
    "ninja",
    "python3",
    "python3 -m pip install",
    "python3 -m pytest",
    "python3 -m build",
    "python",
    "pip3",
    "pip",
    "virtualenv",
    "node",
    "npm",
    "npm run build",
    "npm run test",
    "npm install",
    "yarn",
    "yarn build",
    "yarn test",
    "pnpm",
    "pnpm build",
    "pnpm test",
    "bun",
    "bun install",
    "bun run",
    "bun test",
    "npx",
    "go",
    "go build",
    "go test",
    "gcc",
    "g++",
    "clang",
    "clang++",
    "javac",
    "java",
    "mvn",
    "gradle",
    "docker",
    "docker-compose",
]

# Regex allow patterns for shell commands
# Default: []
# Type: `array`
allow_regex = [
    '^(ls|pwd|cat|grep|find|head|tail|wc|echo|printf|date|tree|stat|file|sort|uniq|cut|awk|sed|tar|zip|unzip|gzip|gunzip)\b',
    '^git (status|diff|log|show|branch|remote)\b',
    '^cargo (check|build|test|run|doc|clippy|fmt|tree|metadata)\b',
    '^rustc\b',
    '^(python|python3) (-m | )?\w*',
    '^(pip|pip3)\b',
    '^virtualenv\b',
    '^(node|npm|yarn|pnpm|bun|npx)\b',
    '^go\b',
    '^(gcc|g\+\+|clang|clang\++)\b',
    '^(javac|java)\b',
    '^(mvn|gradle)\b',
    '^(make|cmake)\b',
    '^(docker|docker-compose)\b',
]

# Glob patterns denied for shell commands
# Default: []
# Type: `array`
deny_glob = [
    "rm *",
    "sudo *",
    "chmod *",
    "chown *",
    "kill *",
    "pkill *",
    "systemctl *",
    "service *",
    "mount *",
    "umount *",
    "docker run *",
    "kubectl *",
]

# Commands that are always denied
# Default: []
# Type: `array`
deny_list = [
    "rm",
    "rm -rf /",
    "rm -rf ~",
    "rm -rf /*",
    "rm -rf /home",
    "rm -rf /usr",
    "rm -rf /etc",
    "rm -rf /var",
    "rm -rf /opt",
    "rmdir /",
    "rmdir /home",
    "rmdir /usr",
    "shutdown",
    "reboot",
    "halt",
    "poweroff",
    "init 0",
    "init 6",
    "systemctl poweroff",
    "systemctl reboot",
    "systemctl halt",
    "sudo rm",
    "sudo chmod 777",
    "sudo chown",
    "sudo passwd",
    "sudo su",
    "sudo -i",
    "sudo bash",
    "su root",
    "su -",
    "format",
    "fdisk",
    "mkfs",
    "mkfs.ext4",
    "mkfs.xfs",
    "mkfs.vfat",
    "dd if=/dev/zero",
    "dd if=/dev/random",
    "dd if=/dev/urandom",
    "wget --no-check-certificate",
    ":(){ :|:& };:",
    "nohup bash -i",
    "exec bash -i",
    "eval",
    "source /etc/bashrc",
    "source ~/.bashrc",
    "chmod 777",
    "chmod -R 777",
    "chown -R",
    "chgrp -R",
    "rm ~/.ssh/*",
    "rm -r ~/.ssh",
    "cat /etc/passwd",
    "cat /etc/shadow",
    "cat ~/.ssh/id_*",
    "tail -f /var/log",
    "head -n 1 /var/log",
]

# Regex deny patterns for shell commands
# Default: []
# Type: `array`
deny_regex = [
    'rm\s+(-rf|--force)',
    'sudo\s+.*',
    'chmod\s+.*',
    'chown\s+.*',
    'docker\s+run\s+.*--privileged',
    'kubectl\s+(delete|drain|uncordon)',
]

# Additional directories that should be searched/prepended to PATH for command execution
# Default: ["$HOME/.cargo/bin", "$HOME/.local/bin", "/opt/homebrew/bin", "/usr/local/bin", "$HOME/.asdf/bin", "$HOME/.asdf/shims...
# Type: `array`
extra_path_entries = [
    "$HOME/.cargo/bin",
    "$HOME/.local/bin",
    "/opt/homebrew/bin",
    "/usr/local/bin",
    "$HOME/.asdf/bin",
    "$HOME/.asdf/shims",
    "$HOME/go/bin",
]


[context]
# Maximum tokens to keep in context (affects model cost and performance) Higher values preserve more
# context but cost more and may hit token limits This field is maintained for compatibility but no
# longer used for trimming
# Default: 90000
# Type: `integer`
max_context_tokens = 130048

# Preserve recent turns during context management This field is maintained for compatibility but no
# longer used for trimming
# Default: 10
# Type: `integer`
preserve_recent_turns = 10

# Percentage to trim context to when it gets too large This field is maintained for compatibility but
# no longer used for trimming
# Default: 60
# Type: `integer`
trim_to_percent = 90

[context.dynamic]
# Enable dynamic context discovery features
# Default: true
# Type: `boolean`
enabled = true

# Maximum number of spooled files to keep
# Default: 100
# Type: `integer`
max_spooled_files = 100

# Enable persisting conversation history during summarization
# Default: true
# Type: `boolean`
persist_history = true

# Maximum age in seconds for spooled tool output files before cleanup
# Default: 3600
# Type: `integer`
spool_max_age_secs = 3600

# Enable syncing MCP tool descriptions to .vtcode/mcp/tools/
# Default: true
# Type: `boolean`
sync_mcp_tools = true

# Enable generating skill index in .agents/skills/INDEX.md
# Default: true
# Type: `boolean`
sync_skills = true

# Enable syncing terminal sessions to .vtcode/terminals/ files
# Default: true
# Type: `boolean`
sync_terminals = true

# Threshold in bytes above which tool outputs are spooled to files
# Default: 8192
# Type: `integer`
tool_output_threshold = 8192


[context.ledger]
# -
# Default: true
# Type: `boolean`
enabled = true

# Inject ledger into the system prompt each turn
# Default: true
# Type: `boolean`
include_in_prompt = true

# -
# Default: 12
# Type: `integer`
max_entries = 12

# Preserve ledger entries during context compression
# Default: true
# Type: `boolean`
preserve_in_compression = true


[debug]
# Enable structured logging for development and troubleshooting
# Default: false
# Type: `boolean`
enable_tracing = true

# Maximum age of debug logs to keep (in days)
# Default: 7
# Type: `integer`
max_debug_log_age_days = 7

# Maximum size of debug logs before rotating (in MB)
# Default: 50
# Type: `integer`
max_debug_log_size_mb = 50

# Trace level (error, warn, info, debug, trace)
# Possible values: debug, error, info, trace, warn
# Default: "info"
# Type: `string`
trace_level = "error"

# List of tracing targets to enable Examples: "vtcode_core::agent", "vtcode_core::tools", "vtcode::*"
# Default: []
# Type: `array`
trace_targets = []


[dotfile_protection]
# Additional dotfile patterns to protect (beyond defaults).
# Default: []
# Type: `array`
additional_protected_patterns = []

# Path to the audit log file.
# Default: "~/.vtcode/dotfile_audit.log"
# Type: `string`
audit_log_path = "~/.vtcode/dotfile_audit.log"

# Enable immutable audit logging of all dotfile access attempts.
# Default: true
# Type: `boolean`
audit_logging_enabled = true

# Directory for storing dotfile backups.
# Default: "~/.vtcode/dotfile_backups"
# Type: `string`
backup_directory = "~/.vtcode/dotfile_backups"

# Block modifications during automated operations.
# Default: true
# Type: `boolean`
block_during_automation = true

# Operations that trigger extra protection.
# Default: ["dependency_installation", "code_formatting", "git_operations", "project_initialization", "build_operations", "test_...
# Type: `array`
blocked_operations = [
    "dependency_installation",
    "code_formatting",
    "git_operations",
    "project_initialization",
    "build_operations",
    "test_execution",
    "linting",
    "auto_fix",
]

# Create backup before any permitted modification.
# Default: true
# Type: `boolean`
create_backups = true

# Enable dotfile protection globally.
# Default: true
# Type: `boolean`
enabled = true

# Maximum number of backups to retain per file.
# Default: 10
# Type: `integer`
max_backups_per_file = 10

# Preserve original file permissions and ownership.
# Default: true
# Type: `boolean`
preserve_permissions = true

# Prevent cascading modifications (one dotfile change triggering others).
# Default: true
# Type: `boolean`
prevent_cascading_modifications = true

# Require explicit user confirmation for any dotfile modification.
# Default: true
# Type: `boolean`
require_explicit_confirmation = true

# Secondary authentication required for whitelisted files.
# Default: true
# Type: `boolean`
require_secondary_auth_for_whitelist = true

# Whitelisted dotfiles that can be modified (after secondary confirmation).
# Default: []
# Type: `array`
whitelist = []


[hooks]
[hooks.lifecycle]
# Commands to run immediately after a tool returns its output
# Default: []
# Type: `array`
post_tool_use = []

# Commands to run immediately before a tool is executed
# Default: []
# Type: `array`
pre_tool_use = []

# Commands to run when an agent session ends
# Default: []
# Type: `array`
session_end = []

# Commands to run immediately when an agent session begins
# Default: []
# Type: `array`
session_start = []

# Commands to run after a task is finalized and session is closed
# Default: []
# Type: `array`
task_completed = []

# Commands to run when the agent indicates task completion (pre-exit)
# Possible values: pre-exit
# Default: []
# Type: `array`
task_completion = []

# Commands to run when the user submits a prompt (pre-processing)
# Possible values: pre-processing
# Default: []
# Type: `array`
user_prompt_submit = []


[mcp]
# Enable connection pooling for better performance
# Default: true
# Type: `boolean`
connection_pooling_enabled = true

# Connection timeout in seconds
# Default: 30
# Type: `integer`
connection_timeout_seconds = 30

# Enable MCP functionality
# Default: false
# Type: `boolean`
enabled = true

# Toggle experimental RMCP client features
# Default: true
# Type: `boolean`
experimental_use_rmcp_client = true

# Maximum number of concurrent MCP connections
# Default: 5
# Type: `integer`
max_concurrent_connections = 5

# Configured MCP providers
# Default: []
# Type: `array`
providers = []

# Request timeout in seconds
# Default: 30
# Type: `integer`
request_timeout_seconds = 30

# Connection retry attempts
# Default: 3
# Type: `integer`
retry_attempts = 3

# Cache capacity for tool discovery results
# Default: 100
# Type: `integer`
tool_cache_capacity = 100

[mcp.allowlist]
# Whether to enforce allow list checks
# Default: false
# Type: `boolean`
enforce = false

[mcp.allowlist.default]

# Provider-specific allow list rules
# Default: {}
[mcp.allowlist.providers]

[mcp.security]
# Enable authentication for MCP server
# Default: false
# Type: `boolean`
auth_enabled = false

[mcp.security.rate_limit]
# Maximum concurrent requests per client
# Default: 10
# Type: `integer`
concurrent_requests = 10

# Maximum requests per minute per client
# Default: 100
# Type: `integer`
requests_per_minute = 100


[mcp.security.validation]
# Maximum argument size in bytes
# Default: 1048576
# Type: `integer`
max_argument_size = 1048576

# Enable path traversal protection
# Default: true
# Type: `boolean`
path_traversal_protection = true

# Enable JSON schema validation for tool arguments
# Default: true
# Type: `boolean`
schema_validation_enabled = true


[mcp.server]
# Bind address for the MCP server
# Default: "127.0.0.1"
# Type: `string`
bind_address = "127.0.0.1"

# Enable vtcode's MCP server capability
# Default: false
# Type: `boolean`
enabled = false

# Tools exposed by the vtcode MCP server
# Default: []
# Type: `array`
exposed_tools = []

# Server identifier
# Default: "vtcode-mcp-server"
# Type: `string`
name = "vtcode-mcp-server"

# Port for the MCP server
# Default: 3000
# Type: `integer`
port = 3000

# Server transport type
# Default: "sse"
# Type: `string`
transport = "sse"

# Server version
# Default: "0.79.4"
# Type: `string`
version = "0.72.2"


[mcp.ui]
# Maximum number of MCP events to display
# Default: 50
# Type: `integer`
max_events = 50

# UI mode for MCP events: "compact" or "full"
# Default: "compact"
# Type: `string`
mode = "compact"

# Show MCP provider names in UI
# Default: true
# Type: `boolean`
show_provider_names = true

# Custom renderer profiles for provider-specific output formatting
# Default: {}
[mcp.ui.renderers]

[model]
# Enable interactive prompt for loop detection instead of silently halting
# Default: true
# Type: `boolean`
loop_detection_interactive = true

# Maximum number of identical tool calls (same tool + same arguments) before triggering loop detection
# Default: 2
# Type: `integer`
loop_detection_threshold = 2

# Enable loop hang detection to identify when model is stuck in repetitive behavior
# Default: false
# Type: `boolean`
skip_loop_detection = false


[optimization]
[optimization.agent_execution]
# Enable performance prediction
# Default: -
# Type: `boolean`
enable_performance_prediction = false

# Back-off duration in milliseconds when no work is pending This reduces CPU usage during idle periods
# Default: -
# Type: `integer`
idle_backoff_ms = 100

# Idle detection timeout in milliseconds (0 to disable) When the agent is idle for this duration, it
# will enter a low-power state
# Default: -
# Type: `integer`
idle_timeout_ms = 5000

# Maximum execution time in seconds
# Default: -
# Type: `integer`
max_execution_time_secs = 300

# Maximum consecutive idle cycles before entering deep sleep
# Default: -
# Type: `integer`
max_idle_cycles = 10

# Maximum memory usage in MB
# Default: -
# Type: `integer`
max_memory_mb = 1024

# Resource monitoring interval in milliseconds
# Default: -
# Type: `integer`
resource_monitor_interval_ms = 100

# State transition history size
# Default: -
# Type: `integer`
state_history_size = 1000

# Enable optimized agent execution loop
# Default: -
# Type: `boolean`
use_optimized_loop = false


[optimization.async_pipeline]
# Batch timeout in milliseconds
# Default: -
# Type: `integer`
batch_timeout_ms = 100

# Result cache size
# Default: -
# Type: `integer`
cache_size = 100

# Enable request batching
# Default: -
# Type: `boolean`
enable_batching = false

# Enable result caching
# Default: -
# Type: `boolean`
enable_caching = true

# Maximum batch size for tool requests
# Default: -
# Type: `integer`
max_batch_size = 5


[optimization.command_cache]
# Allowlist of command prefixes eligible for caching
# Default: -
# Type: `array`
allowlist = [
    "rg",
    "ls",
    "git status",
    "git diff --stat",
]

# Enable command caching
# Default: -
# Type: `boolean`
enabled = true

# Maximum number of cached entries
# Default: -
# Type: `integer`
max_entries = 128

# Cache TTL in milliseconds
# Default: -
# Type: `integer`
ttl_ms = 2000


[optimization.file_read_cache]
# Enable file read caching
# Default: -
# Type: `boolean`
enabled = true

# Maximum number of cached entries
# Default: -
# Type: `integer`
max_entries = 128

# Maximum cached file size (bytes)
# Possible values: bytes
# Default: -
# Type: `integer`
max_size_bytes = 10485760

# Minimum file size (bytes) before caching
# Possible values: bytes
# Default: -
# Type: `integer`
min_size_bytes = 262144

# Cache TTL in seconds
# Default: -
# Type: `integer`
ttl_secs = 300


[optimization.llm_client]
# Response cache TTL in seconds
# Default: -
# Type: `integer`
cache_ttl_secs = 300

# Connection pool size
# Default: -
# Type: `integer`
connection_pool_size = 4

# Enable connection pooling
# Default: -
# Type: `boolean`
enable_connection_pooling = false

# Enable request batching
# Default: -
# Type: `boolean`
enable_request_batching = false

# Enable response caching
# Default: -
# Type: `boolean`
enable_response_caching = true

# Rate limit burst capacity
# Default: -
# Type: `integer`
rate_limit_burst = 20

# Rate limit: requests per second
# Default: -
# Type: `number`
rate_limit_rps = 10.0

# Response cache size
# Default: -
# Type: `integer`
response_cache_size = 50


[optimization.memory_pool]
# Enable memory pool (can be disabled for debugging)
# Default: -
# Type: `boolean`
enabled = true

# Maximum number of strings to pool
# Default: -
# Type: `integer`
max_string_pool_size = 64

# Maximum number of Values to pool
# Default: -
# Type: `integer`
max_value_pool_size = 32

# Maximum number of Vec<String> to pool
# Default: -
# Type: `integer`
max_vec_pool_size = 16


[optimization.profiling]
# Auto-export results to file
# Default: -
# Type: `boolean`
auto_export_results = false

# Enable regression testing
# Default: -
# Type: `boolean`
enable_regression_testing = false

# Enable performance profiling
# Default: -
# Type: `boolean`
enabled = false

# Export file path
# Default: -
# Type: `string`
export_file_path = "benchmark_results.json"

# Maximum benchmark history size
# Default: -
# Type: `integer`
max_history_size = 1000

# Maximum allowed performance regression percentage
# Default: -
# Type: `number`
max_regression_percent = 10.0

# Resource monitoring interval in milliseconds
# Default: -
# Type: `integer`
monitor_interval_ms = 100


[optimization.tool_registry]
# Tool execution timeout in seconds
# Default: -
# Type: `integer`
default_timeout_secs = 180

# Hot cache size for frequently used tools
# Default: -
# Type: `integer`
hot_cache_size = 16

# Maximum concurrent tool executions
# Default: -
# Type: `integer`
max_concurrent_tools = 4

# Enable optimized registry
# Default: -
# Type: `boolean`
use_optimized_registry = false


[output_style]
# -
# Default: "default"
# Type: `string`
active_style = "default"


[permissions]
# Directory for audit logs (created if not exists) Defaults to ~/.vtcode/audit
# Default: "~/.vtcode/audit"
# Type: `string`
audit_directory = "~/.vtcode/audit"

# Enable audit logging of all permission decisions
# Default: true
# Type: `boolean`
audit_enabled = true

# Enable permission decision caching to avoid redundant evaluations
# Default: true
# Type: `boolean`
cache_enabled = true

# Cache time-to-live in seconds (how long to cache decisions) Default: 300 seconds (5 minutes)
# Default: 300
# Type: `integer`
cache_ttl_seconds = 300

# Enable the enhanced permission system (resolver + audit logger + cache)
# Default: true
# Type: `boolean`
enabled = true

# Log allowed commands to audit trail
# Default: true
# Type: `boolean`
log_allowed_commands = true

# Log denied commands to audit trail
# Default: true
# Type: `boolean`
log_denied_commands = true

# Log permission prompts (when user is asked for confirmation)
# Default: true
# Type: `boolean`
log_permission_prompts = true

# Enable command resolution to actual paths (helps identify suspicious commands)
# Default: true
# Type: `boolean`
resolve_commands = true


[prompt_cache]
# Base directory for local prompt cache storage (supports `~` expansion)
# Default: "~/.vtcode/cache/prompts"
# Type: `string`
cache_dir = "~/.vtcode/cache/prompts"

# Automatically evict stale entries on startup/shutdown
# Default: true
# Type: `boolean`
enable_auto_cleanup = true

# Enable prompt caching features globally
# Default: true
# Type: `boolean`
enabled = false

# Maximum age (in days) before cached entries are purged
# Default: 30
# Type: `integer`
max_age_days = 30

# Maximum number of cached prompt entries to retain on disk
# Default: 1000
# Type: `integer`
max_entries = 1000

# Minimum quality score required before persisting an entry
# Default: 0.7
# Type: `number`
min_quality_threshold = 0.7
cache_friendly_prompt_shaping = false

[prompt_cache.providers]
[prompt_cache.providers.anthropic]
# Apply cache control to system prompts by default
# Default: true
# Type: `boolean`
cache_system_messages = true

# Apply cache control to tool definitions by default Default: true (tools are typically stable and
# benefit from longer caching)
# Default: true
# Type: `boolean`
cache_tool_definitions = true

# Apply cache control to user messages exceeding threshold
# Default: true
# Type: `boolean`
cache_user_messages = true

# -
# Default: true
# Type: `boolean`
enabled = true

# Extended TTL for Anthropic prompt caching (in seconds) Set to >= 3600 for 1-hour cache on messages
# Default: 3600
# Type: `integer | null`
extended_ttl_seconds = 3600

# Maximum number of cache breakpoints to use (max 4 per Anthropic spec). Default: 4
# Default: 4
# Type: `integer`
max_breakpoints = 4

# TTL for subsequent cache breakpoints (messages). Set to >= 3600 for 1-hour cache on messages.
# Default: 300 (5 minutes) - recommended for frequently changing messages
# Possible values: messages
# Default: 300
# Type: `integer`
messages_ttl_seconds = 300

# Minimum message length (in characters) before applying cache control to avoid caching very short
# messages that don't benefit from caching. Default: 256 characters (~64 tokens)
# Default: 256
# Type: `integer`
min_message_length_for_cache = 256

# Default TTL in seconds for the first cache breakpoint (tools/system). Anthropic only supports "5m"
# (300s) or "1h" (3600s) TTL formats. Set to >= 3600 for 1-hour cache on tools and system prompts.
# Default: 3600 (1 hour) - recommended for stable tool definitions
# Possible values: tools/system
# Default: 3600
# Type: `integer`
tools_ttl_seconds = 3600


[prompt_cache.providers.deepseek]
# -
# Default: true
# Type: `boolean`
enabled = true

# Emit cache hit/miss metrics from responses when available
# Default: true
# Type: `boolean`
surface_metrics = true


[prompt_cache.providers.gemini]
# -
# Default: true
# Type: `boolean`
enabled = true

# TTL for explicit caches (ignored in implicit mode)
# Default: 3600
# Type: `integer | null`
explicit_ttl_seconds = 3600

# -
# Default: 1024
# Type: `integer`
min_prefix_tokens = 1024

# Gemini prompt caching mode selection
# Default: "implicit"
# Type: `string`
mode = "implicit"


[prompt_cache.providers.moonshot]
# -
# Default: true
# Type: `boolean`
enabled = true


[prompt_cache.providers.openai]
# -
# Default: true
# Type: `boolean`
enabled = true

# -
# Default: 3600
# Type: `integer`
idle_expiration_seconds = 3600

# -
# Default: 1024
# Type: `integer`
min_prefix_tokens = 1024

prompt_cache_key_mode = "session"

# -
# Default: true
# Type: `boolean`
surface_metrics = true


[prompt_cache.providers.openrouter]
# -
# Default: true
# Type: `boolean`
enabled = true

# Propagate provider cache instructions automatically
# Default: true
# Type: `boolean`
propagate_provider_capabilities = true

# Surface cache savings reported by OpenRouter
# Default: true
# Type: `boolean`
report_savings = true


[prompt_cache.providers.zai]
# -
# Default: false
# Type: `boolean`
enabled = false


[provider]
[provider.anthropic]
# Enable token counting via the count_tokens endpoint When enabled, the agent can estimate input token
# counts before making API calls Useful for proactive management of rate limits and costs
# Default: false
# Type: `boolean`
count_tokens_enabled = false

# Effort level for token usage (high, medium, low) Controls how many tokens Claude uses when
# responding, trading off between response thoroughness and token efficiency. Supported by Claude Opus
# 4.5/4.6 (4.5 requires effort beta header)
# Possible values: high, low, medium
# Default: "low"
# Type: `string`
effort = "low"

# Enable extended thinking feature for Anthropic models When enabled, Claude uses internal reasoning
# before responding, providing enhanced reasoning capabilities for complex tasks. Only supported by
# Claude 4, Claude 4.5, and Claude 3.7 Sonnet models. Claude 4.6 uses adaptive thinking instead of
# extended thinking. Note: Extended thinking is now auto-enabled by default (31,999 tokens). Set
# MAX_THINKING_TOKENS=63999 environment variable for 2x budget on 64K models. See:
# https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking
# Possible values: 31
# Default: true
# Type: `boolean`
extended_thinking_enabled = true

# Beta header for interleaved thinking feature
# Default: "interleaved-thinking-2025-05-14"
# Type: `string`
interleaved_thinking_beta = "interleaved-thinking-2025-05-14"

# Budget tokens for extended thinking (minimum: 1024, default: 31999) On 64K output models (Opus 4.5,
# Sonnet 4.5, Haiku 4.5): default 31,999, max 63,999 On 32K output models (Opus 4): max 31,999 Use
# MAX_THINKING_TOKENS environment variable to override.
# Default: 31999
# Type: `integer`
interleaved_thinking_budget_tokens = 31999

# Type value for enabling interleaved thinking
# Default: "enabled"
# Type: `string`
interleaved_thinking_type_enabled = "enabled"

# DEPRECATED: Model name validation has been removed. The Anthropic API validates model names
# directly, avoiding maintenance burden and allowing flexibility. This field is kept for backward
# compatibility but has no effect.
# Default: false
# Type: `boolean`
skip_model_validation = false

[provider.anthropic.tool_search]
# Search algorithm: "regex" (Python regex patterns) or "bm25" (natural language)
# Default: "regex"
# Type: `string`
algorithm = "regex"

# Tool names that should never be deferred (always available)
# Default: []
# Type: `array`
always_available_tools = []

# Automatically defer loading of all tools except core tools
# Default: true
# Type: `boolean`
defer_by_default = true

# Enable tool search feature (requires advanced-tool-use-2025-11-20 beta)
# Default: false
# Type: `boolean`
enabled = false

# Maximum number of tool search results to return
# Default: 5
# Type: `integer`
max_results = 5


[provider.openai]
websocket_mode = false


[pty]
# Command timeout in seconds (prevents hanging commands)
# Default: 300
# Type: `integer`
command_timeout_seconds = 3600

# Default terminal columns for PTY sessions
# Default: 80
# Type: `integer`
default_cols = 120

# Default terminal rows for PTY sessions
# Default: 24
# Type: `integer`
default_rows = 24

# Enable PTY support for interactive commands
# Default: true
# Type: `boolean`
enabled = true

# Threshold (KB) at which to auto-spool large outputs to disk instead of memory
# Possible values: KB
# Default: 5000
# Type: `integer`
large_output_threshold_kb = 5000

# Maximum bytes of output to retain per PTY session (prevents memory explosion)
# Default: 25000000
# Type: `integer`
max_scrollback_bytes = 25000000

# Maximum number of concurrent PTY sessions
# Default: 10
# Type: `integer`
max_sessions = 10

# Total scrollback buffer size (lines) retained per PTY session
# Possible values: lines
# Default: 400
# Type: `integer`
scrollback_lines = 400

shell_zsh_fork = false

# Number of recent PTY output lines to display in the chat transcript
# Default: 20
# Type: `integer`
stdout_tail_lines = 20


[sandbox]
# Default sandbox mode
# Default: "read_only"
# Type: `string`
default_mode = "read_only"

# Enable sandboxing for command execution
# Default: true
# Type: `boolean`
enabled = false

[sandbox.external]
# Type of external sandbox
# Default: "none"
# Type: `string`
sandbox_type = "none"

[sandbox.external.docker]
# CPU limit for container
# Default: ""
# Type: `string`
cpu_limit = ""

# Docker image to use
# Default: "ubuntu:22.04"
# Type: `string`
image = "ubuntu:22.04"

# Memory limit for container
# Default: ""
# Type: `string`
memory_limit = ""

# Network mode
# Default: "none"
# Type: `string`
network_mode = "none"


[sandbox.external.microvm]
# Kernel image path
# Default: ""
# Type: `string`
kernel_path = ""

# Memory size in MB
# Default: 512
# Type: `integer`
memory_mb = 512

# Root filesystem path
# Default: ""
# Type: `string`
rootfs_path = ""

# Number of vCPUs
# Default: 1
# Type: `integer`
vcpus = 1

# VMM to use (firecracker, cloud-hypervisor)
# Possible values: cloud-hypervisor, firecracker
# Default: ""
# Type: `string`
vmm = ""


[sandbox.network]
# Allow any network access (legacy mode)
# Default: false
# Type: `boolean`
allow_all = false

# Domain allowlist for network egress Following field guide: "Default-deny outbound network, then
# allowlist."
# Default: []
# Type: `array`
allowlist = []

# Block all network access (overrides allowlist)
# Default: false
# Type: `boolean`
block_all = false


[sandbox.resource_limits]
# Custom CPU time limit in seconds (0 = use preset)
# Default: 0
# Type: `integer`
cpu_time_secs = 0

# Custom disk write limit in MB (0 = use preset)
# Default: 0
# Type: `integer`
max_disk_mb = 0

# Custom memory limit in MB (0 = use preset)
# Default: 0
# Type: `integer`
max_memory_mb = 0

# Custom max processes (0 = use preset)
# Default: 0
# Type: `integer`
max_pids = 0

# Preset resource limits profile
# Default: "moderate"
# Type: `string`
preset = "moderate"

# Custom wall clock timeout in seconds (0 = use preset)
# Default: 0
# Type: `integer`
timeout_secs = 0


[sandbox.seccomp]
# Additional syscalls to block
# Default: []
# Type: `array`
additional_blocked = []

# Enable seccomp filtering (Linux only)
# Default: true
# Type: `boolean`
enabled = true

# Log blocked syscalls instead of killing process (for debugging)
# Default: false
# Type: `boolean`
log_only = false

# Seccomp profile preset
# Default: "strict"
# Type: `string`
profile = "strict"


[sandbox.sensitive_paths]
# Additional paths to block
# Default: []
# Type: `array`
additional = []

# Paths to explicitly allow (overrides defaults)
# Default: []
# Type: `array`
exceptions = []

# Use default sensitive paths (SSH, AWS, etc.)
# Possible values: AWS, SSH, etc.
# Default: true
# Type: `boolean`
use_defaults = true


[security]
# Automatically apply detected patch blocks in assistant replies when no write tool was executed.
# Defaults to false for safety.
# Default: false
# Type: `boolean`
auto_apply_detected_patches = false

# Encrypt payloads passed across executors.
# Default: false
# Type: `boolean`
encrypt_payloads = false

# Play terminal bell notification when HITL approval is required.
# Default: true
# Type: `boolean`
hitl_notification_bell = true

# Require human confirmation for critical actions
# Default: true
# Type: `boolean`
human_in_the_loop = true

# Enable runtime integrity tagging for critical paths.
# Default: true
# Type: `boolean`
integrity_checks = true

# Require a successful write tool before accepting claims like "I've updated the file" as applied.
# When true, such claims are treated as proposals unless a write tool executed successfully.
# Default: true
# Type: `boolean`
require_write_tool_for_claims = true

# Enable zero-trust checks between components.
# Default: false
# Type: `boolean`
zero_trust_mode = false

[security.gatekeeper]
# Paths eligible for quarantine auto-clear
# Default: [".vtcode/bin", "~/.vtcode/bin"]
# Type: `array`
auto_clear_paths = [
    ".vtcode/bin",
    "~/.vtcode/bin",
]

# Attempt to clear quarantine automatically (opt-in)
# Possible values: opt-in
# Default: false
# Type: `boolean`
auto_clear_quarantine = false

# Warn when a quarantined executable is detected
# Default: true
# Type: `boolean`
warn_on_quarantine = true


[skills]
# Enable auto-trigger on $skill-name mentions
# Default: true
# Type: `boolean`
enable-auto-trigger = true

# Enable description-based keyword matching for auto-trigger
# Default: true
# Type: `boolean`
enable-description-matching = true

# Maximum number of skills to show in system prompt
# Default: 10
# Type: `integer`
max-skills-in-prompt = 10

# Minimum keyword matches required for description-based trigger
# Default: 2
# Type: `integer`
min-keyword-matches = 2

# Prompt format for skills section (Agent Skills spec) - "xml": XML wrapping for safety (Claude models
# default) - "markdown": Plain markdown sections
# Default: "xml"
# Type: `string`
prompt-format = "xml"

# Rendering mode for skills in system prompt - "lean": Codex-style minimal (name + description + path
# only, 40-60% token savings) - "full": Full metadata with version, author, native flags
# Default: "lean"
# Type: `string`
render-mode = "lean"


[syntax_highlighting]
# Enable theme caching for better performance
# Default: true
# Type: `boolean`
cache_themes = true

# Enable syntax highlighting for tool output
# Default: true
# Type: `boolean`
enabled = true

# Languages to enable syntax highlighting for
# Default: ["rust", "python", "javascript", "typescript", "go", "java", "cpp", "c", "php", "html", "css", "sql", "csharp", "bash...
# Type: `array`
enabled_languages = [
    "rust",
    "python",
    "javascript",
    "typescript",
    "go",
    "java",
    "cpp",
    "c",
    "php",
    "html",
    "css",
    "sql",
    "csharp",
    "bash",
    "swift",
]

# Performance settings - highlight timeout in milliseconds
# Default: 5000
# Type: `integer`
highlight_timeout_ms = 5000

# Maximum file size for syntax highlighting (in MB)
# Default: 10
# Type: `integer`
max_file_size_mb = 10

# Theme to use for syntax highlighting
# Default: "base16-ocean.dark"
# Type: `string`
theme = "base16-ocean.dark"


[telemetry]
# Emit bottleneck traces for slow paths
# Default: false
# Type: `boolean`
bottleneck_tracing = true

# Enable real-time dashboards
# Default: true
# Type: `boolean`
dashboards_enabled = true

# Emit performance events for file I/O, spawns, and UI latency
# Default: true
# Type: `boolean`
perf_events = true

# Retention window for historical benchmarking (days)
# Possible values: days
# Default: 14
# Type: `integer`
retention_days = 14

# KPI sampling interval in milliseconds
# Default: 1000
# Type: `integer`
sample_interval_ms = 1000

# -
# Default: true
# Type: `boolean`
trajectory_enabled = true


[timeouts]
# Adaptive timeout decay ratio (0.1-1.0). Lower relaxes faster back to ceiling.
# Possible values: 0.1-1.0
# Default: 0.875
# Type: `number`
adaptive_decay_ratio = 0.875

# Minimum timeout floor in milliseconds when applying adaptive clamps.
# Default: 1000
# Type: `integer`
adaptive_min_floor_ms = 1000

# Number of consecutive successes before relaxing adaptive ceiling.
# Default: 5
# Type: `integer`
adaptive_success_streak = 5

# Maximum duration (in seconds) for standard, non-PTY tools.
# Default: 180
# Type: `integer`
default_ceiling_seconds = 180

# Maximum duration (in seconds) for MCP calls.
# Default: 120
# Type: `integer`
mcp_ceiling_seconds = 120

# Maximum duration (in seconds) for PTY-backed commands.
# Default: 300
# Type: `integer`
pty_ceiling_seconds = 300

# Maximum duration (in seconds) for streaming API responses.
# Default: 600
# Type: `integer`
streaming_ceiling_seconds = 600

# Percentage (0-100) of the ceiling after which the UI should warn.
# Possible values: 0-100
# Default: 80
# Type: `integer`
warning_threshold_percent = 80


[tools]
# Default policy for tools not explicitly listed
# Default: "prompt"
# Type: `string`
default_policy = "allow"

max_consecutive_blocked_tool_calls_per_turn = 8

# Maximum number of times the same tool invocation can be retried with the identical arguments within
# a single turn.
# Default: 3
# Type: `integer`
max_repeated_tool_calls = 2

max_sequential_spool_chunk_reads = 6

# Maximum inner tool-call loops per user turn Prevents infinite tool-calling cycles in interactive
# chat. This limits how many back-and-forths the agent will perform executing tools and re-asking the
# model before returning a final answer.
# Default: 200
# Type: `integer`
max_tool_loops = 20

[tools.editor]
enabled = true

preferred_editor = ""

suspend_tui = true


# Tool-specific loop thresholds (Adaptive Loop Detection) Allows setting higher loop limits for
# read-only tools (e.g., ls, grep) and lower limits for mutating tools.
# Default: {}
[tools.loop_thresholds]

[tools.plugins]
# Explicit allow-list of plugin identifiers permitted to load.
# Default: []
# Type: `array`
allow = []

# Enable hot-reload polling for manifests to support rapid iteration.
# Default: false
# Type: `boolean`
auto_reload = true

# Default trust level when a manifest omits trust metadata.
# Default: "sandbox"
# Type: `string`
default_trust = "sandbox"

# Explicit block-list of plugin identifiers that must be rejected.
# Default: []
# Type: `array`
deny = []

# Toggle the plugin runtime. When disabled, manifests are ignored.
# Default: true
# Type: `boolean`
enabled = true

# Manifest paths (files or directories) that should be scanned for plugins.
# Default: []
# Type: `array`
manifests = []


# Specific tool policies
# Default: {}
[tools.policies]
"/edit" = "prompt"

"/plan" = "prompt"

"/plan_off" = "prompt"

agent_info = "allow"

apply_patch = "allow"

ask_user_question = "allow"

"assistant<|channel|>apply_patch" = "allow"

checklist = "prompt"

coder_mode = "prompt"

enter_plan = "prompt"

enter_plan_mode = "prompt"

exec_code = "allow"

execute_code = "allow"

exit_plan = "prompt"

exit_plan_mode = "allow"

git_diff = "allow"

implement_plan = "prompt"

list_skills = "allow"

load_skill = "allow"

load_skill_resource = "allow"

mode_edit = "prompt"

mode_plan = "prompt"

open_file = "allow"

plan_checklist = "prompt"

plan_exit = "prompt"

plan_manager = "prompt"

plan_mode = "prompt"

plan_off = "prompt"

plan_on = "prompt"

plan_start = "prompt"

plan_task_tracker = "allow"

plan_tasks = "prompt"

planner_mode = "prompt"

request_user_input = "allow"

resume_edit_mode = "prompt"

run_pty_cmd = "allow"

search_file = "allow"

"send_command<|channel|>analysis" = "allow"

start_implementation = "prompt"

start_planning = "prompt"

switch_edit_mode = "prompt"

switch_plan_mode = "prompt"

switch_to_edit_mode = "prompt"

switch_to_plan_mode = "prompt"

task_tracker = "allow"

track_tasks = "prompt"

unified_exec = "allow"

unified_file = "allow"

web_fetch = "allow"

write_file = "allow"


[tools.web_fetch]
# Inline whitelist - Domains to allow in restricted mode
# Default: []
# Type: `array`
allowed_domains = []

# Path to audit log file
# Default: ""
# Type: `string`
audit_log_path = "~/.vtcode/web_fetch_audit.log"

# Inline blocklist - Additional domains to block
# Default: []
# Type: `array`
blocked_domains = []

# Additional blocked patterns
# Default: []
# Type: `array`
blocked_patterns = []

# Enable dynamic blocklist loading from external file
# Default: false
# Type: `boolean`
dynamic_blocklist_enabled = false

# Path to dynamic blocklist file
# Default: ""
# Type: `string`
dynamic_blocklist_path = "~/.vtcode/web_fetch_blocklist.json"

# Enable dynamic whitelist loading from external file
# Default: false
# Type: `boolean`
dynamic_whitelist_enabled = false

# Path to dynamic whitelist file
# Default: ""
# Type: `string`
dynamic_whitelist_path = "~/.vtcode/web_fetch_whitelist.json"

# Enable audit logging of URL validation decisions
# Default: false
# Type: `boolean`
enable_audit_logging = false

# Security mode: "restricted" (blocklist) or "whitelist" (allowlist)
# Possible values: blocklist
# Default: "restricted"
# Type: `string`
mode = "restricted"

# Strict HTTPS-only mode
# Default: true
# Type: `boolean`
strict_https_only = true


[ui]
# Allow ANSI escape sequences in tool output (enables colors but may cause layout issues)
# Default: false
# Type: `boolean`
allow_tool_ansi = true

# Compatibility mode for legacy terminals that map bold to bright colors. When enabled, avoids using
# bold styling on text that would become bright colors, preventing visibility issues in terminals with
# "bold is bright" behavior.
# Default: false
# Type: `boolean`
bold_is_bright = true

# Color scheme mode for automatic light/dark theme switching. - "auto": Detect from terminal (via OSC
# 11 or COLORFGBG env var) - "light": Force light mode theme selection - "dark": Force dark mode theme
# selection
# Default: "auto"
# Type: `string`
color_scheme_mode = "auto"

# Dim completed todo items (- [x]) in agent output
# Default: true
# Type: `boolean`
dim_completed_todos = true

# UI display mode preset (full, minimal, focused)
# Possible values: focused, full, minimal
# Default: "minimal"
# Type: `string`
display_mode = "minimal"

# Number of rows to allocate for inline UI viewport
# Default: 16
# Type: `integer`
inline_viewport_rows = 16

# Override the responsive layout mode
# Default: "auto"
# Type: `string`
layout_mode = "auto"

# Add spacing between message blocks
# Default: true
# Type: `boolean`
message_block_spacing = true

# Minimum contrast ratio for text against background (WCAG 2.1 standard) - 4.5: WCAG AA (default,
# suitable for most users) - 7.0: WCAG AAA (enhanced, for low-vision users) - 3.0: Large text minimum
# - 1.0: Disable contrast enforcement
# Default: 4.5
# Type: `number`
minimum_contrast = 4.5

# Reasoning display mode for chat UI ("always", "toggle", or "hidden")
# Possible values: always, toggle
# Default: "toggle"
# Type: `string`
reasoning_display_mode = "toggle"

# Default visibility for reasoning when display mode is "toggle"
# Default: false
# Type: `boolean`
reasoning_visible_default = true

# Keep animated progress indicators while `ui.reduce_motion_mode` is enabled.
# Default: false
# Type: `boolean`
reduce_motion_keep_progress_animation = false

# Reduce motion mode: minimizes shimmer/flashing animations. Can also be enabled via
# `VTCODE_REDUCE_MOTION=1`.
# Default: false
# Type: `boolean`
reduce_motion_mode = false

# Restrict color palette to the 11 "safe" ANSI colors portable across common themes. Safe colors: red,
# green, yellow, blue, magenta, cyan + brred, brgreen, brmagenta, brcyan Problematic colors avoided:
# brblack (invisible in Solarized Dark), bryellow (light themes), white/brwhite (light themes), brblue
# (Basic Dark). See: https://blog.xoria.org/terminal-colors/
# Default: false
# Type: `boolean`
safe_colors_only = false

# Screen reader mode: disables animations, uses plain text indicators, and optimizes output for
# assistive technology compatibility. Can also be enabled via `VTCODE_SCREEN_READER=1`.
# Default: false
# Type: `boolean`
screen_reader_mode = false

# Show warning/error/fatal diagnostic lines in the TUI transcript and log panel. Also controls whether
# ERROR-level tracing logs appear in the TUI session log. Errors are always captured in the session
# archive JSON regardless of this setting.
# Default: false
# Type: `boolean`
show_diagnostics_in_transcript = true

# Show the right sidebar (queue, context, tools)
# Possible values: context, queue, tools
# Default: true
# Type: `boolean`
show_sidebar = false

show_turn_timer = false

# Maximum number of lines to display in tool output (prevents transcript flooding)
# Default: 600
# Type: `integer`
tool_output_max_lines = 50

# Tool output display mode ("compact" or "full")
# Default: "compact"
# Type: `string`
tool_output_mode = "compact"

# Maximum bytes of output to display before auto-spooling to disk
# Default: 200000
# Type: `integer`
tool_output_spool_bytes = 200000

[ui.keyboard_protocol]
# Resolve Esc key ambiguity (recommended for performance)
# Default: true
# Type: `boolean`
disambiguate_escape_codes = true

# Enable keyboard protocol enhancements (master toggle)
# Default: true
# Type: `boolean`
enabled = true

# Preset mode: "default", "full", "minimal", or "custom"
# Default: "default"
# Type: `string`
mode = "default"

# Report all keys, including modifier-only keys (Shift, Ctrl)
# Possible values: Ctrl, Shift
# Default: false
# Type: `boolean`
report_all_keys = false

# Report alternate key layouts (e.g. for non-US keyboards)
# Default: true
# Type: `boolean`
report_alternate_keys = true

# Report press, release, and repeat events
# Default: true
# Type: `boolean`
report_event_types = true


[ui.notifications]
completion = true

delivery_mode = "hybrid"

enabled = true

command_failure = false

error = false

completion_success = false

completion_failure = true

hitl = true

policy_approval = true

request = false

suppress_when_focused = true

tool_failure = false

tool_success = false

repeat_window_seconds = 30

max_identical_in_window = 1


[ui.status_line]
# -
# Default: 200
# Type: `integer`
command_timeout_ms = 200

# -
# Default: "Auto"
# Type: `string`
mode = "Auto"

# -
# Default: 1000
# Type: `integer`
refresh_interval_ms = 1000