vtcode 0.118.0

Table of contents

• Table of contents
• What is VT Code?
• Core capabilities
• Install
  • macOS and Linux
  • Windows PowerShell
  • Package managers
• Quick start
• Model promotions
  • Xiaomi MiMo V2.5 Series
• Configuration
  • Atlas Cloud
• Extension points
  • Skills
  • MCP
  • Agents and editors
• Safety model
• Protocols and exports
• Benchmarks
• Documentation
• Contributing guide
  • For AI agents
  • For human contributors
• Development
• Contributing
• Support
• Star History
• License

What is VT Code?

VT Code is an open-source coding agent for the terminal. It combines a model-driven reasoning loop with a local harness that can read files, search code, edit safely, run commands, preserve context, resume sessions, and connect to external tools.

The default workflow is intentionally simple: one reliable agent loop, explicit delegation for bounded side work, and a workspace-first security model.

Core capabilities

Install

macOS and Linux

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

Skip optional search tools:

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

Windows PowerShell

irm https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.ps1 | iex

[!NOTE] Windows release artifacts are best-effort and may lag behind macOS/Linux builds.

Package managers

cargo install vtcode
brew install vtcode

# Development tap
brew tap vinhnx/tap
brew install vinhnx/tap/vtcode

[!TIP] Official macOS/Linux release archives include ghostty-vt/ runtime libraries for richer PTY snapshots. Custom installs continue to work with the built-in legacy_vt100 backend.

More details: Installation Guide, Native Installer Guide, Ghostty VT Packaging.

Quick start

Set a provider key and launch VT Code in a project:

export OPENAI_API_KEY="sk-..."
vtcode

Common commands:

vtcode ask "write a Rust factorial function" > factorial.rs
vtcode exec "summarize the current git diff"
vtcode --resume
vtcode --continue

VT Code keeps primary output on stdout and sends logs, metadata, reasoning traces, and prompts to stderr. This keeps ask and exec useful in shell pipelines.

Model promotions

Xiaomi MiMo V2.5 Series

Xiaomi's MiMo V2.5 Pro is the default model in VT Code — available as the native MiMo provider and through OpenRouter. It delivers strong performance in agentic capabilities, complex software engineering, and long-horizon tasks with a 1M context window and deep reasoning.

Pricing: Pay-as-you-go · Subscription · Quick Access

Read: Xiaomi MiMo documentation | OpenRouter models.

Configuration

Most settings live in vtcode.toml. Runtime overrides use --config key=value.

[agent]
provider = "openai"
default_model = "gpt-5.4"

Atlas Cloud

Atlas Cloud is a new LLM provider in VT Code. It works through VT Code's [[custom_providers]] support, so you can point VT Code at https://api.atlascloud.ai/v1 without adding a dedicated runtime provider.

[agent]
provider = "atlascloud"
default_model = "deepseek-ai/DeepSeek-V3-0324"

[[custom_providers]]
name = "atlascloud"
display_name = "Atlas Cloud"
base_url = "https://api.atlascloud.ai/v1"
api_key_env = "ATLASCLOUD_API_KEY"
model = "deepseek-ai/DeepSeek-V3-0324"

Other custom OpenAI-compatible providers use the same [[custom_providers]] pattern.

Recommended validated Atlas chat model pool examples for default_model or vtcode ask --model <model-id> include:

• deepseek-ai/DeepSeek-V3-0324
• deepseek-ai/deepseek-r1-0528
• moonshotai/Kimi-K2-Instruct
• Qwen/Qwen3-Coder
• google/gemini-2.5-flash
• openai/gpt-5.2-chat
• anthropic/claude-opus-4.5-20251101
• zai-org/glm-4.7
• minimaxai/minimax-m2.1
• xai/grok-4-0709

Useful configuration docs:

• Provider Guides
• Configuration Precedence
• Config Field Reference
• Tool Configuration
• Lifecycle Hooks

Extension points

Skills

VT Code discovers repository, user, admin, and bundled system skills using the open Agent Skills SKILL.md format.

vtcode skills list
vtcode skills info my-skill
vtcode skills create my-skill
vtcode skills validate ./.agents/skills/my-skill

Read: Agent Skills Guide.

MCP

VT Code can connect to external MCP servers over stdio or HTTP transports. It can also expose curated tools through its embedded MCP server. The MCP config covers providers, concurrency, timeouts, allowlists, UI rendering, auth, rate limits, and validation.

Read: MCP Integration Guide.

Agents and editors

• Subagents
• Agent Client Protocol and Zed
• IDE Downloads
• IDE Troubleshooting

Safety model

VT Code uses layered controls for shell and filesystem access:

