Lessons from Building VT Code: An Open-Source AI Coding Agent

---

Lessons from Building VT Code: An Open-Source AI Coding Agent

VT Code is a Rust-based terminal coding agent with semantic code intelligence via Tree-sitter and ast-grep. Supports multiple LLM providers with automatic failover and efficient context management. After extensive development and iteration, I've distilled five fundamental lessons that shaped the project's design and continue to inform its evolution.

1. Architecture Determines Long-Term Viability

Early in development, I faced a critical decision: optimize for rapid prototyping or invest in modular architecture. I chose modularity, and this decision has proven foundational to the project's sustainability.

• Core separation strategy: The architecture separates vtcode-core (reusable library) from src/ (CLI implementation). This separation enables other developers to programmatically integrate VT Code's components, LLM abstractions, tool registries, execution engines, into their own Rust projects without adopting the entire agent framework.

• Agent Client Protocol integration: I implemented ACP support to decouple agents from editors, following the precedent set by the Language Server Protocol for language tooling. The current Zed IDE integration demonstrates this approach: developers can switch editors without rewriting agent logic, fostering an ecosystem where both editors and agents can evolve independently.

• Component extraction roadmap: I'm planning to extract vtcode-llm and vtcode-tools into standalone crates. This will provide reusable infrastructure that other agent developers can leverage, reducing duplicated effort across the ecosystem while maintaining clear separation of concerns.

• Strategic rationale: This architectural approach directly addresses the sustainability challenges common in open-source projects. By creating clear boundaries and reusable components, I've enabled contributions at multiple levels, from core algorithms to interface implementations, without requiring contributors to understand the entire codebase.

2. Provider Abstraction Enables Strategic Flexibility

I designed VT Code to be fundamentally provider-agnostic, supporting comprehensive LLM provider integration:

Supported ecosystem:

• Major providers: OpenAI, Anthropic, Gemini, xAI
• Regional providers: DeepSeek, Z.AI, Moonshot AI
• Aggregators: OpenRouter
• Local inference: LM Studio, Ollama

Implementation approach: The system implements a universal LLMProvider trait that handles protocol translation transparently. For example, it automatically converts OpenAI's tool_calls format to Anthropic's tool_use content blocks, ensuring core agent logic remains provider-agnostic. The abstraction also manages provider-specific optimizations: Anthropic's cache_control for performance, OpenAI's cached_tokens for cost tracking, without leaking implementation details into business logic.

Practical implications:

• Switch providers during development to optimize for specific task requirements
• Conduct A/B testing across models to identify optimal price-performance ratios
• Run entirely offline using local models for security-sensitive operations
• Avoid vendor lock-in that constrains typical AI tooling

Performance characteristics: The abstraction layer introduces approximately 50ms overhead compared to direct API calls, negligible in agent workflows where model inference dominates latency (typically 1-5 seconds per turn).

3. Structural Code Intelligence vs. Text Manipulation

I architected VT Code to treat code as structured data rather than text streams, implementing two key integrations:

Tree-sitter for parsing: The system performs incremental AST generation across Rust, Python, JavaScript/TypeScript, Go, and Java. This enables the agent to traverse code structure, identify specific nodes (functions, variables, types), and understand cross-reference relationships, capabilities impossible with pattern-matching approaches.

ast-grep for refactoring: I integrated structural pattern matching to enable semantic transformations. For example, when converting synchronous functions to async:

// Pattern matches and transforms
fn process($args) -> Result<$ret> { $body }
// Into
async fn process($args) -> Result<$ret> { $body }

The system automatically:

• Updates function signatures with async keyword
• Adjusts return type wrapping appropriately
• Identifies all call sites and adds .await
• Handles error propagation (? operator) correctly

This transformation is fundamentally impossible with regex-based approaches, which would require dozens of fragile patterns while still missing edge cases.

Key distinction: String manipulation produces chatbots that generate code. Structural comprehension produces refactoring tools. This semantic understanding gap separates demonstration projects from production-grade agents capable of modifying real codebases reliably.

4. Context Engineering as Core Infrastructure

Context window management represents the primary constraint in LLM-based systems. I've systematized this challenge through VT Code's context engineering infrastructure:

Phase-aware curation: The system dynamically prioritizes tool visibility based on execution state. During exploration phases, it emphasizes ripgrep_search and list_files. During validation phases, it prioritizes run_terminal_cmd for test execution. This reduces context allocation to irrelevant tool descriptions.

Automatic summarization: At 20 conversation turns or 85% token budget utilization, the system triggers LLM-powered summarization targeting 30% compression. The process:

• Preserves the decision ledger (critical for coherence)
• Compresses conversation history into structured fact lists
• Maintains task objectives and constraints
• Typically frees 30-40K tokens for continued execution

