V-Agent

A native, GPU-accelerated code editor with local-first AI.

V-Agent is a fork of Zed — it keeps Zed's Rust engine (LSP, tree-sitter, multi-cursor, vim mode, splits, git, terminal, extensions) and layers on its own identity and workflow.

V-Agent is not affiliated with, endorsed by, or sponsored by Zed Industries, Inc. "Zed" is a trademark of Zed Industries, Inc. and is used here only to identify the upstream project this is derived from. See CREDITS.md.

Install

All commands below pull the latest release — they never go stale. Browse the releases if you prefer to download by hand.

Linux

One command, any distro — detects your package manager and installs the right thing, falling back to the portable tarball on anything untested:

curl -fsSL https://raw.githubusercontent.com/otzpt/V-Agent/main/install.sh | sh

Read install.sh first if you would rather see what it does. On a distro with no native package (Void included) it installs under ~/.local and needs no root at all.

The rest of this section is the same thing done by hand.

Arch, Manjaro, EndeavourOS, CachyOS — native package:

curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-x86_64.pkg.tar.zst
sudo pacman -U V-Agent-x86_64.pkg.tar.zst

Debian, Ubuntu, Mint, Pop!_OS — .deb:

curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-amd64.deb
sudo apt install ./V-Agent-amd64.deb

Fedora, RHEL, openSUSE — .rpm:

curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-x86_64.rpm
sudo dnf install ./V-Agent-x86_64.rpm

Any distro — AppImage, no install needed:

curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-x86_64.AppImage
chmod +x V-Agent-x86_64.AppImage
./V-Agent-x86_64.AppImage

Portable tarball — unpack and run:

curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-linux-x86_64.tar.gz
tar -xzf V-Agent-linux-x86_64.tar.gz
./V-Agent-linux-x86_64/v-agent

Void Linux (glibc): the one-command installer above is the easy path, and needs no root. A native .xbps is also published. There is no xbps repository to install it from, and xbps installs from repositories only, so index the download directory first. Do not rename the file:

# The asset name carries the version, so "latest/download" cannot be used here.
ver=1.1.2
curl -LO "https://github.com/otzpt/V-Agent/releases/download/v$ver/v-agent-${ver}_1.x86_64.xbps"
xbps-rindex -a v-agent-*.x86_64.xbps
sudo xbps-install -R "$PWD" v-agent

Install a Vulkan driver too, whichever route you took. The package cannot depend on one: Void has no vulkan-driver virtual package and mesa ships no Vulkan driver of its own. Pick mesa-vulkan-radeon, mesa-vulkan-intel, mesa-vulkan-nouveau, or nvidia for your GPU. Without it V-Agent installs cleanly and then fails to start, which is a confusing way to find out.

Requirements are glibc >= 2.35 (check with ldd --version) and a working Vulkan driver (vulkaninfo --summary). The musl variant of Void cannot run these binaries under any circumstance: they are glibc-linked and the GUI has never been built against musl.

See the Void Linux guide for building the package yourself from packaging/void/template, and ROADMAP.md for what is still outstanding.

Build the Arch package yourself — from a checkout, if you would rather not trust a prebuilt binary:

git clone https://github.com/otzpt/V-Agent.git
cd V-Agent/packaging/arch
makepkg -si                  # from source (long build)
makepkg -si -p PKGBUILD-bin  # or repackage the released binary (fast)

Runtime dependencies

The .pkg.tar.zst and .deb declare their dependencies, so pacman -U and apt install pull them in automatically. The AppImage and tarball do not — they are a bare binary. If V-Agent exits immediately or complains about a missing shared library, install the runtime set by hand:

# Arch / Manjaro / EndeavourOS / CachyOS
sudo pacman -S --needed alsa-lib curl fontconfig gcc-libs git glib2 libxcb \
  libx11 libxkbcommon libxkbcommon-x11 sqlite vulkan-icd-loader wayland zstd

On Debian/Ubuntu the runtime libraries ship with any desktop install, so the AppImage normally just works. Rather than hand-install them — package names moved in Ubuntu 24.04's t64 transition, and libasound2 there is now a different package — let apt resolve the real set from the .deb:

# Debian / Ubuntu / Mint / Pop!_OS
curl -LO https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-amd64.deb
sudo apt install -y ./V-Agent-amd64.deb   # pulls in every runtime dependency