• Command allowlist
• Per-command argument validation
• Workspace path normalization and symlink checks
• Dangerous command blocking
• Optional sandbox integration
• Human approval gates
• Auditable execution logs

The model is designed to reduce prompt injection, argument injection, workspace escape, and privilege escalation risk while keeping developer workflows practical.

• Security Model
• Command Security Model
• Execution Policy
• Sandbox Deep Dive
• Tool Policies

Protocols and exports

Benchmarks

VT Code has a pending submission to vercel/next-evals-oss, the benchmark behind the Next.js AI Agent Evaluations leaderboard.

Read: benchmark notes, eval framework.

Documentation

Start here:

• Documentation Hub
• Documentation Map
• Getting Started
• Interactive Mode
• Commands
• Exec Mode
• Context Engineering
• Architecture
• Development
• FAQ

Ask docs assistants: Google Gemini CodeWiki or Devin DeepWiki.

Contributing guide

Whether you are an AI agent or a human contributor, read this section before opening a PR.

For AI agents

If you are an AI coding agent (Claude Code, Cursor, Copilot, Codex, or similar), read AGENTS.md before making changes. It is the authoritative source for workspace conventions.

Rules (non-negotiable):

• Conventions: Conventional Commits (type(scope): subject), 4-space indentation, snake_case functions, PascalCase types, anyhow::Result<T> with .with_context().
• API contract: vtcode-exec-events::ThreadEvent is the authoritative runtime event type. Do not invent parallel types. Harness config lives in agent.harness, automation.full_auto, context.dynamic -- do not add new top-level harness subsystems.
• Keep changes surgical. Preserve existing APIs unless the task requires a change. Do not reformat files you are not editing.

Verification workflow:

CI sets RUSTFLAGS="-D warnings" and uses --locked. Match locally.

Workspace layout:

~20 crates. Key crates: vtcode (binary/CLI), vtcode-core (agent loop, tools, LLM orchestration), vtcode-tui (TUI surface), vtcode-llm (provider abstraction), vtcode-config (config schema). Each crate has its own AGENTS.md with crate-specific guidance.

Session memory: .vtcode/memory/ (gitignored) stores cross-session learnings. Read gotchas.md and decisions.md at session start when context is needed.

Output discipline: Cap large command output: COMMAND 2>&1 | head -c 4000.

For human contributors

Getting started:

1. Fork the repo and clone your fork.
2. Install Rust (stable). The project uses rust-toolchain.toml to pin the channel.
3. Run ./scripts/check-dev.sh to confirm your environment builds cleanly.
4. Pick an open issue or a good first issue.

Before you commit:

• Run ./scripts/check-dev.sh (fast) or ./scripts/check-dev.sh --test (thorough).
• Use Conventional Commits: type(scope): subject. Example: fix(tools): handle empty glob result.
• Keep PRs focused. One logical change per PR is easier to review.

Where to put things:

If you are unsure, open an issue first and describe what you want to change.

Further reading:

• AGENTS.md -- workspace conventions and rules
• CONTRIBUTING.md -- detailed contribution process
• Architecture -- system design overview

Development

git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh

VT Code uses Rust stable, edition 2024, and MSRV 1.88. The dev profile disables incremental compilation (sccache). Set CARGO_INCREMENTAL=1 to override.

Local checks:

./scripts/check-dev.sh             # fast gate (clippy, fmt, check)
./scripts/check-dev.sh --test      # + unit and integration tests
./scripts/check-dev.sh --workspace # + all workspace crates
./scripts/check-dev.sh --lints     # + additional lints

Running tests:

cargo nextest run                   # parallel runner (preferred)
cargo nextest run -p vtcode-core    # single crate
cargo nextest run test_name         # single test by name

Launching VT Code:

./scripts/run-debug.sh   # debug build + launch
./scripts/run.sh         # release build + launch

Both auto-bootstrap the Ghostty VT runtime. Without it, PTY snapshots fall back to legacy_vt100.

Read: Development Setup, Testing, CI/CD.

Contributing

VT Code is an open-source project, and I would love for more people to help shape it. Whether you are fixing a typo, improving docs, reporting a bug, testing a model provider, sharing an idea, or sending code, your contribution is welcome.

If you are new here, start with open issues or good first issues. For larger changes, please read CONTRIBUTING.md and AGENTS.md first so we can keep the project easy to review and maintain together.

Support

VT Code is built in my spare time and shared freely with the community. If it helps you ship code, learn, experiment with agents, or save a few hours, a small donation helps me keep improving it.

You can support ongoing development at buymeacoffee.com/vinhnx. Stars, issues, feedback, and word of mouth also mean a lot.

Star History

If you find VT Code useful, please consider starring the repository. It helps more developers discover the project and gives the community a visible signal that the work is valuable.

License

This repository is licensed under the MIT License.