# VTCode Configuration File (Example)
# Getting-started reference; see docs/config/CONFIGURATION_PRECEDENCE.md for override order.
# Copy this file to vtcode.toml and customize as needed.
# Core agent behavior; see docs/config/CONFIGURATION_PRECEDENCE.md.
[agent]
# Primary LLM provider to use (e.g., "openai", "gemini", "anthropic", "openrouter")
provider = "openai"
# Environment variable containing the API key for the provider
api_key_env = "OPENAI_API_KEY"
# Default model to use when no specific model is specified
default_model = "gpt-5-nano"
# Visual theme for the terminal interface
theme = "ciapre-dark"
# Enable TODO planning helper mode for structured task management
todo_planning_mode = true
# UI surface to use ("auto", "alternate", "inline")
ui_surface = "auto"
# Maximum number of conversation turns before rotating context (affects memory usage)
# Lower values reduce memory footprint but may lose context; higher values preserve context but use more memory
max_conversation_turns = 50
# Reasoning effort level ("low", "medium", "high") - affects model usage and response speed
reasoning_effort = "low"
# Enable self-review loop to check and improve responses (increases API calls)
enable_self_review = false
# Maximum number of review passes when self-review is enabled
max_review_passes = 1
# Enable prompt refinement loop for improved prompt quality (increases processing time)
refine_prompts_enabled = false
# Maximum passes for prompt refinement when enabled
refine_prompts_max_passes = 1
# Optional alternate model for refinement (leave empty to use default)
refine_prompts_model = ""
# Small model configuration for efficient operations
# Following Claude Code's pattern, use a smaller model for 50%+ of calls (large reads, parsing, summarization)
# Typically 70-80% cheaper than main model; same quality for summary/parse tasks
[agent.small_model]
# Enable small model tier
enabled = true
# Small model ID (e.g., "claude-3-5-haiku", "gpt-4o-mini", "gemini-2.0-flash")
# Leave empty to auto-select lightweight sibling of main model
model = ""
# Maximum tokens for small model responses (use smaller value for summaries/parsing)
max_tokens = 1000
# Temperature for small model (lower = more deterministic for parsing)
temperature = 0.3
# Use small model for large file reads (>50KB) - significant token savings
use_for_large_reads = true
# Use small model for web content summarization
use_for_web_summary = true
# Use small model for git history processing
use_for_git_history = true
# Maximum size of project documentation to include in context (in bytes)
project_doc_max_bytes = 16384
# Maximum size of instruction files to process (in bytes)
instruction_max_bytes = 16384
# List of additional instruction files to include in context
instruction_files = []
# Onboarding configuration - Customize the startup experience
[agent.onboarding]
# Enable the onboarding welcome message on startup
enabled = true
# Custom introduction text shown on startup
intro_text = "Let's get oriented. I preloaded workspace context so we can move fast."
# Include project overview information in welcome
include_project_overview = true
# Include language summary information in welcome
include_language_summary = false
# Include key guideline highlights from AGENTS.md
include_guideline_highlights = true
# Include usage tips in the welcome message
include_usage_tips_in_welcome = false
# Include recommended actions in the welcome message
include_recommended_actions_in_welcome = false
# Maximum number of guideline highlights to show
guideline_highlight_limit = 3
# List of usage tips shown during onboarding
usage_tips = [
"Describe your current coding goal or ask for a quick status overview.",
"Reference AGENTS.md guidelines when proposing changes.",
"Draft or refresh your TODO list with update_plan before coding.",
"Prefer asking for targeted file reads or diffs before editing.",
]
# List of recommended actions shown during onboarding
recommended_actions = [
"Start the session by outlining a 3–6 step TODO plan via update_plan.",
"Review the highlighted guidelines and share the task you want to tackle.",
"Ask for a workspace tour if you need more context.",
]
# Custom prompts configuration - Define personal assistant commands
[agent.custom_prompts]
# Enable the custom prompts feature with /prompts:<name> syntax
enabled = true
# Directory where custom prompt files are stored
directory = "~/.vtcode/prompts"
# Additional directories to search for custom prompts
extra_directories = []
# Maximum file size for custom prompts (in kilobytes)
max_file_size_kb = 64
# Custom API keys for specific providers
[agent.custom_api_keys]
# Moonshot AI API key (for specific provider access)
moonshot = "sk-sDj3JUXDbfARCYKNL4q7iGWRtWuhL1M4O6zzgtDpN3Yxt9EA"
# Checkpointing configuration for session persistence
[agent.checkpointing]
# Enable automatic session checkpointing
enabled = false
# Maximum number of checkpoints to keep on disk
max_snapshots = 50
# Maximum age of checkpoints to keep (in days)
max_age_days = 30
# Tool security configuration
[tools]
# Default policy when no specific policy is defined ("allow", "prompt", "deny")
# "allow" - Execute without confirmation
# "prompt" - Ask for confirmation
# "deny" - Block the tool
default_policy = "prompt"
# Maximum number of tool loops allowed per turn (prevents infinite loops)
# Higher values allow more complex operations but risk performance issues
# Recommended: 20 for most tasks, 50 for complex multi-step workflows
max_tool_loops = 20
# Maximum number of repeated identical tool calls (prevents stuck loops)
max_repeated_tool_calls = 2
# Specific tool policies - Override default policy for individual tools
[tools.policies]
apply_patch = "prompt" # Apply code patches (requires confirmation)
close_pty_session = "allow" # Close PTY sessions (no confirmation needed)
create_pty_session = "allow" # Create PTY sessions (no confirmation needed)
edit_file = "allow" # Edit files directly (no confirmation needed)
grep_file = "allow" # Sole content-search tool (ripgrep-backed)
list_files = "allow" # List directory contents (no confirmation needed)
list_pty_sessions = "allow" # List PTY sessions (no confirmation needed)
read_file = "allow" # Read files (no confirmation needed)
read_pty_session = "allow" # Read PTY session output (no confirmation needed)
resize_pty_session = "allow" # Resize PTY sessions (no confirmation needed)
run_pty_cmd = "prompt" # Run commands in PTY (requires confirmation)
run_terminal_cmd = "prompt" # Run terminal commands (requires confirmation)
send_pty_input = "prompt" # Send input to PTY (requires confirmation)
update_plan = "allow" # Update task plans (no confirmation needed)
web_fetch = "prompt" # Fetch web content (requires confirmation)
write_file = "allow" # Write files (no confirmation needed)
# Web Fetch tool security configuration
# See docs/tools/web_fetch_security.md for detailed documentation
[tools.web_fetch]
# Security mode: "restricted" (blocklist) or "whitelist" (allowlist only)
# "restricted" - Blocks known sensitive/malicious domains (default, recommended)
# "whitelist" - Only allows explicitly whitelisted domains (strictest, enterprise use)
mode = "restricted"
# Enable dynamic blocklist loading from external file
# Useful for organization-specific domains
dynamic_blocklist_enabled = false
# Path to dynamic blocklist file (JSON format)
# File should contain: { "blocked_domains": [...], "blocked_patterns": [...] }
# Example: ~/.vtcode/web_fetch_blocklist.json
# See .vtcode/web_fetch_blocklist.json.example for template
dynamic_blocklist_path = "~/.vtcode/web_fetch_blocklist.json"
# Enable dynamic whitelist loading from external file (whitelist mode only)
# Recommended for enterprise use with whitelist mode
dynamic_whitelist_enabled = false
# Path to dynamic whitelist file (JSON format)
# File should contain: { "allowed_domains": [...] }
# Example: ~/.vtcode/web_fetch_whitelist.json
# See .vtcode/web_fetch_whitelist.json.example for template
dynamic_whitelist_path = "~/.vtcode/web_fetch_whitelist.json"
# Inline blocklist - Additional domains to block (merged with default blocklist)
# Example: ["internal-api.company.com", "legacy-system.local"]
blocked_domains = []
# Inline whitelist - Specific domains to allow in restricted mode
# Useful for exempting legitimate services from blocklist
# Example: ["paypal.com/status", "company-docs.com"]
allowed_domains = []
# Additional blocked patterns (merged with defaults)
# These patterns prevent access to URLs containing sensitive information
# Example: ["internal_token=", "company_secret="]
blocked_patterns = []
# Log all URL validation decisions for audit trail
# Useful for security monitoring and compliance
enable_audit_logging = false
# Audit log file location
# Only used if enable_audit_logging = true
audit_log_path = "~/.vtcode/web_fetch_audit.log"
# Strict mode: Block HTTP and require HTTPS
# Recommended: keep true for production
# Set to false only for development/testing with local services
strict_https_only = true
# Command security - Define safe and dangerous command patterns
[commands]
# Commands that are always allowed without confirmation
# For non-powered users: all safe, known commands are enabled by default
# These safe commands help the agent use system and build tools properly
allow_list = [
# File system and basic utilities
"ls", # List directory contents
"pwd", # Print working directory
"cat", # Display file contents
"head", # Show first lines
"tail", # Show last lines
"grep", # Search text patterns
"find", # Find files
"wc", # Count lines/words
"sort", # Sort lines
"uniq", # Remove duplicates
"cut", # Extract columns
"awk", # Text processing
"sed", # Stream editor
"echo", # Print text
"printf", # Formatted print
"date", # Print date/time
"which", # Locate commands
"file", # File type detection
"stat", # File status
"tree", # Directory tree
"diff", # Compare files
"patch", # Apply patches
"whoami", # Current user
"hostname", # System hostname
"uname", # System info
# Compression utilities
"tar",
"zip",
"unzip",
"gzip",
"gunzip",
"bzip2",
"bunzip2",
"xz",
"unxz",
# Version control systems
"git",
"hg",
"svn",
"git-lfs",
# Git workflow commands
"git status",
"git diff",
"git log",
"git show",
"git branch",
"git remote",
"git fetch",
"git pull",
"git clone",
"git checkout",
"git switch",
"git add",
"git commit",
"git stash",
"git tag",
# Build systems
"make",
"cmake",
"ninja",
"meson",
"bazel",
# Rust/Cargo ecosystem
"cargo", # Rust package manager
"cargo build",
"cargo build --release",
"cargo build --profile release",
"cargo check",
"cargo test",
"cargo run",
"cargo clippy",
"cargo fmt",
"cargo tree",
"cargo metadata",
"cargo doc",
"cargo nextest",
"cargo nextest run",
"rustc",
"rustfmt",
"rustup",
# Python ecosystem
"python", # Python interpreter
"python3",
"pip", # Package installer
"pip3",
"virtualenv", # Virtual environments
"pytest",
"black", # Code formatter
"flake8", # Linter
"mypy", # Type checker
"ruff", # Fast linter
# Node.js/npm ecosystem
"npm", # JavaScript package manager
"node", # JavaScript runtime
"yarn", # Alternative package manager
"pnpm", # Performant package manager
"bun", # Fast JavaScript runtime
"npx", # Run packages
# Go ecosystem
"go", # Go compiler
"gofmt", # Code formatter
"golint", # Linter
# Java ecosystem
"java", # Java runtime
"javac", # Java compiler
"mvn", # Maven build tool
"gradle", # Gradle build tool
# C/C++ ecosystem
"gcc", # C compiler
"g++", # C++ compiler
"clang", # Alternative C compiler
"clang++", # Alternative C++ compiler
# Container tools
"docker", # Container platform
"docker-compose", # Container orchestration
# System info utilities
"ps", # Process listing
"top", # Process monitor
"htop", # Interactive process monitor
"df", # Disk usage
"du", # Directory usage
]
# Additional directories to prepend to PATH when running commands
# Enables agent to find user-installed tools and language runtime binaries
extra_path_entries = [
"$HOME/.cargo/bin", # Rust tools
"$HOME/.cargo/env", # Rust environment
"$HOME/.local/bin", # Local user binaries
"$HOME/.nvm/versions/node/*/bin", # Node.js versions
"/opt/homebrew/bin", # Homebrew (macOS)
]
# Commands that are never allowed - Explicit dangerous command patterns
# These are blocked regardless of any allow rules
deny_list = [
# Destructive root filesystem operations
"rm -rf /", # Delete root directory (dangerous)
"rm -rf ~", # Delete home directory (dangerous)
"rm -rf /*", # Delete root contents
"rm -rf /home", # Delete home directory (system-wide)
"rm -rf /usr", # Delete user binaries (destructive)
"rm -rf /etc", # Delete system config (destructive)
"rm -rf /var", # Delete variable data (destructive)
"rm -rf /opt", # Delete optional software (destructive)
# System shutdown/reboot operations
"shutdown", # Shut down system (dangerous)
"reboot", # Reboot system (dangerous)
"halt", # Halt system (dangerous)
"poweroff", # Power off system (dangerous)
"init 0", # Init shutdown (dangerous)
"init 6", # Init reboot (dangerous)
"systemctl poweroff", # Systemd shutdown (dangerous)
"systemctl reboot", # Systemd reboot (dangerous)
"systemctl halt", # Systemd halt (dangerous)
# Privilege escalation attempts
"sudo rm", # Sudo remove (dangerous)
"sudo chmod", # Sudo permission change (dangerous)
"sudo chown", # Sudo ownership change (dangerous)
"sudo passwd", # Sudo password change (dangerous)
"sudo su", # Sudo shell (dangerous)
"sudo -i", # Sudo interactive (dangerous)
"sudo bash", # Sudo bash shell (dangerous)
"su root", # Switch to root (dangerous)
"su -", # Switch to root (dangerous)
# Filesystem destruction
"format", # Format disk (dangerous)
"fdisk", # Partition disk (dangerous)
"mkfs", # Make filesystem (dangerous)
"mkfs.ext4", # Make ext4 filesystem (dangerous)
"mkfs.xfs", # Make xfs filesystem (dangerous)
"mkfs.vfat", # Make vfat filesystem (dangerous)
"dd if=/dev/zero", # Overwrite with zeros (dangerous)
"dd if=/dev/random", # Overwrite with random (dangerous)
"dd if=/dev/urandom", # Overwrite with urandom (dangerous)
# Shell exploits
":(){ :|:& };:", # Fork bomb (dangerous)
"nohup bash -i", # Background shell (dangerous)
"exec bash -i", # Replace shell (dangerous)
"eval", # Execute strings (dangerous)
"source /etc/bashrc", # Source system config (dangerous)
"source ~/.bashrc", # Source user config (dangerous)
# Permission/ownership changes
"chmod 777", # World-writable permissions (dangerous)
"chmod -R 777", # Recursive world-writable (dangerous)
"chown -R", # Recursive ownership change (dangerous)
"chgrp -R", # Recursive group change (dangerous)
# SSH key exposure
"rm ~/.ssh/*", # Delete SSH keys (dangerous)
"rm -r ~/.ssh", # Delete SSH directory (dangerous)
# Sensitive file access
"cat /etc/passwd", # Expose user data (dangerous)
"cat /etc/shadow", # Expose password hashes (dangerous)
"cat ~/.ssh/id_*", # Expose private keys (dangerous)
"tail -f /var/log", # Monitor system logs (dangerous)
"head -n 1 /var/log", # Read system logs (dangerous)
]
# Command patterns that are allowed (supports glob patterns)
# Glob patterns enable safe workflows for common development tasks
allow_glob = [
# Version control workflows
"git *", # Allow common git workflows; destructive flags require confirm
"hg *", # Mercurial workflows
"svn *", # Subversion workflows
# Build and compilation workflows
"cargo *", # Allow cargo workflows; publishing requires confirm
"cargo nextest *", # Test execution
"rustc *", # Rust compiler
"rustfmt *", # Code formatter
"make *", # Make build system
"cmake *", # CMake build system
"ninja *", # Ninja build system
# Python workflows
"python *", # Python commands
"python3 *", # Python 3 commands
"pip *", # Package installation
"pip3 *", # Python 3 package installation
"virtualenv *", # Virtual environment
"pytest *", # Test execution
# Node.js workflows
"npm *", # NPM commands
"npm run *", # NPM scripts
"node *", # Node runtime
"yarn *", # Yarn package manager
"yarn run *", # Yarn scripts
"pnpm *", # PNPM package manager
"pnpm run *", # PNPM scripts
"bun *", # Bun runtime
"bun run *", # Bun scripts
"npx *", # Execute packages
# Go workflows
"go *", # Go compiler
"gofmt *", # Go formatter
# Java workflows
"javac *", # Java compiler
"java *", # Java runtime
"mvn *", # Maven build
"gradle *", # Gradle build
# C/C++ workflows
"gcc *", # C compiler
"g++ *", # C++ compiler
"clang *", # Alternative C compiler
"clang++ *", # Alternative C++ compiler
# Container workflows
"docker *", # Docker commands
"docker-compose *", # Docker compose
# File operations (read-only safe operations)
"cat *", # File viewing
"head *", # View start of files
"tail *", # View end of files
"grep *", # Search files
"find *", # Find files
"wc *", # Count content
"diff *", # Compare files
"tar *", # Archive operations
"zip *", # ZIP compression
"unzip *", # ZIP extraction
"gzip *", # GZIP compression
"gunzip *", # GZIP extraction
]
# When commands are potentially destructive, the agent will require an explicit confirmation flag
# Example: set `confirm = true` in the `EnhancedTerminalInput` for `run_terminal_cmd` tool input
# Command patterns that are denied (supports glob patterns)
# These patterns are always blocked to prevent dangerous operations
deny_glob = [
"rm *", # Delete operations (potentially destructive)
"rmdir *", # Directory removal
"sudo *", # Privilege escalation
"chmod *", # Permission changes
"chown *", # Ownership changes
"kill *", # Process termination
"pkill *", # Process killing by pattern
"systemctl *", # System service management
"service *", # Legacy service management
"mount *", # Filesystem mounting
"umount *", # Filesystem unmounting
"dd *", # Direct disk access
"mkfs *", # Filesystem creation
"fdisk *", # Disk partitioning
"docker run *", # Docker container creation (requires careful review)
"kubectl *", # Kubernetes operations
"shutdown *", # System shutdown
"reboot *", # System reboot
"halt *", # System halt
]
# Regular expression patterns for allowed commands (if needed)
allow_regex = []
# Regular expression patterns for denied commands (if needed)
deny_regex = []
# Security configuration - Safety settings for automated operations
[security]
# Require human confirmation for potentially dangerous actions
human_in_the_loop = true
# Require explicit write tool usage for claims about file modifications
require_write_tool_for_claims = true
# Auto-apply patches without prompting (DANGEROUS - disable for safety)
auto_apply_detected_patches = false
# UI configuration - Terminal and display settings
[ui]
# Tool output display mode
# "compact" - Concise tool output
# "full" - Detailed tool output
tool_output_mode = "full"
# Maximum number of lines to display for each tool stream section
tool_output_max_lines = 600
# Spool tool output larger than this many bytes to .vtcode/tool-output/*.log (0 disables spooling)
tool_output_spool_bytes = 200000
# Optional custom directory for spooled tool output logs (relative or absolute)
# tool_output_spool_dir = ".vtcode/tool-output"
# Preserve ANSI color codes in tool output (set to true to enable colors)
allow_tool_ansi = true
# Number of rows to allocate for inline UI viewport
inline_viewport_rows = 16
# Show timeline navigation panel (displays plan when available, timeline otherwise)
show_timeline_pane = true
# Status line configuration
[ui.status_line]
# Status line mode ("auto", "command", "hidden")
mode = "auto"
# How often to refresh status line (milliseconds)
refresh_interval_ms = 2000
# Timeout for command execution in status line (milliseconds)
command_timeout_ms = 200
# Timeout ceilings and warning threshold for long-running tools
[timeouts]
# Maximum duration for standard (non-PTY) tools in seconds. Set to 0 to disable.
default_ceiling_seconds = 180
# Maximum duration for PTY-backed commands in seconds. Set to 0 to disable.
pty_ceiling_seconds = 300
# Maximum duration for MCP tool calls in seconds. Set to 0 to disable.
mcp_ceiling_seconds = 120
# Maximum duration for streaming API responses in seconds. Set to 0 to disable.
# Increase this if you encounter streaming timeouts with long inputs or slow networks
streaming_ceiling_seconds = 600
# Emit a warning once execution exceeds this percentage of the ceiling.
warning_threshold_percent = 80
# PTY (Pseudo Terminal) configuration - For interactive command execution
[pty]
# Enable PTY support for interactive commands
enabled = true
# Default number of terminal rows for PTY sessions
default_rows = 24
# Default number of terminal columns for PTY sessions
default_cols = 80
# Maximum number of concurrent PTY sessions
max_sessions = 10
# Command timeout in seconds (prevents hanging commands)
command_timeout_seconds = 300
# Number of recent lines to show in PTY output
stdout_tail_lines = 20
# Total lines to keep in PTY scrollback buffer
scrollback_lines = 400
# Preferred shell program for PTY sessions
# Priority order for shell selection:
# 1. Explicitly specified shell (per-command parameter)
# 2. preferred_shell configuration (this setting)
# 3. $SHELL environment variable
# 4. Auto-detection (searches for /bin/zsh, /bin/bash, /bin/sh)
# 5. Fallback to appropriate system default (/bin/sh on POSIX, cmd.exe/pwsh on Windows)
# Leave blank to use auto-detection (recommended for development)
# preferred_shell = "/bin/zsh"
# Context management configuration - Controls conversation memory
[context]
# Maximum number of tokens to keep in context (affects model cost and performance)
# Higher values preserve more context but cost more and may hit token limits
max_context_tokens = 90000
# Percentage to trim context to when it gets too large
trim_to_percent = 60
# Number of recent conversation turns to always preserve
preserve_recent_turns = 6
# Enable semantic-aware context compression using structural analysis
semantic_compression = false
# Retain tool outputs longer when related actions are in progress
tool_aware_retention = false
# Maximum AST depth to preserve when semantic compression is active
max_structural_depth = 3
# Number of recent tool responses to keep when tool-aware retention is enabled
preserve_recent_tools = 5
# Decision ledger configuration - Track important decisions
[context.ledger]
# Enable decision tracking and persistence
enabled = true
# Maximum number of decisions to keep in ledger
max_entries = 12
# Include ledger summary in model prompts
include_in_prompt = true
# Token budget management - Track and limit token usage
[context.token_budget]
# Enable token usage tracking and budget enforcement
enabled = false
# Model to use for token counting (must match your actual model)
model = "gpt-5-nano"
# Percentage threshold to warn about token usage (0.75 = 75%)
warning_threshold = 0.75
# Enable detailed component-level token tracking (increases overhead)
detailed_tracking = false
# Context curation - Intelligent context management
[context.curation]
# Enable automatic context curation (filters and optimizes context)
enabled = false
# Maximum tokens to allow per turn after curation
max_tokens_per_turn = 50000
# Number of recent messages to always preserve
preserve_recent_messages = 5
# Maximum number of tool descriptions to keep in context
max_tool_descriptions = 10
# Include decision ledger in curation
include_ledger = true
# Maximum ledger entries to include in curation
ledger_max_entries = 12
# Include recent error messages in context
include_recent_errors = true
# Maximum recent errors to include
max_recent_errors = 3
# AI model routing - Intelligent model selection
[router]
# Enable intelligent model routing
enabled = true
# Enable heuristic-based model selection
heuristic_classification = true
# Optional override model for routing decisions (empty = use default)
llm_router_model = ""
# Model mapping for different task types
[router.models]
# Model for simple queries
simple = "gpt-5-nano"
# Model for standard tasks
standard = "gpt-5-nano"
# Model for complex tasks
complex = "gpt-5-nano"
# Model for code generation heavy tasks
codegen_heavy = "gpt-5-nano"
# Model for information retrieval heavy tasks
retrieval_heavy = "gpt-5-nano"
# Router budget settings (if applicable)
[router.budgets]
# Router heuristic patterns for task classification
[router.heuristics]
# Maximum characters for short requests
short_request_max_chars = 120
# Minimum characters for long requests
long_request_min_chars = 1200
# Text patterns that indicate code patch operations
code_patch_markers = [
"```",
"diff --git",
"apply_patch",
"unified diff",
"patch",
"edit_file",
"create_file",
]
# Text patterns that indicate information retrieval
retrieval_markers = [
"search",
"web",
"google",
"docs",
"cite",
"source",
"up-to-date",
]
# Text patterns that indicate complex multi-step tasks
complex_markers = [
"plan",
"multi-step",
"decompose",
"orchestrate",
"architecture",
"benchmark",
"implement end-to-end",
"design api",
"refactor module",
"evaluate",
"tests suite",
]
# Telemetry and analytics
[telemetry]
# Enable trajectory logging for usage analysis
trajectory_enabled = true
# Syntax highlighting configuration
[syntax_highlighting]
# Enable syntax highlighting for code in tool output
enabled = true
# Theme for syntax highlighting
theme = "base16-ocean.dark"
# Cache syntax highlighting themes for performance
cache_themes = true
# Maximum file size for syntax highlighting (in MB)
max_file_size_mb = 10
# Programming languages to enable syntax highlighting for
enabled_languages = [
"rust",
"python",
"javascript",
"typescript",
"go",
"java",
]
# Timeout for syntax highlighting operations (milliseconds)
highlight_timeout_ms = 1000
# Automation features - Full-auto mode settings
[automation.full_auto]
# Enable full automation mode (DANGEROUS - requires careful oversight)
enabled = false
# Maximum number of turns before asking for human input
max_turns = 30
# Tools allowed in full automation mode
allowed_tools = [
"write_file",
"read_file",
"list_files",
"grep_file",
]
# Require profile acknowledgment before using full auto
require_profile_ack = true
# Path to full auto profile configuration
profile_path = "automation/full_auto_profile.toml"
# Prompt caching - Cache model responses for efficiency
[prompt_cache]
# Enable prompt caching (reduces API calls for repeated prompts)
enabled = false
# Directory for cache storage
cache_dir = "~/.vtcode/cache/prompts"
# Maximum number of cache entries to keep
max_entries = 1000
# Maximum age of cache entries (in days)
max_age_days = 30
# Enable automatic cache cleanup
enable_auto_cleanup = true
# Minimum quality threshold to keep cache entries
min_quality_threshold = 0.7
# Prompt cache configuration for OpenAI
[prompt_cache.providers.openai]
enabled = true
min_prefix_tokens = 1024
idle_expiration_seconds = 3600
surface_metrics = true
# Prompt cache configuration for Anthropic
[prompt_cache.providers.anthropic]
enabled = true
default_ttl_seconds = 300
extended_ttl_seconds = 3600
max_breakpoints = 4
cache_system_messages = true
cache_user_messages = true
# Prompt cache configuration for Gemini
[prompt_cache.providers.gemini]
enabled = true
mode = "implicit"
min_prefix_tokens = 1024
explicit_ttl_seconds = 3600
# Prompt cache configuration for OpenRouter
[prompt_cache.providers.openrouter]
enabled = true
propagate_provider_capabilities = true
report_savings = true
# Prompt cache configuration for Moonshot
[prompt_cache.providers.moonshot]
enabled = true
# Prompt cache configuration for xAI
[prompt_cache.providers.xai]
enabled = true
# Prompt cache configuration for DeepSeek
[prompt_cache.providers.deepseek]
enabled = true
surface_metrics = true
# Prompt cache configuration for Z.AI
[prompt_cache.providers.zai]
enabled = false
# Model Context Protocol (MCP) - Connect external tools and services
[mcp]
# Enable Model Context Protocol (may impact startup time if services unavailable)
enabled = true
max_concurrent_connections = 5
request_timeout_seconds = 30
retry_attempts = 3
# Timeout (seconds) for initializing MCP servers (default: 60)
startup_timeout_seconds = 60
# MCP UI configuration
[mcp.ui]
mode = "compact"
max_events = 50
show_provider_names = true
# MCP renderer profiles for different services
[mcp.ui.renderers]
sequential-thinking = "sequential-thinking"
context7 = "context7"
# MCP provider configuration - External services that connect via MCP
[[mcp.providers]]
name = "time"
command = "uvx"
args = ["mcp-server-time"]
enabled = true
max_concurrent_requests = 3
[mcp.providers.env]
# Agent Client Protocol (ACP) - IDE integration
[acp]
enabled = true
[acp.zed]
enabled = true
transport = "stdio"
workspace_trust = "full_auto"
[acp.zed.tools]
read_file = true
list_files = true
# Lifecycle hooks - Execute shell commands in response to agent events
# For documentation and examples, see: docs/guides/lifecycle-hooks.md
[hooks.lifecycle]
# Session start hooks - Run when a session begins
session_start = [
# Example: Set up project context when session starts
{
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/setup-env.sh",
timeout_seconds = 30
}
]
}
]
# Session end hooks - Run when a session ends
session_end = [
# Example: Log session completion
{
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/log-session-end.sh"
}
]
}
]
# Pre-tool use hooks - Run before tools execute, can block or validate
pre_tool_use = [
# Example: Validate bash commands for dangerous patterns
{
matcher = "Bash",
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/security-check.sh",
timeout_seconds = 10
}
]
}
]
# Post-tool use hooks - Run after tools execute successfully
post_tool_use = [
# Example: Run linters after file modifications
{
matcher = "Write|Edit",
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/run-linter.sh"
}
]
},
# Example: Log bash command execution
{
matcher = "Bash",
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/log-command.sh"
}
]
},
# Example: Track all tool usage
{
matcher = ".*",
hooks = [
{
command = "$VT_PROJECT_DIR/.vtcode/hooks/log-tool-usage.sh"
}
]
}
]
# Model-specific behavior configuration
[model]
# Enable loop hang detection to identify when model is stuck in repetitive behavior
# When disabled, the model can continue making repetitive tool calls
# Default: false (detection is enabled by default)
skip_loop_detection = false
# Maximum number of identical tool calls (same tool + same arguments) before triggering loop detection
# Default: 3
# When a tool with identical arguments is called more than this threshold, detection triggers
loop_detection_threshold = 3
# Enable interactive prompt for loop detection instead of silently halting
# When true, shows a user prompt asking whether to keep detection enabled or disable for session
# When false, automatically halts on detected loop without prompting
# Default: true
loop_detection_interactive = true