vtcode 0.45.2

# VTCode Configuration File
# 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 = "ollama"

# Environment variable containing the API key for the provider
api_key_env = "OLLAMA_API_KEY"

# Default model to use when no specific model is specified
default_model = "gpt-oss:20b-cloud"

# 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"

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

# Maximum tokens for main LLM generation responses
# Default: 2000 for standard tasks
# Adjust based on model context window:
# - 16384 for models with 128k context
# - 32768 for models with 256k context
max_tokens = 2000

# Temperature for prompt refinement (0.0-1.0)
# Lower values ensure more deterministic/consistent prompt improvement
# Default: 0.3 is lower than main temperature for stable refinement
refine_temperature = 0.3

# Maximum tokens for prompt refinement
# Prompts are typically shorter, so 800 tokens is usually sufficient
refine_max_tokens = 800

# 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 = ""

# 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 = []
verbosity = "medium"

# 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

# Ripgrep dependency management - Auto-install ripgrep on startup for faster file search
[agent.ripgrep]
# Enable automatic ripgrep installation on startup (disable in CI/CD environments)
auto_install = true

# Preferred installation methods in order of preference
# Available: "homebrew", "apt", "cargo", "chocolatey", "scoop"
preferred_methods = [
] # Empty = auto-detect based on platform and available tools

# Skip installation cache and retry failed installations
skip_cache = false

# Installation timeout in seconds (prevents hung installations)
timeout_seconds = 300

# 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.",
    "Use the Zed Assistant to interact with VT Code's ACP integration.",
]

# 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.",
    "Try using slash commands like /logs, /status, and /doctor for diagnostics.",
]

# 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 = ""

# 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 = 100

# Maximum number of repeated identical tool calls (prevents stuck loops)
max_repeated_tool_calls = 2

# Web Fetch tool security configuration
[tools.web_fetch]
# Security mode: "restricted" (blocklist) or "whitelist" (allowlist only)
# "restricted" - Blocks known sensitive/malicious domains (default)
# "whitelist" - Only allows explicitly whitelisted domains (strictest)
mode = "restricted"

# Enable dynamic blocklist loading from external file
dynamic_blocklist_enabled = false

# Path to dynamic blocklist file (JSON format)
# File should contain: { "blocked_domains": [...], "blocked_patterns": [...] }
# Reloaded on each web_fetch call if modified
dynamic_blocklist_path = "~/.vtcode/web_fetch_blocklist.json"

# Enable dynamic whitelist loading from external file (whitelist mode only)
dynamic_whitelist_enabled = false

# Path to dynamic whitelist file (JSON format)
# File should contain: { "allowed_domains": [...], "allowed_patterns": [...] }
# Reloaded on each web_fetch call if modified
dynamic_whitelist_path = "~/.vtcode/web_fetch_whitelist.json"

# Inline blocklist - Additional domains to block (merged with default blocklist)
blocked_domains = []

# Inline whitelist - Specific domains to allow in restricted mode
# Useful for exempting legitimate services from blocklist
allowed_domains = []

# Additional blocked patterns (merged with defaults)
blocked_patterns = []

# Log all URL validation decisions for audit trail
enable_audit_logging = false

# Audit log file location
audit_log_path = "~/.vtcode/web_fetch_audit.log"

# Strict mode: Block HTTP and require HTTPS
# Disable only for testing/development
strict_https_only = true

# Specific tool policies - Override default policy for individual tools
[tools.policies]
apply_patch = "prompt"
close_pty_session = "allow"
create_pty_session = "allow"
edit_file = "allow"
grep_file = "allow"
list_files = "allow"
list_pty_sessions = "allow"
read_file = "allow"
read_pty_session = "allow"
resize_pty_session = "allow"
run_pty_cmd = "allow"
run_terminal_cmd = "allow"
send_pty_input = "allow"
update_plan = "allow"
write_file = "allow"
# Command security configuration
# Note: Safe command defaults are built into vtcode-core (80+ commands)
# This section allows adding CUSTOM commands beyond the defaults
# For the full list of safe/blocked commands, see: docs/COMMAND_SECURITY_MODEL.md
[commands]
# Add custom commands here that aren't in the built-in safe list
# Example: allow_list = ["my-custom-tool", "special-build-script"]
allow_list = []

