VT Code는 LLM 네이티브 코드 이해 능력과 강력한 셸 안전성 (shell safety)을 갖춘 오픈 소스 코딩 에이전트입니다. 자동 장애 조치 (failover) 및 효율적인 컨텍스트 관리 (context management)를 통해 여러 LLM 프로바이더를 지원합니다.

네이티브 설치 프로그램 (권장) - 의존성 없음, 즉시 설정 가능:
기본 macOS/Linux 설치 프로그램은 향상된 시맨틱 그레프 (semantic grep) 및 프로그래밍 언어 수준의 이해를 위해 권장되는 ripgrep + ast-grep 번들을 함께 설치하려고 시도합니다 (선택 사항).

팁

공식 macOS/Linux 릴리스 아카이브에는 더 풍부한 PTY 화면 스냅샷을 위한 런타임 라이브러리인 ghostty-vt/가 포함되어 있습니다. 릴리스 버전이 아니거나 커스텀 설치 시 해당 에셋을 사용할 수 없는 경우, VT Code는 여전히 내장된 legacy_vt100 백엔드로 대체하여 작동합니다.

macOS & Linux:

curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
# 또는 설치 중 ripgrep + ast-grep 제외
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

참고

Windows 설치는 현재 최선(best-effort)을 다하는 수준이며 macOS/Linux 릴리스 빌드보다 뒤처질 수 있습니다. 현재 릴리스 파이프라인은 cross 기반의 Windows 빌드를 위해 조정 중이며, Windows 빌드 시간은 비용이 많이 들 수 있으므로 모든 릴리스에서 Windows 아티팩트(artifacts)를 사용할 수 없을 수도 있습니다.

대체 설치 방법:

# Cargo (Rust 패키지 관리자)
cargo install vtcode
# Homebrew (macOS/Linux)
...

Ghostty VT는 vtcode dependencies install ...을 통해 설치되지 않습니다.

대신, VT Code는 다음 중 하나의 방식으로 제공되는 런타임 라이브러리를 사용합니다:

• 공식 macOS/Linux 릴리스 아카이브의 ghostty-vt/ 아래에 번들로 포함됨
• 네이티브 설치 프로그램이 릴리스 설치 중에 복사함
• scripts/setup-ghostty-vt-dev.sh를 통해 개발용으로 로컬에 준비됨
• 런타임 라이브러리가 누락된 경우 ./scripts/run.sh 및 ./scripts/run-debug.sh에 의해 자동 부트스트랩(Auto-bootstrapped)됨

설치 가이드(Installation Guide), 개발 환경 설정(Development Setup), 그리고 Ghostty VT 패키징(Ghostty VT Packaging)을 참조하세요.

참고: 만약 "installed from different tap" 오류가 발생하면, 먼저 기존의 formula를 삭제하세요:
brew uninstall vtcode

그 다음, 선호하는 tap에서 설치를 진행하세요.

더 많은 옵션과 문제 해결 방법은 설치 가이드(Installation Guide) 및 네이티브 설치 가이드(Native Installer Guide)를 참조하세요.

# API 키 설정
export OPENAI_API_KEY="sk-..."
# VT Code 실행
...

VT Code는 개방형 Agent Skills 표준을 따르는 Skills(기술)에 대한 포괄적인 지원을 포함합니다. Skills를 통해 VT Code는 외부 역량을 활용하고 표준화된 기술 시스템을 통해 기능을 확장할 수 있습니다.

Skill Discovery (기술 발견): VT Code는 우선순위 처리를 통해 여러 위치에서 기술을 발견하고 로드할 수 있습니다.
Standard Compliance (표준 준수): 상호 운용성을 위해 Agent Skills 사양을 완전히 준수합니다.
Multi-Location Support (다중 위치 지원): 기술은 로컬 디렉토리, 원격 저장소 또는 임베디드 리소스에서 로드될 수 있습니다.
Extensible Ecosystem (확장 가능한 생태계): 향상된 역량을 위해 성장하는 Agent Skills 생태계와 통합됩니다.