Real-time budgeting: I use Hugging Face's tokenizers (docs) library for precise token tracking—not estimation, but actual tokenization. This prevents silent truncation of tool outputs, API errors from oversized requests, and context window exhaustion mid-task.

Decision ledger: The system maintains a structured audit log:

struct Decision {
    turn: usize,
    reasoning: String,
    action: Action,
    outcome: Outcome,
}

This enables the agent to reference previous decisions during complex multi-turn tasks, maintaining coherence across extended sessions.

Outcome: Context management transitions from user responsibility to automated infrastructure, enabling sessions exceeding 100 turns without manual intervention.

5. Defense-in-Depth Security Architecture

Unrestricted filesystem and terminal access creates substantial security risk. I implemented multi-layered security controls as a core architectural feature:

Sandboxed execution: Integration with Anthropic's Sandbox Runtime (srt) provides isolated environments with configurable controls:

• Filesystem access modes (read-only, read-write, none)
• Network access policies (allowed domains, complete blocking, prompt-based)
• Resource limits (CPU, memory, execution time)
• Policy configuration via vtcode.toml:

[security]
default_policy = "prompt"  # deny, allow, or prompt

[security.overrides]
read_file = "allow"
write_file = "prompt"
run_terminal_cmd = "prompt"
web_search = "allow"

This enables project-specific trust profiles. Open-source exploration might allow reads and prompt writes, while production codebases might require prompts for all operations.

Path validation: The system performs strict workspace confinement via canonicalized path checking:

fn validate_path(path: &Path, workspace: &Path) -> Result<()> {
    let canonical = path.canonicalize()?;
    if !canonical.starts_with(workspace) {
        return Err(SecurityError::PathTraversal);
    }
    Ok(())
}

This prevents path traversal attacks (e.g., ../../../etc/passwd) regardless of LLM output.

Human-in-the-loop: Before executing high-risk operations (write, delete, execute), the system displays:

• Exact command or operation
• Affected files and paths
• Predicted impact
• Users maintain final approval authority before execution.

Design philosophy: This defense-in-depth approach demonstrates responsible local agent development with explicit, user-controlled trust boundaries.

---

Conclusion: Lessons from Building for the Long Term

After months developing VT Code, I've learned that building effective coding agents aren't just system prompts, they're built on engineering discipline, managed context, sandboxed execution, configurable policies.

Five principles emerged as essential:

1. Modular architecture wasn't optional. Early decisions compound over time. Separating vtcode-core from CLI implementation enables contributions without requiring system-wide understanding. This sustains projects beyond initial enthusiasm.
2. Provider abstraction protects against obsolescence. The AI landscape shifts constantly, pricing changes, models improve, options emerge. The LLMProvider trait cost development time upfront but pays dividends whenever I switch providers or test alternatives. Vendor lock-in is technical debt that kills flexibility.
3. Structural intelligence was the hardest lesson. Integrating Tree-sitter and ast-grep required significant effort, but semantic comprehension separates toys from tools. Real refactoring demands understanding structure, not pattern matching. This distinguishes "generates code" from "maintains code."
4. Context management taught me automation beats documentation. Building automatic summarization and phase-aware curation transformed VT Code from requiring constant supervision to handling extended sessions autonomously. The best interface is often no interface.
5. Security by design forced uncomfortable early decisions. Sandboxed execution, configurable policies, and path validation delayed shipping, but I wouldn't trust VT Code without them. Earning trust requires architectural justification, not warnings.
6. The broader insight: Sustainable agents are infrastructure, not experiments. This means architecture that outlasts features, abstractions enabling ecosystem growth, and security scaling with capability.

VT Code represents my conviction that developers adopt agents built with engineering discipline, modular enough to extend, flexible enough to adapt, intelligent enough to understand structure, automated enough to handle complexity, secure enough to trust.

AI capabilities evolve rapidly. Engineering foundations don't. I'm building for the latter, knowing it adapts to the former.

---

Acknowledgments

VT Code wouldn't exist without the open-source community. I'm deeply grateful to:

The foundational projects: Tree-sitter for making structural parsing accessible, ast-grep for demonstrating what semantic refactoring can be, and the Rust ecosystem for providing the infrastructure this project builds on.

The AI research community: Anthropic, OpenAI, and others major AI frontier research labs pushing forward agent capabilities and sharing their findings. The Sandbox Runtime integration and Zed Inc's Agent Client Protocol protocol support reflect collaborations that strengthen the entire ecosystem.

Early contributors and testers: Those who filed issues, submitted pull requests, and provided honest feedback when VT Code was rough. Your input shaped critical architectural decisions.

The broader developer community: Everyone building agents, sharing learnings, and raising the bar for what's possible. We're collectively figuring out how to make AI tooling reliable, and that requires transparent discussion of both successes and failures.

This project stands on the shoulders of countless open-source contributors who built the tools, libraries, and protocols that made it possible.

Project: https://github.com/vinhnx/vtcode

Thank you!