You also need a working Vulkan driver for GPU acceleration — vulkan-icd-loader plus mesa (AMD/Intel) or nvidia-utils (NVIDIA) on Arch; libvulkan1 plus mesa-vulkan-drivers on Debian/Ubuntu.

To uninstall: sudo pacman -R v-agent (Arch) or sudo apt remove v-agent (Debian/Ubuntu). The AppImage and tarball are self-contained — just delete them.

Windows

Installer (.msi) — installs to %LOCALAPPDATA%\Programs\V-Agent, no administrator rights required:

irm https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-x64.msi -OutFile V-Agent.msi
msiexec /i V-Agent.msi

Portable (.zip) — unpack and run v-agent.exe:

irm https://github.com/otzpt/V-Agent/releases/latest/download/V-Agent-windows-x86_64.zip -OutFile V-Agent.zip
Expand-Archive V-Agent.zip -DestinationPath V-Agent
.\V-Agent\v-agent.exe

macOS

Not built yet — see ROADMAP.md. Build from source meanwhile.

A note on signing

Releases are not code-signed. Windows SmartScreen will say "unknown publisher" (More info → Run anyway), and macOS would require right-click → Open. This is the absence of a paid certificate, not a defect. Every file's checksum is on the release page if you want to verify it.

Distro repositories

pacman -S v-agent and apt install v-agent from the official repositories are not available: those require the distro's own maintainers to adopt the package. The commands above install the same binaries directly.

For Arch, the AUR PKGBUILDs live in packaging/arch/ and can be built locally today with makepkg -si; publishing them to the AUR is still pending. See ROADMAP.md for the details and what a self-hosted repository would take.

What V-Agent adds on top of Zed

• Activity bar — a VS Code-style left icon rail (Explorer, Search, Git, AI, Terminal, Extensions, Settings) with true open/close toggling
• Colorful file icons — Material-style language icons in the project tree
• One-click Build & Run — press F9 and V-Agent detects the language, finds your compiler (gcc, python, node, go, rustc, …), builds and runs it. If the toolchain is missing, it offers to install it
• Local-first AI — the agent panel defaults to a local Ollama model (no API key, nothing leaves your machine). Bring your own key (Groq, OpenAI, Anthropic) for a cloud model if you prefer. MCP context servers are fully supported (see Choosing a local model)
• Agent slash commands — /model, /effort, /clear, alongside Zed's /compact and @ context (files, symbols, web fetch, threads, diagnostics)
• V-Agent branding — app icon, menus, and a dark default theme

Choosing a local model

The agent panel needs a model that supports tool calling — without it the model can read your prompt but can't open files, search, or edit anything. Many popular "coder" models are completion/fill-in-the-middle models and have no tool support at all. Check before you commit to one:

ollama show <model>   # look for "tools" under Capabilities

Model	Tools	Notes
qwen3:8b	✅	Trained for agentic use; thinking mode improves tool selection. Good 8 GB VRAM pick
qwen3-coder:30b	✅	Best local agentic coder, but ~18 GB — needs 24 GB VRAM
devstral:24b	✅	Purpose-built for agentic SWE; ~14 GB
qwen2.5-coder:7b	✅	Strong at completion, weak at deciding to use tools — often needs prompting
llama3.1:8b	✅	Tool calling fine, code ability weak
deepseek-coder-v2	❌	No tool support — completion/FIM only, cannot drive the agent

Sizing: a Q4 model needs roughly its file size in VRAM. Exceeding your card spills to system RAM and gets dramatically slower — Ollama will still run it, so slowness is usually the symptom, not an error.

Context windows are handled for you. Ollama defaults to a small context (2–4k tokens), which silently truncates tool definitions out of the prompt — the single most common reason a local model "ignores" its tools. V-Agent reads each model's real context length and sends it explicitly, so you don't have to set num_ctx yourself.

If local isn't enough: agentic coding is genuinely hard below ~14B. A practical split is a local model for completion and inline edits, with a bring-your-own-key provider (Groq's free tier is fast and runs 32B-class models) for agent mode. Local-first doesn't have to mean local-only.

Coding-time tracking (Hackatime / WakaTime) — optional

V-Agent can log how long you spend coding to Hackatime or any WakaTime-compatible service. It is off unless you deliberately set it up, and it is not enabled by any default in V-Agent.

To turn it on:

