vtcode.toml.example

# 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
allow_list = [
    "ls",           # List directory contents
    "pwd",          # Print working directory
    "git status",   # Show git status
    "git diff",     # Show git differences
    "cargo check",  # Check Rust code
    "echo",         # Print text
]

# Additional directories to prepend to PATH when running commands
extra_path_entries = [
  "$HOME/.cargo/bin",
  "$HOME/.local/bin",
  "/opt/homebrew/bin",
]

# Commands that are never allowed
deny_list = [
    "rm -rf /",        # Delete root directory (dangerous)
    "rm -rf ~",        # Delete home directory (dangerous)
    "shutdown",        # Shut down system (dangerous)
    "reboot",          # Reboot system (dangerous)
    "sudo *",          # Any sudo command (dangerous)
    ":(){ :|:& };:",   # Fork bomb (dangerous)
]

# Command patterns that are allowed (supports glob patterns)
allow_glob = [
    "git *",        # All git commands
    "cargo *",      # All cargo commands
    "python -m *",  # Python module commands
]

# Command patterns that are denied (supports glob patterns)
deny_glob = [
    "rm *",         # All rm commands
    "sudo *",       # All sudo commands
    "chmod *",      # All chmod commands
    "chown *",      # All chown commands
    "kubectl *",    # All kubectl commands (admin access)
]

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

# Memory System Configuration - Three-tier memory for conversation persistence
[memory]
# Enable memory system
enabled = true

# Maximum turns in working memory (last N turns with full fidelity)
working_memory_limit = 20

# Maximum summaries to retain (compressed older turns)
summary_limit = 100

# Enable background summarization (async, zero user latency)
enable_background_summarization = true

# Auto-checkpoint periodically for session persistence
auto_checkpoint = true

# Checkpoint interval in seconds (300 = 5 minutes)
checkpoint_interval_seconds = 300

# Directory for session logs (leave empty for default: ~/.vtcode/sessions)
# log_directory = "~/.vtcode/sessions"

# Optional: specific model for summarization (leave empty to use default)
# summarization_model = ""

# Procedures - Procedural guidance for LLM agents
[memory.procedures]
# Enable procedures system
enabled = true

# Directories to scan for procedures (relative to workspace root)
# Procedures are markdown files that guide LLM behavior on common workflows
# Default: docs/procedures (project procedures) and .vtcode/procedures (user procedures)
paths = ["docs/procedures", ".vtcode/procedures"]

# Optional: Add additional directories
# paths = ["docs/procedures", ".vtcode/procedures", "custom/procedures"]

# Vector Database Configuration - Semantic search foundation
[vectordb]
# Backend to use: "memory" (in-memory, default) or "qdrant" (future)
backend = "memory"

# Collection name prefix for vector storage
collection_prefix = "vtcode"

# Embedding dimensions (384 for default embedding model)
embedding_dimensions = 384

# Qdrant Configuration (for future use with external vector database)
# [vectordb.qdrant]
# url = "http://localhost:6333"
# api_key = ""

# 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