VT Code의 기술 구현에 대한 자세한 내용은 Agent Skills 가이드(Agent Skills Guide)를 참조하세요.

VT Code는 제한된 작업(bounded work)을 포그라운드 서브에이전트(foreground subagents)에 위임할 수 있으며, 명시적으로 구성된 백그라운드 서브에이전트(background subagent)를 관리되는 서브프로세스(managed subprocess)로 실행할 수도 있습니다.

/agent 및 /agents active 명령어를 사용하면 메인 세션을 전환하지 않고도 위임된 에이전트들을 현장에서 검사할 수 있습니다.

• 백그라운드 서브프로세스는 선택 사항(opt-in)입니다. VT Code는 더 이상 사전 구성된 기본 백그라운드 에이전트를 포함하여 배포하지 않습니다.
• Ctrl+B는 [subagents.background]가 활성화되어 있고 default_agent가 설정된 경우에만 구성된 기본 백그라운드 서브에이전트를 시작하거나 중지합니다.
• /subprocesses 또는 Alt+S는 로컬 에이전트(Local Agents) 서랍을 엽니다.
• 와이드 모드 사이드바(wide-mode sidebar)는 위임된 에이전트와 백그라운드 서브프로세스를 위한 통합된 로컬 에이전트 섹션을 보여줍니다.

백그라운드 런타임(background runtime)은 [subagents.background] 아래에서 구성됩니다:

[subagents.background]
enabled = true
default_agent = "rust-engineer"
...

VT Code는 GitHub Copilot, OpenAI, Anthropic, Google Gemini, DeepSeek, OpenRouter, Z.AI, Moonshot AI, MiniMax, HuggingFace Inference Providers, Ollama (로컬 및 클라우드), 그리고 LM Studio (로컬)와 함께 작동합니다.

사용 중인 프로바이더(provider)에 해당하는 환경 변수를 설정하세요 (모든 옵션은 설치 가이드(Installation Guide)를 참조하십시오).

VT Code는 공식 copilot CLI를 통한 OAuth 디바이스 플로우(device-flow) 인증을 사용하여 GitHub Copilot에 대한 퍼스트 클래스(first-class) 지원을 포함합니다.

CLI:

# GitHub Copilot CLI 설치
brew install gh-copilot
# 인증
...

상세한 설정은 GitHub Copilot 인증(GitHub Copilot Authentication)을 참조하십시오.

VT Code는 통합을 위해 여러 에이전트 프로토콜(agent protocols)을 지원합니다:

VT Code는 Zed와 같은 코드 에디터(code editors)와 통합할 수 있습니다. 설정 및 문제 해결은 ACP 문서를 참조하십시오.

로컬 개발의 경우, ~/.local/bin에 설치된 오래된 바이너리에 의존하는 대신, 명시적인 --config 경로와 함께 레포지토리 빌드(target/debug/vtcode 또는 target/release/vtcode)를 실행하는 작은 래퍼 스크립트(wrapper script)를 Zed가 가리키도록 설정하는 것을 권장합니다.

VT Code는 에이전트 간의 통신과 상호 운용성(interoperability)을 가능하게 하는 에이전트 간(Agent2Agent, A2A) 프로토콜을 구현합니다. A2A 프로토콜은 다음을 지원합니다:

에이전트 발견 (Agent Discovery): /.well-known/agent-card.json에 있는 에이전트 카드(Agent Cards)를 통해 수행

태스크 생명주기 관리 (Task Lifecycle Management): submitted, working, completed, failed와 같은 상태(states)

실시간 스트리밍 (Real-time Streaming): 서버 전송 이벤트 (Server-Sent Events, SSE)를 통해 수행

풍부한 콘텐츠 유형 (Rich Content Types): 텍스트, 파일, 그리고 구조화된 데이터 파트

푸시 알림 (Push Notifications): 웹훅(Webhook) 기반의 비동기 업데이트

