VTCode copilot-instructions.md

VT Code Agent Guidelines

VT Code: Rust terminal coding agent with modular architecture, multi-LLM support (OpenAI, Anthropic, Gemini), tree-sitter parsing for 6+ languages.

Build & Test Commands

# Preferred (faster with cargo-nextest)
cargo nextest run           # Run all tests (3-5x faster)
cargo nextest run -p vtcode-core  # Single package
cargo t                     # Alias for nextest run
cargo tq                    # Quick profile (no retries)

# Standard cargo commands
cargo check                 # Fast compile check
cargo clippy                # Lint (strict Clippy rules)
cargo fmt                   # Format code

# Fallback (if nextest unavailable)
cargo ts                    # Alias for standard cargo test

Architecture & Key Modules

• Workspace: crates/codegen/vtcode-core/ (library) + src/main.rs (binary) + 9 workspace crates
• Core: llm/ (multi-provider), tools/ (trait-based), config/ (TOML-based)
• Integrations: Tree-sitter, PTY execution, ACP/MCP protocol, Gemini/OpenAI/Anthropic APIs

Code Style & Conventions

• Naming: snake_case functions/vars, PascalCase types (standard Rust)
• Error Handling: anyhow::Result<T> + anyhow::Context; NO unwrap()
• Constants: Use crates/codegen/vtcode-core/src/config/constants.rs (never hardcode, especially model IDs)
• Config: Read from vtcode.toml at runtime
• Docs: Markdown ONLY in ./docs/; use docs/models.json for latest LLM models
• Formatting: 4-space indentation, early returns, simple variable names
• Ownership first: Prefer owned values and borrows; reach for Rc<T> / Arc<T> only when multiple owners genuinely need to keep data alive
• Shared ownership: Rc<T> is single-threaded; Arc<T> is for cross-thread/task sharing. Prefer immutable sharing before RefCell, Mutex, or RwLock
• Cycles: Use Weak<T> / Arc::downgrade() for back-references or task-parent links so shared graphs can drop cleanly

See Also