Skip to content

FAQ

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

FAQ

Common questions about VT Code usage and behavior.

API Keys

Where does VT Code store my API keys?

In your OS keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service) by default — never in a workspace .env. Add keys with /secret add <provider> in the TUI or vtcode secret add <provider> on the CLI. You can also use environment variables or a workspace .env.

My API key isn't being picked up

echo $GEMINI_API_KEY          # check if it's set in your shell
/secret add gemini            # or store it via the TUI

Terminal & TUI

Characters look weird (boxes, )

VT Code assumes a Nerd Font for box-drawing and icon support. Install one from Nerd Fonts.

How do I pipe output to other tools?

VT Code separates data (stdout) from metadata/logging (stderr), so piping works cleanly:

vtcode ask "code for a fibonacci function" > fib.py
vtcode exec --json    # stream of structured events

Why don't I see duplicate key events on Windows?

VT Code filters key events to only process KeyEventKind::Press, avoiding duplicates from both press and release — cross-platform compatible.

Can I change font size in VT Code?

No — that's a terminal emulator setting. VT Code adapts to the terminal's actual size via resize events.

What should I configure for tmux?

set -g mouse on

Enable tmux mouse support for wheel scrolling and click actions inside fullscreen rendering. Avoid fullscreen mode with tmux -CC (iTerm2 control mode).

Configuration & Debugging

How do I validate or reset my config?

vtcode config --validate
vtcode config --reset

How do I enable debug logging?

RUST_LOG=vtcode_core=debug,vtcode=debug vtcode

Or in vtcode.toml:

[debug]
enable_tracing = true
trace_level = "debug"
trace_targets = ["vtcode_core", "vtcode"]

How do I control session cost?

Set agent.harness.max_budget_usd to cap estimated API spend; VT Code stops the session when the cap is reached and warns at budget_warning_threshold (default 0.75).

Behavior

Is VT Code a library or framework?

VT Code is a tool/agent. However, vtcode-core is a reusable Rust library, and vtcode-battery-pack provides a curated set of crates for embedding in your own projects.

What frame and tick rate does the TUI use?

60 FPS frame rate and 4 Hz tick rate by default.

Can I use VT Code in a pipe / non-TTY?

Yes. VT Code detects when stdout is a pipe and adapts — full TUI when a terminal is available, text output when piped.

How do I use scheduled reminders?

VT Code recognizes phrases like remind me at 3pm to ... and in 45 minutes, .... Session-scoped scheduled prompts fire only at idle boundaries so they never interrupt an in-flight turn.

Troubleshooting

Build issues

cargo clean
cargo build --release
rustc --version   # check Rust version

Local model won't generate

Local generation usually fails because the server is stopped or the model isn't loaded. Run /local status, then /local start <provider>, and use /local troubleshoot for guided diagnostics. See Local-Models.

Getting Help

Related

Clone this wiki locally