Skip to content

Configuration

Jump to bottom
Vinh Nguyen edited this page Aug 5, 2026 · 1 revision

Configuration

VT Code uses a comprehensive TOML configuration system. The vtcode init command creates a vtcode.toml file with sensible defaults.

Basic Configuration

# Agent settings
[agent]
provider = "openai"        # anthropic, google, openrouter, zai, ...
default_model = "gpt-5.4"
max_conversation_turns = 150

# Security settings
[features]
human_in_the_loop = true   # enable human-in-the-loop tool approval

# Tool policies
[tools]
default_policy = "prompt"

[tools.policies]
exec_command = "prompt"
code_search = "allow"
apply_patch = "prompt"

Command Permissions

[commands]
allow_list = ["ls", "pwd", "cat", "git status", "cargo check"]
deny_list = ["rm -rf", "sudo rm", "shutdown"]

You can also use allow_glob/deny_glob and allow_regex/deny_regex for pattern-based rules, plus approval_prefixes to skip repeated approval prompts.

Lifecycle Hooks

Execute shell commands in response to agent events. Supported lifecycle points include session_start, session_end, pre_tool_use, post_tool_use, user_prompt_submit, pre_compact, stop, subagent_start, subagent_stop, and permission_request.

[hooks.lifecycle]
pre_tool_use = [
  { matcher = "exec_command", hooks = [
    { command = "$VT_PROJECT_DIR/.vtcode/hooks/security-check.sh", timeout_seconds = 10 }
  ] }
]

Session Onboarding

[agent.onboarding]
enabled = true
include_project_overview = true
include_language_summary = true
include_guideline_highlights = true
guideline_highlight_limit = 4

Provider Governance

providers_whitelist restricts which LLM providers VT Code may access, preventing accidental data leakage in corporate or air-gapped environments:

# vtcode.toml
providers_whitelist = ["opencode-zen", "opencode-go", "gemini"]

Leave it empty (the default) to allow all built-in and custom providers.

Custom Providers

Add any OpenAI-compatible endpoint:

[[custom_providers]]
name = "mycorp"
display_name = "MyCorp"
base_url = "https://llm.corp.example/v1"
api_key_env = "MYCORP_API_KEY"
model = "gpt-5-mini"
context_window = 256000   # optional; defaults to 128000 tokens

context_window (in tokens) drives the context size shown in the UI, compaction thresholds, and preflight token checks. Use models = ["m1", "m2", ...] to expose multiple models from one endpoint.

PTY Settings

[pty]
enabled = true
command_timeout_seconds = 300

UI Extras

[ui]
vim_mode = true               # Vim-style prompt editing
theme = "ciapre"              # default theme

[ui.fullscreen]
mouse_capture = true          # in-app mouse vs terminal selection
copy_on_select = true
scroll_speed = 1.0

Context & Memory

  • agent.harness.max_budget_usd — hard cost cap; VT Code stops when the estimated API cost is reached. A warning fires at budget_warning_threshold (default 0.75).
  • agent.harness.auto_compaction_enabled — automatic context compaction under token pressure.
  • context.dynamic.retained_user_messages — how many recent user messages are kept verbatim during local compaction (default 4).
  • agent.checkpointing.* — automatic per-turn checkpoints with retention limits.

Validate Your Config

vtcode config --validate
vtcode config --reset

Related

Clone this wiki locally