JSON-RPC 2.0: 상호 운용성을 위해 HTTP(S) 상에서 동작

A2A 프로토콜 지원에 대한 자세한 정보는 A2A 프로토콜 문서(A2A Protocol Documentation)를 참조하십시오.

VT Code는 Claude Code와 같은 도구를 포함하여 기존 애플리케이션을 VT Code에 연결할 수 있도록 Anthropic Messages API와의 호환성을 제공합니다.

서버는 다음을 지원합니다:

• /v1/messages 경로의 메시지 엔드포인트 (Messages endpoint)
• 스트리밍 응답 (Streaming responses)
• 도구 호출 (Tool calling)
• 비전 (이미지) 지원 (Vision support)
• 멀티턴 대화 (Multi-turn conversations)
• 시스템 프롬프트 (System prompts)
• 모든 주요 Anthropic API 기능

Anthropic API 호환성에 대한 자세한 내용은 Anthropic API Documentation을 참조하세요.

VT Code는 대규모 언어 모델 (LLM) API를 위한 개방형 및 벤더 중립적 표준인 Open Responses 사양을 준수합니다. 이를 통해 서로 다른 제공자(Provider) 간에 상호 운용 가능한 LLM 워크플로를 구현할 수 있습니다.

Open Responses 준수의 주요 특징:

통합 아이템 유형 (Unified Item Types): 정의된 생명주기 상태를 가진 상태 머신 (State machine) 기반 아이템
시맨틱 스트리밍 (Semantic Streaming): 원시 토큰 델타 (Raw token deltas)가 아닌 의미 있는 전환을 설명하는 이벤트
에이전틱 루프 지원 (Agentic Loop Support): 조합 가능한 도구 호출 (Tool invocation) 및 메시지 오케스트레이션 (Message orchestration)
확장 지점 (Extension Points): 네임스페이스 확장(예: vtcode:file_change)을 통한 제공자별 기능 지원

Open Responses 구현에 대한 자세한 내용은 Open Responses Documentation을 참조하세요.

VT Code는 표준화된 세션 궤적 (Session trajectory) 내보내기를 위해 Agent Trajectory Interchange Format (ATIF) v1.4를 구현합니다. ATIF는 사용자 메시지, 에이전트 응답, 도구 호출 (Tool calls), 관찰 (Observations), LLM 메트릭 (Metrics)을 포함한 전체 상호작용 이력을 디버깅, 시각화, SFT (Supervised Fine-Tuning), 그리고 RL (Reinforcement Learning) 파이프라인에서 사용할 수 있는 JSON 형식으로 캡처합니다.

전체 이력 (Complete History): 모든 에이전트 단계, 도구 호출 및 관찰 내용을 하나의 파일에 저장
LLM 메트릭 (LLM Metrics): 단계별 및 합계 토큰 사용량, 비용 및 캐시 통계
상호 운용성 (Interoperable): Harbor, OpenHands, Gemini CLI, Claude Code 및 Codex 궤적과 호환
선택적 활성화 (Opt-in): vtcode.toml 파일에서 telemetry.atif_enabled = true를 통해 활성화 가능

자세한 내용은 ATIF Trajectory Format Documentation을 참조하세요.

VT Code는 원활한 계정 기반 액세스를 위해 보안 OAuth 2.0 인증을 지원합니다:

OAuth 제공자 (OAuth Providers): PKCE로 보안된 흐름을 사용하는 OpenAI ChatGPT 및 OpenRouter
보안 토큰 저장 (Secure Token Storage): 운영체제 네이티브 자격 증명 저장소 (Keychain, Credential Manager, Secret Service)
자동 토큰 갱신 (Automatic Token Refresh): 사용자 개입 없는 투명한 토큰 갱신
폴백 암호화 (Fallback Encryption): 키링 (Keyring)을 사용할 수 없는 경우 AES-256-GCM으로 암호화된 파일 사용

