VTCode README

项目的 README,来自 github.com/vinhnx/VTCode。合并为一个 markdown 文件:README.md。

VT Code

Terminal-first coding agent, desktop-ready on macOS — explore, plan, edit, and verify with your model of choice.

Rust License GitHub release

Ask DeepWiki macOS 15+ arm64 and x64

VT Code Desktop app demo Desktop app

VT Code terminal TUI demo
Terminal TUI

Overview

VT Code is an auditable, resumable agentic coding loop — terminal TUI plus native macOS app, open source under MIT OR Apache-2.0 (see Contributing and License). Start with Quick start; the full map is in Documentation.

At a glance What you get
Plan Plan read-only, review turn diffs.
Safety Auditable command policy with sandboxing.
Long runs Headless exec with resume; snapshots, subagents.
Extend MCP (interop), skills, plugins.
Models Hosted or local providers per task.

Quick start

Install on macOS, Linux, or Windows/WSL, configure once, and run. Source builds need Rust 1.100.0+ (edition 2024); the installation guide covers every method.

1. Install

# Review the installer script before running it: https://github.com/vinhnx/vtcode/blob/main/scripts/install.sh
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash

Same-guide alternatives: brew install vinhnx/tap/vtcode, cargo install vtcode, Windows irm https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.ps1 | iex, or Desktop app. Verify with vtcode --version.

2. Configure your project

From your project directory:

cd path/to/your/project
vtcode init # scaffolds vtcode.toml, .vtcode/, and AGENTS.md; review before committing
vtcode secret add openai # replace `openai` with your provider

Keys stay in secure storage (OS keyring or encrypted file); env vars, workspace .env, or vtcode login work where supported. See getting started and provider guides. ChatGPT: vtcode login openai (or --from-codex); Copilot uses the official copilot CLI — see OAuth authentication.

Caution: Keep API keys out of Git and vtcode.toml, and never commit a workspace .env file.

3. Run your first task

vtcode   # open the interactive TUI

Ask one focused question, review the changes and test results, then commit. See Usage for automation and session commands.

Usage

Common commands (full list in command reference):

Goal Command
Start the TUI vtcode
Ask without tools vtcode ask "explain Rc vs Arc"
Run a task headlessly vtcode exec "refactor main.rs"
Review pending changes vtcode review
Schedule recurring work vtcode schedule create --prompt "..." --every 1h
Resume the last session vtcode continue
Resume a headless run vtcode exec resume --last "prompt"
Roll back a snapshot vtcode snapshots / vtcode revert
Inspect a run log vtcode trajectory

ask is tool-free; exec runs the full tool loop and needs workspace trust (approve the TTY prompt, or set VTCODE_TRUST_WORKSPACE=full-auto for non-TTY runs; deny refuses instead). review inspects uncommitted changes without the agent loop. For larger tasks, start read-only, review the turn diff, and use /explain without another model call. See interactive mode, exec mode, and full automation.

Desktop app

Native macOS app (macOS 15+) sharing the CLI runloop, providers, tool policy, sandboxing, sessions, config, and credentials. Configure a provider first (Quick start).

Install (macOS 15+)

brew install --cask vinhnx/tap/vtcode-desktop

Update cask installs with brew upgrade --cask vinhnx/tap/vtcode-desktop. Without Homebrew, download the latest release or run vtcode desktop --install, then launch with vtcode desktop or from Finder. The cask ships Apple Silicon builds; Intel Macs install from source with vtcode desktop --install (see installation guide).

[!WARNING] First launch needs one-time approval for ad hoc-signed builds (Homebrew cask included): open the app once from Applications, click Open Anyway in System Settings › Privacy & Security, then reopen from Finder (or vtcode desktop). The button expires about an hour after a blocked launch — reopen the app to bring it back. Notarized releases skip this. See desktop workspace.

Documentation

Start from the documentation index or Wiki. The index is canonical; this section keeps one link per task.

Start

Use

Automate

Extend

Develop

Development

26-crate workspace sketch at version 0.183.1 (full list in the architecture guide; default-members builds only the root binary, vtcode-core, vtcode-skills, vtcode-tui-runtime, and vtcode-ui):

graph LR
    BIN["vtcode binary"] --> CORE["vtcode-core harness"]
    CORE --> LLM["vtcode-llm"]
    CORE --> SAFETY["vtcode-safety"]
    CORE --> EVENTS["vtcode-exec-events (crates/common)"]
    CORE --> MEMORY["vtcode-memory"]
    CORE --> SKILLS["vtcode-skills"]
    CORE --> TUI["vtcode-tui-runtime"]
    CORE --> UI["vtcode-ui"]

Build with Rust 1.100.0+ (edition 2024; workspace version 0.183.1):

git clone https://github.com/vinhnx/vtcode.git
cd vtcode
./scripts/run-debug.sh     # build and launch a debug binary
./scripts/check-dev.sh     # fast gate: clippy, fmt, check (add --test for tests)
cargo nextest run          # tests via nextest (see testing guide)