1. Get your config from hackatime.hackclub.com/my/wakatime_setup. It writes ~/.wakatime.cfg with your api_url and api_key.
2. Install the agent binary, wakatime-cli. If you've used a WakaTime plugin in another editor you already have it in ~/.wakatime/. If not, V-Agent will notice and offer to download it for you from the official wakatime/wakatime-cli releases — in a visible terminal that shows the URL and destination first.

What gets sent, and to whom: heartbeats go to the api_url in your ~/.wakatime.cfg (Hackatime, or WakaTime, or your own server) — never to V-Agent, and never to Zed. Each heartbeat contains the file path, project name, language, a timestamp, and whether it was a save. Your file contents are never sent. Sending is handled by wakatime-cli itself, the same agent every other WakaTime editor plugin uses.

What V-Agent does, precisely: on save, and on opening or switching files (throttled to one heartbeat per file per two minutes), it runs wakatime-cli with the file path and a timestamp. That is the entire integration. V-Agent does not read your config, does not hold your API key, and makes no network requests of its own.

What wakatime-cli does beyond that — worth knowing, and not V-Agent's doing. The agent is a separate program with its own behaviour. From version 2.21 it scans local transcript logs from AI coding tools (Claude Code, Codex, Amp, Continue, Cody, Roo Code) to attribute AI-assisted line changes, and reports a count of changed lines. It reads those transcripts on your machine whether the editor is V-Agent, VS Code, or anything else with a WakaTime plugin. If you would rather it did not, that is a conversation with WakaTime, not with V-Agent — but you should know it happens rather than discover it.

wakatime-cli also maintains an offline queue and its own logs under ~/.wakatime/. Run it with --verbose --log-file <path> to see exactly what it collects and sends.

To turn it off: delete or rename ~/.wakatime.cfg. V-Agent then does nothing at all — no network calls, no prompts, and wakatime-cli is never invoked.

Building from source

Everyone needs Rust (stable), protoc and CMake. Then the platform bits below.

1. Get the code

git clone https://github.com/otzpt/V-Agent.git
cd V-Agent

2. Install build dependencies

Arch / Manjaro:

sudo pacman -S --needed base-devel rustup cmake clang lld llvm protobuf \
  vulkan-icd-loader wayland libxkbcommon libxcb fontconfig freetype2 \
  alsa-lib libgit2 sqlite zstd pipewire
rustup default stable

Debian / Ubuntu:

sudo apt update && sudo apt install -y \
  build-essential cmake clang lld llvm pkg-config protobuf-compiler \
  libvulkan1 libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libx11-xcb-dev libxcb1-dev libfontconfig-dev libfreetype6-dev \
  libasound2-dev libgit2-dev libsqlite3-dev libzstd-dev libssl-dev \
  libglib2.0-dev libva-dev pipewire xdg-desktop-portal

(Or just run script/linux, which detects your distro and installs the set.)

Windows: install the Windows 10/11 SDK (for rc.exe), plus protoc and CMake on PATH. If the icon-embedding step cannot find rc.exe, point it at the SDK:

$env:ZED_RC_TOOLKIT_PATH = "C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64"

3. Build

cargo build --release --bin v-agent

The binary lands in target/release/v-agent (v-agent.exe on Windows). A full build takes roughly 15–40 minutes depending on the machine.

Run it straight from the target directory:

./target/release/v-agent .

4. Optional — build the installers

Windows .msi (needs the WiX dotnet tool):

dotnet tool install --global wix
pwsh packaging/windows/build-msi.ps1 -TargetDir target -OutFile V-Agent.msi

The Linux .deb, .AppImage and Arch .pkg.tar.zst are produced by the release workflow — see .github/workflows/release.yml for the exact steps if you want to reproduce them locally.

Contributing back

git checkout -b my-change
# ... edit ...
cargo build --release --bin v-agent   # make sure it still builds
git commit -am "Describe the change"
git push origin my-change

Then open a pull request. See CONTRIBUTING.md — changes to the underlying editor are often better sent upstream to Zed.

License

V-Agent is a derivative work of Zed, which is licensed under GPL-3.0-or-later. Accordingly, V-Agent is released under GPL-3.0-or-later — see LICENSE-GPL. Portions of the codebase (GPUI and other libraries) are Apache-2.0 — see LICENSE-APACHE.

Third-party attribution — Zed, One Dark, Nightfox/Carbonfox, and the Material Icon Theme — is documented in CREDITS.md.