상세한 설정 및 제공자 가이드는 OAuth Authentication Guide를 참조하세요.

VT Code는 풍부한 설정 옵션을 지원하며, 설정 내용은 vtcode.toml에 저장됩니다.

주요 설정 기능은 다음과 같습니다:

OAuth 설정 (OAuth Settings): 제공자별 인증 방식 및 토큰 저장 방식 제어
라이프사이클 훅 (Lifecycle Hooks): 에이전트 이벤트에 반응하여 셸 명령어를 실행 - Lifecycle Hooks Guide 참조
도구 정책 (Tool Policies): 허용, 확인 필요, 또는 거부될 도구를 제어
보안 설정 (Security Settings): Human-in-the-loop(사람의 개입) 승인 및 워크스페이스 경계 구성
성능 튜닝 (Performance Tuning): 컨텍스트 제한(Context limits), 타임아웃(Timeouts), 캐싱 동작(Caching behavior) 조정
PTY 백엔드 선택 (PTY Backend Selection): Ghostty VT가 기본 백엔드이며, 런타임 라이브러리를 사용할 수 없는 경우 legacy_vt100으로 대체됩니다.

전체 설정 옵션은 Configuration을 참조하세요.

Ghostty VT 런타임 라이브러리 패키징에 대한 자세한 내용은 Ghostty VT Packaging을 참조하세요.

VT Code는 견고하고 파이프(Pipe) 친화적인 경험을 보장하기 위해 명령줄 인터페이스 가이드라인(Command Line Interface Guidelines)과 표준 UNIX 원칙을 따릅니다:

출력 스트림 (Output Streams): 기본 출력(예: ask로부터의 코드, exec로부터의 이벤트)은 stdout으로 전송됩니다. 모든 로그, 메타데이터, 추론 흔적(Reasoning traces), 그리고 상호작용 프롬프트는 stderr로 전송됩니다. 이를 통해 vtcode 출력을 다른 도구로 안전하게 파이프(Pipe)할 수 있습니다.

생성된 코드만 파일에 저장되며, 메타데이터는 화면에 남습니다.

vtcode ask "factorial function in rust" > factorial.rs

표준 인자 (Standard Arguments): clap을 사용하여 GNU/POSIX 인자 파싱 표준을 준수하며, --help, --version, 그리고 위치 인자(Positional arguments)를 위한 -- 구분자와 같은 표준 플래그를 지원합니다.

보안 우선 (Security First): tree-sitter-bash 명령 검증, 실행 정책(Execution policy), 샌드박스 격리(Sandbox isolation)를 포함한 다층 보안 모델
OAuth 인증 (OAuth Authentication): OS 네이티브 자격 증명 저장소 및 자동 토큰 갱신을 지원하는 보안 PKCE 기반 OAuth 흐름 (docs)
멀티 프로바이더 AI (Multi-Provider AI): OpenAI, Anthropic, DeepSeek, Gemini, Z.AI, Moonshot AI, OpenRouter, MiniMax, Ollama (로컬)
의미론적 코드 이해 (Semantic Code Understanding): LLM 네이티브 코드 분석 및 탐색 (Rust, Python, JavaScript/TypeScript, Go, Java 등)
스마트 도구 (Smart Tools): 내장된 코드 분석, 파일 작업, 터미널 명령 및 리팩터링 (Refactoring)
에이전트 기술 (Agent Skills): 오픈 에이전트 기술 (Agent Skills) 표준에 맞춘, 다중 위치 지원 및 우선순위 처리를 포함하는 포괄적인 기술 위치 시스템 (docs)
에디터 통합 (Editor Integration): 에이전트 클라이언트 프로토콜 (Agent Client Protocol, ACP)을 통한 Zed IDE 네이티브 지원
라이프사이클 훅 (Lifecycle Hooks): 컨텍스트 강화, 정책 집행 및 자동화를 위해 에이전트 이벤트에 반응하여 사용자 정의 셸 명령을 실행 (docs)
컨텍스트 관리 (Context Management): 고급 토큰 예산 추적 및 컨텍스트 큐레이션 (Context curation)
TUI 인터페이스 (TUI Interface): 실시간 스트리밍을 지원하는 풍부한 터미널 사용자 인터페이스
Ghostty VT 스냅샷 (Ghostty VT Snapshots): PTY 세션은 사용 가능한 경우 Ghostty VT 런타임 라이브러리를 사용하며, 그렇지 않으면 내장된 legacy_vt100으로 대체됨