CI uses --locked and RUSTFLAGS="-D warnings"; match locally with RUSTFLAGS="-D warnings" cargo check --locked. See development and testing.

Release binaries and notes live on GitHub releases.

Contributing

VT Code is open source and community-driven. Code, docs, evals, and fixes are welcome — include vtcode trajectory output in bug reports where possible. Before a PR, read contributing and pick a good first issue or help wanted item. Forks: keep license and third-party notices intact (see License).

Security

Report vulnerabilities privately via GitHub private vulnerability reporting. See the security policy.

Community

The Code of Conduct keeps review constructive. Contact: vinhnguyen2308 [at] gmail [dot] com.

Thanks to our contributors

Thank you to everyone below. You are the reason this project keeps moving.

View all contributors (31)

Security Advisors

@glmgbj233  @nnfrog 

Main Contributor

@kernitus 

Core Contributors

@ct-jaryn  @7jrxt42BxFZo4iAnN4CX  @xcrong  @netbrah  @Sachin-Bhat  @gzsombor  @leonj1  @chenrui333  @oiwn 

Contributors

@apewithllm  @pawurb  @f-o-x11  @shouryamaanjain  @rs545837  @georgeatparallel  @S2thend  @vivekgupta-memcode  @ericcurtin  @Sanjays2402  @diegosouzapw  @raphamorim  @TuanLe-bk18  @ForrestThump  @RobertBorg  @EvoLinkAI  @uiYzzi  @poelzi  @morler 

Resources

Support VT Code

Current sponsors: Codemod and CodeRabbit.

@codemod  @coderabbitai 

GitHub Sponsors

If you like VT Code, please star the repo and share it — starring helps discovery and brings in new users, contributors, and sponsors. Thank you for growing the community.

Star History Chart

License

First-party code is MIT OR Apache-2.0, available under either LICENSE-MIT or LICENSE (Apache-2.0). You are welcome to fork, use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the code, for personal or commercial use, under either license. Keep the license and copyright notices when you distribute copies. Third-party code keeps its original licenses, listed in THIRD-PARTY-NOTICES.

VTCode (vinhnx/VTCode)

正在搜索数据库…

914 ·GitHub
这是什么?VT Code 是一个基于 Rust 的开源编程智能体,可在终端中运行,让你在代码仓库中探索、规划、编辑和验证修改,并可使用托管或本地的 AI 模型。
这是纯命令行工具,还是带有终端界面?两者都有:它提供可脚本化的命令,如 'vtcode ask' 和 'vtcode exec',适合无界面使用;同时还提供完整的交互式 TUI(基于 ratatui/crossterm 构建),用于规划任务和查看每轮对话的代码差异。
我该如何安装并在项目中开始使用?通过官方安装脚本、Homebrew 或 Cargo 安装(Windows 下使用 PowerShell),运行 'vtcode --version' 验证安装,然后在项目文件夹中生成配置和智能体说明文件,并在运行 'vtcode' 之前添加你的服务商凭据。
可以使用哪些 AI 服务商?需要 API 密钥吗?它支持 OpenAI 等托管服务商,也支持本地模型。你可以通过 'vtcode secret add'、环境变量、工作区的 .env 文件添加凭据,或对于支持登录流程的服务商,使用 'vtcode login'。
Windows 版本是否和 macOS/Linux 版本一样稳定?支持 Windows(包括 WSL),但文档明确说明 Windows 版本属于“尽力而为”的支持,更新可能会比 macOS 和 Linux 版本慢。
我的服务商凭据是如何存储的?通过 'vtcode secret add' 添加的凭据会保存在安全存储中,可以是操作系统的密钥环,也可以是加密文件;项目也提醒不要将 API 密钥提交到 Git 或 vtcode.toml 中。
文档中提到的 HOVER 循环是什么?HOVER 是 VT Code 的自我修正循环:智能体先说明预期结果,收集有限的证据,只有当证据与预期不符时才会调整其方法。
除了 AI 模型,VT Code 还能连接哪些东西?它可以集成 MCP 服务器、Skills、插件,以及通过 ACP 连接的编辑器桥接工具,另外还有一个实验性的 WebMCP 配套功能,从而扩展智能体的工具能力,并将其能力延伸到其他编辑器中。
它能否长时间无人值守运行或执行定时任务?可以:'vtcode exec' 能在无界面模式下运行完整的工具循环,支持上下文压缩和可恢复的会话;'vtcode schedule create' 可以设置周期性的持久化提示任务。不过要实现完全自动化,需要明确信任工作区。
我能恢复或分叉之前的会话吗?可以:使用 'vtcode continue' 恢复上一次会话,使用 'vtcode continue --session-id' 分叉较早的会话,使用 'vtcode trajectory' 查看运行日志。
有哪些类似的项目?Baize, grok-build, goose, lean-ctx, oh-my-pi, kimi-code, Axl, codeAgent
作者
vinhnx
大小
179 MB
星标
914
时长
1年
提交 · 90 天