# Add custom PATH entries for non-standard tool locations (optional)
# Note: Built-in entries already include ~/.cargo/bin, ~/.local/bin, /opt/homebrew/bin
extra_path_entries = []

# Optional: Custom environment variables for command execution
# To set custom variables, uncomment and edit:
# [commands.environment]
# RUST_BACKTRACE = "1"
# CUSTOM_VAR = "value"

# Optional: Rust-specific configuration
# To customize cargo execution, uncomment and edit:
# [commands.rust]
# cargo_timeout_seconds = 120
# cargo_environment_overrides = { CARGO_TERM_COLOR = "never" }

# Optional: Custom command patterns for project-specific tools
# All safe/dangerous defaults are built into vtcode-core
# Add project-specific patterns here:
# allow_glob = ["my-tool *", "custom-build *"]
# deny_glob = ["docker run *"]
# allow_regex = []
# deny_regex = []

# Permission system enhancements - Command resolution, audit logging, and caching
[permissions]
# Enable command resolution to actual paths (helps identify suspicious commands)
resolve_commands = true

# Enable audit logging of all permission decisions
audit_enabled = true

# Directory for audit logs (created if not exists)
# Uses ~/.vtcode/audit by default
audit_directory = "~/.vtcode/audit"

# What permission decisions to log
log_allowed_commands = true
log_denied_commands = true
log_permission_prompts = true
log_sandbox_events = true

# Permission decision caching settings
# Avoids redundant policy evaluations for repeated commands
cache_enabled = true

# Cache time-to-live in seconds (default: 5 minutes = 300 seconds)
cache_ttl_seconds = 300
enabled = true

# 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 = "compact"

# Maximum number of lines to display in tool output (prevents transcript flooding)
# Lines beyond this limit are truncated to a tail preview
tool_output_max_lines = 50

# Maximum bytes threshold for spooling tool output to disk
# Output exceeding this size is written to .vtcode/tool-output/*.log
tool_output_spool_bytes = 200000

# Optional custom directory for spooled tool output logs
# If not set, defaults to .vtcode/tool-output/
# tool_output_spool_dir = "/path/to/custom/spool/dir"

# Allow ANSI escape sequences in tool output (enables colors but may cause layout issues)
allow_tool_ansi = false