자동 업데이트 시스템 (Auto-Update System): 릴리스 채널, 버전 고정(Version pinning) 및 미러 지원을 포함한 내장 업데이트 관리자 (docs)

VT Code는 프롬프트 인젝션 (Prompt injection) 및 인자 인젝션 (Argument injection) 공격으로부터 보호하기 위해 **심층 방어 보안 모델 (Defense-in-depth security model)**을 구현합니다:

실행 정책 (Execution Policy): 명령별 인자 검증을 포함한 명령 허용 목록 (Allowlist)
워크스페이스 격리 (Workspace Isolation): 모든 작업이 워크스페이스 경계 내로 제한됨
OS 네이티브 샌드박싱 (OS-Native Sandboxing): 커널 수준의 격리를 위해 macOS Seatbelt 및 Linux Landlock + seccomp 사용
도구 정책 (Tool Policies): MCP 도구에 대해 구성 가능한 허용/거부/프롬프트 정책
인간 참여 (Human-in-the-Loop): 민감한 작업에 대해 구성 가능한 승인 시스템
감사 추적 (Audit Trail): 모든 명령 실행에 대한 포괄적인 로깅

자세한 내용은 보안 모델(Security Model) 및 샌드박스 심층 분석(Sandbox Deep Dive)을 참조하십시오.

설치 (Installation)
시작하기 (Getting started)
OAuth 인증 (OAuth Authentication)

• PKCE를 포함한 안전한 OAuth 2.0 흐름, 토큰 저장 및 자동 갱신
• 구성 (Configuration)
  업데이트 시스템 (Update System)
• 릴리스 채널, 버전 고정(version pinning) 및 업데이트 관리
  AI 프로바이더 설정 (AI Provider Setup)
• 다양한 LLM 프로바이더 구성을 위한 완전한 가이드:
  컨텍스트 엔지니어링 (Context Engineering)
  에이전트 스킬 (Agent Skills)
• 다중 위치 지원, 우선순위 처리 및 개방형 Agent Skills 표준을 포함한 포괄적인 스킬 위치 시스템.
  표준 준수 (Standard Compliance)
• VT Code가 Agent Skills 표준을 구현하는 방법

코드 인텔리전스 (Code Intelligence)
에이전트 클라이언트 프로토콜 (Agent Client Protocol, ACP)
Zed 통합 (Zed Integration)

• 에이전트 클라이언트 프로토콜(ACP) 통합. VT Code는 완전한 ACP 에이전트 기능을 갖추고 있어, Zed와 같은 ACP 클라이언트와 함께 작동합니다.
  라이프사이클 훅 (Lifecycle Hooks)
• 에이전트 이벤트에 반응하여 셸 명령을 실행함으로써 컨텍스트 강화, 정책 집행 및 자동화를 가능하게 함
  키보드 단축키 (Keyboard Shortcuts)
  macOS Alt 단축키 문제 해결 (macOS Alt Shortcut Troubleshooting)
• macOS에서 Alt/Option 단축키가 작동하지 않을 때의 해결 방법
  실행 모드 (Exec Mode)
  개발 (Development)
• 개발 환경 설정 (Development Setup)
• 테스트 (Testing)
• CI/CD
  경험적 평가 (Empirical Evaluation)
• 안전성, 논리 및 코딩 벤치마크 전반에 걸쳐 LLM 성능을 측정하기 위한 공식 프레임워크.