Skip to content

Getting Started

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

Getting Started

This guide helps you get VT Code up and running in your terminal.

Prerequisites

  • Rust 1.88+ (only required to build from source; the Homebrew/installer paths need no Rust)
  • Git for version control
  • macOS, Linux, or Windows (WSL2)

Installation

Option 1: Homebrew

brew trust vinhnx/tap
brew install vinhnx/tap/vtcode

Option 2: Install script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

This also installs ripgrep and ast-grep for search and structural analysis.

Option 3: Build from source

git clone https://github.com/vinhnx/vtcode.git
cd vtcode
cargo build --release
# Binary at target/release/vtcode

Set Up Your API Key

VT Code stores secrets in your OS keyring (never in a workspace .env):

# From the TUI
/secret add gemini

# From the command line
vtcode secret add openai

The first-run wizard auto-discovers keys already in your shell environment or keyring and tells you exactly which source it found. If you paste a new key, input is hidden and you get a masked preview to confirm before saving.

Provider-specific env vars also work (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, ZAI_API_KEY, MOONSHOT_API_KEY, STEPFUN_API_KEY, MINIMAX_API_KEY, ...).

No provider key at all? Local models (Ollama, LM Studio, llama.cpp) need no key — see Local-Models.

Initialize and Launch

cd /path/to/your/project
vtcode init    # scaffolds vtcode.toml, .vtcode/, and AGENTS.md
vtcode         # launch the interactive TUI

WORKSPACE_DIR tells VT Code which folder is its primary context. The CLI sets this automatically from your current directory; override it with vtcode <path> or --workspace-dir.

Your First Session

Try asking things like:

  • "Analyze this codebase"
  • "Add error handling to the user authentication"
  • "Refactor this function to be more readable"

Command-line queries

vtcode ask "Write a Python function to calculate Fibonacci numbers" > fib.py

vtcode ask sends the raw response to stdout and metadata to stderr, so it pipes cleanly into other tools. Use vtcode exec --json for a stream of structured events.

Resume Sessions

  • vtcode --resume — picker of recent sessions
  • vtcode --resume <SESSION_ID> — jump to a known session
  • vtcode --continue — resume the most recent session automatically

Next Steps

Clone this wiki locally