# 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 warnings for tool execution
[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 a tool runs longer than this percentage of its 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
# Increased to prevent line wrapping issues with unicode characters
default_cols = 120

# 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
# Reduced to prevent display clutter
stdout_tail_lines = 5

# Total lines to keep in PTY scrollback buffer
scrollback_lines = 100

# Preferred shell program for PTY sessions (defaults to $SHELL or auto-detect)
# preferred_shell = "/bin/zsh"

# Debug and tracing configuration - Development and troubleshooting
[debug]
# Enable structured logging for development and troubleshooting
enable_tracing = false

# Trace level: "error", "warn", "info", "debug", "trace"
# Lower levels (error) are more selective; higher levels (trace) are verbose
trace_level = "info"

# Comma-separated list of tracing targets (modules to trace)
# Examples: "vtcode_core::agent", "vtcode_core::tools", "vtcode::*"
# Leave empty to trace all targets
trace_targets = []

# Directory for debug logs (created if not exists)
debug_log_dir = "~/.vtcode/debug"

# Maximum size of debug logs before rotating (in MB)
max_debug_log_size_mb = 50

# Maximum age of debug logs to keep (in days)
max_debug_log_age_days = 7

# Context management configuration - Controls conversation memory
[context]
# 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
max_context_tokens = 90000
trim_to_percent = 80
preserve_recent_turns = 12

# Token-based truncation for tool outputs before model input
# Max tokens from a single tool result to include (head+tail strategy)
model_input_token_budget = 25000

# Secondary byte fuse applied after token truncation (in bytes)
# Provides protection against pathological cases
model_input_byte_fuse = 10240

# 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
preserve_in_compression = true

[context.token_budget]
enabled = true
model = "gpt-5-nano"
warning_threshold = 0.75
alert_threshold = 0.85
detailed_tracking = false

# 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-oss:20b-cloud"
# Model for standard tasks
standard = "gpt-oss:20b-cloud"
# Model for complex tasks
complex = "gpt-oss:20b-cloud"
# Model for code generation heavy tasks
codegen_heavy = "gpt-oss:20b-cloud"
# Model for information retrieval heavy tasks
retrieval_heavy = "gpt-oss:20b-cloud"

# 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 = true

# Maximum number of turns before asking for human input
max_turns = 100

# Tools allowed in full automation mode
allowed_tools = [
    "write_file",
    "read_file",
    "list_files",
    "grep_file",
    "run_terminal_cmd",
    "create_pty_session",
    "run_pty_cmd",
    "read_pty_session",
    "resize_pty_session",
    "close_pty_session",
    "update_plan",
    "apply_patch",
    "send_pty_input",
]

# Require profile acknowledgment before using full auto
require_profile_ack = false

# 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
# Optional: set server-side prompt cache retention for OpenAI Responses API.
# Example: "24h" will increase model-side prompt caching to 24 hours, which can
# reduce cost and latency for repeated reasoning prompts.
prompt_cache_retention = "24h"

# 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
experimental_use_rmcp_client = true
startup_timeout_ms = 30

# 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.providers]]
name = "time"
command = "uvx"
args = ["mcp-server-time"]
enabled = true
max_concurrent_requests = 3

[mcp.providers.env]

[[mcp.providers]]
name = "fetch"
command = "uvx"
args = ["mcp-server-fetch"]
enabled = true
max_concurrent_requests = 3

[mcp.providers.env]


# Agent Client Protocol (ACP) - IDE integration
[acp]
enabled = true

[mcp.allowlist]
enforce = false

[mcp.server]
enabled = false
bind_address = "127.0.0.1"
port = 3000
transport = "sse"
name = "vtcode-mcp-server"
version = "0.39.13"
exposed_tools = []

[acp.zed]
enabled = true
transport = "stdio"
workspace_trust = "full_auto"

[mcp.allowlist.default]

[mcp.security]
auth_enabled = false

[mcp.security.rate_limit]
requests_per_minute = 100
concurrent_requests = 10

[acp.zed.tools]
read_file = true
list_files = true

[mcp.allowlist.providers]

[mcp.security.validation]
schema_validation_enabled = true
path_traversal_protection = true
max_argument_size = 1048576

[hooks.lifecycle]
session_start = []
session_end = []
user_prompt_submit = []
pre_tool_use = []
post_tool_use = []

[model]
skip_loop_detection = false
loop_detection_threshold = 3
loop_detection_interactive = true

# [hooks.lifecycle]
# # Session start hook that provides project context
# session_start = [{ hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/setup-env.sh", timeout_seconds = 30 }] }]

# # Session end hook for cleanup/logging
# session_end = [{ hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/log-session-end.sh" }] }]

# # Security validation for bash commands
# pre_tool_use = [
#   { matcher = "Bash", hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/security-check.sh", timeout_seconds = 10 }] }
# ]

# # Post-tool hook to run linters and log commands
# post_tool_use = [
#   { matcher = "Write|Edit", hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/run-linter.sh" }] },
#   { matcher = "Bash", hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/log-command.sh" }] },
#   { matcher = ".*", hooks = [{ command = "$VT_PROJECT_DIR/.vtcode/hooks/log-tool-usage.sh" }] }
# ]