v0.1.62 MIT Windows · macOS · Linux

An agent that shows its work.

Vellum Code reads your project, makes the change, verifies it, and reports back — with the whole operation visible. GUI‑first and local‑first, MCP‑native, seven providers, and a CLI that shares the same brain.

Download for Windows See the Agents Window
Signed installer · auto-updates in-app No VSCode required Your keys stay on your machine
See it in action
Release
v0.1.62 Signed installer, auto-updating
Providers
7 One key each — bring your own
Tests green
1,176 989 main · 187 renderer
License
MIT Local-first, keys OS-encrypted
What it does

Everything visible.

A chat-first agent that reads your project, makes the change, verifies it, and reports back — with the whole operation on screen. No black boxes, no silent edits.

The Agents Window

A collapsible left sidebar, a centered chat column, and a right tool rail that collapses to a 40px icon strip. A context bar pins workspace, branch, and runners right at the composer.

Cursor-register shell

Changes panel

The working tree as a reviewable surface: staged and unstaged groups, per-hunk stage · unstage · discard, untracked previews, and a deterministic branch-and-commit that respects your selection.

Hunk-or-file → chat

Parallel sessions

Switching chats never kills a running turn. It keeps streaming in the background behind an amber dot and a live-tail hover — and returning catches you up mid-sentence.

/tell steers without switching

The agent loop, in the open

Streaming tool calls, and a live-writing view where you watch the file grow inside the tool card as the agent types. Auto-compact before you hit the wall, end-of-turn auto-verify with proof chips, a "N files changed" chip on every finished turn, stuck detection, a wall-clock watchdog, and provider failover.

Live-writing view Auto-verify Failover

Trusted apply

SEARCH/REPLACE edits with fast-model re-anchoring when the file drifted, a tsserver shadow pre-flight that surfaces diagnostics in the composer, and reject-with-instruction: tell the diff overlay how it should have been done and the retry obeys.

Shadow pre-flight Reject with instruction

Live Preview

A real browser pane in the rail. Dev-server URLs are sniffed from terminal output, runtime errors are captured, and any of them becomes a one-click fix request.

/undo and /redo

Snapshot-based rollback for the whole workspace — the coding agent's safety net, and yours. Restoring a snapshot invalidates the agent's read-state so it never works from a stale picture.

Cockpit extras

Deep PR review with a confirmed-post gate, a /fix-tests greening loop, welcome-screen task suggestions derived from churn and git status, OS notifications when you're tabbed away, and memory suggestions distilled from your own corrections.

Review

A diff that says what it meant.

Intent-Diff groups the agent's changes by purpose instead of by file. You read theses — "error handling added (3 files)" — not a wall of red and green.

  • Load-bearing groups first, and expanded. The changes that actually carry the feature are the ones you see.
  • Low-confidence groups flagged with a warning, so a weak model's guess never hides inside a tidy summary.
  • The raw diff is one toggle away — and every error path falls back to it silently rather than showing you a wrong story.
Review changes · feat/rate-limit
Rate limiting added to the upload route 3 files · +64 −9
src/main/api/rate-limit.ts +48
src/main/api/upload.ts +12−9
src/main/ipc/upload-handlers.ts +4
Coverage for the new limit 1 file · +72
src/main/api/__tests__/rate-limit.test.ts +72
Window and hit ceiling wired through env low model confidence 2 files · +6 −2
.vellum/env.yaml +4−2
src/shared/config.ts +2
diff--git a/src/main/api/upload.ts b/src/main/api/upload.ts
@@-12,7 +12,9 @@ export async function registerUpload(app: Router) {
12 app.post('/api/upload', async (req, res) => {
14 const body = await readBody(req)
14 if (!limiter.check(req.ip)) return res.status(429).end()
15 const body = await readBody(req)
16 const saved = await store.write(body)
diff--git a/src/main/api/rate-limit.ts b/src/main/api/rate-limit.ts
1const WINDOW_MS = Number(env.RATE_WINDOW_MS ?? 60_000)
2const MAX_HITS = Number(env.RATE_MAX_HITS ?? 20)
3const hits = new Map<string, number[]>()
4export const limiter = { check, reset }
Design mode

The agent looks at what it made.

Design mode turns "seeing" into a hard protocol rather than a nice idea. On every UI change the agent screenshots the result, judges it against your own written standards, and iterates until it passes.

  • A screenshot after every UI change — the agent cannot claim a visual change it never looked at.
  • Judged against .vellum/taste.md — your design standards, injected into the system prompt and used as the rubric. Spacing, contrast, states, motion.
  • A before/after receipt on the finished turn: turn start and turn end, side by side, with the verdict.
Design turn · receipt taste.md satisfied
Turn start
spacing 6px — off grid
contrast 3.1:1 on secondary text — fails
Turn end
spacing 8px — on grid
contrast 7.4:1 — passes
Fleet

Background work you can actually watch.

Every fleet task runs in its own git worktree with a real, archived chat — not a spinner you have to trust. History survives restarts, follow-ups adopt the same worktree, and dispatch is mode-aware.

  • Live log and diff overlays on any running task, plus remote runners when the work outgrows your laptop.
  • PRs end to end — review the diff, then merge or Create PR straight from the task row. Push-first, gh-backed.
  • Worktree isolation, so four agents can edit four branches without stepping on each other's working tree.
Fleet · .git/worktrees 3
fix flaky auth test wt/auth-retry running
extract settings service +412 −208 ready to merge
typecheck the eval harness wt/evals-tsc done · 8m 12s
bump electron + rebuild native needs review
Context engine

It knows the codebase before you explain it.

A semantic index over your repository — tree-sitter parsing plus embeddings — feeding an explicit, inspectable context stack. You can always see what the model was given.

Retrieval you control

Auto-context retrieval is opt-in, never a surprise. Project DNA, per-workspace memory, and a high-churn risk signal ride in the system prompt so the agent knows which files are load-bearing before it touches them.

Mentions that mean something

@codebase searches the semantic index, @docs pulls the docs you point at, and @terminal hands over the last real output. Rules cascade from CLAUDE.md and AGENTS.md.

@codebase rate limiting @docs AGENTS.md @terminal memory · 4 notes churn risk · src/main/api
<workspace> vellum-tweaks · branch feat/rate-limit
<rules> AGENTS.md → src/main/AGENTS.md (path-scoped cascade)
<retrieved> 3 files src/main/api/upload.ts · src/main/http/router.ts · src/shared/config.ts
<memory> "always run targeted vitest, not the full suite"
Safety rails

Autonomy with a fence around it.

The agent is only as useful as it is safe to leave running. Every rail here is a real gate in the main process, not a warning label.

Diff approval queue

Edits queue as reviewable diffs. Approve, reject, or reject with an instruction the retry must obey.

Permission rules

Per-tool and command-pattern allow / ask / deny in .vellum/permissions.yaml — glob-matched, checked before anything runs.

Danger gate

22 catastrophic command patterns — recursive deletes, force-push, dropped tables — drop to a one-shot approval even in bypass mode.

Privacy redactor

An egress allowlist plus pre-send scrubbing. Shared transcripts are cleaned of secrets before they leave the machine.

Read-only folders

Attach a reference repo as read-only, and the path-traversal-hardened workspace service keeps it that way.

Loopback-only API

vellum serve binds 127.0.0.1 with bearer tokens. Nothing is listening on your LAN.

rm -rf ./build Blocked for a one-shot confirmation — even with approvals bypassed.
Two surfaces, one brain

Same agent, headless when you want it.

The desktop app and the CLI share the same engine, the same workspace config, and the same permissions. Script it in CI, or live in the TUI — your choice, not a rewrite.

  • An interactive TUI built on ink, for people who never want to leave the terminal.
  • Single-shot mode with NDJSON, so an agent turn is just another step in your pipeline.
  • vellum doctor gives you a health snapshot of providers, index, and workspace when something smells off.
bash — vellum v0.1.62
$ vellum
Interactive TUI — the default. Full agent loop, in your terminal.
$ vellum task "fix the failing upload test" --json
Single-shot, non-interactive. --json streams NDJSON, one event per line.
$ vellum serve
Localhost HTTP API on 127.0.0.1 with bearer tokens.
$ vellum init
Scaffolds .vellum/ — mcp, rules, skills, taste.md, env.yaml.
$ vellum doctor
Health snapshot: providers reachable, index fresh, workspace sound.
Providers

Bring your own key.

Seven providers behind one agent loop, with automatic failover when one stalls. Cloud frontier models or a local Ollama box — the agent doesn't care which.

Keys are stored with OS-level encryption — DPAPI on Windows — never in plain JSON. Nothing routes through a Vellum server, because there isn't one.

Anthropic OpenAI Google OpenRouter Groq DeepSeek Ollama local

Local-first by construction

Sessions, snapshots, the semantic index, and task history all live in a local SQLite database. The only traffic out is the request you asked for, filtered through the egress allowlist.

Workspace config

A repo that teaches the agent.

Everything the agent should know about your project lives in a committed .vellum/ directory. Reviewable, diffable, and shared with the whole team — including the CLI.

File Purpose
taste.md Your design standards — injected into the system prompt and used to judge UI screenshots.
env.yaml Worktree setup commands, extra allowed hosts (including localhost, for screenshots), environment variables.
permissions.yaml Per-tool and command-pattern allow / ask / deny rules.
mcp.json MCP servers over stdio or SSE — tools and resources the agent can call.
rules/*.md Path-scoped prompt rules, applied only where they're relevant.
skills/*.md Project-local skills the agent can load on demand.
architecture.yaml Layer and import rules, validated at diff time so an edit can't quietly break your boundaries.
Why it's built this way

Familiar shell. Broader ambition.

The window will feel like home if you already live in a Cursor-class editor. What sits underneath it is aimed past autocomplete: an agent you can supervise, script, isolate, and audit — on your machine, with your keys, under your rules.

01

Visible by default

Tool calls stream, files grow as they're written, and every finished turn carries its own proof. Trust is earned on screen, turn by turn.

02

Local-first, BYOK

Your sessions, index, and keys stay on your disk. There's no Vellum cloud in the request path — because there is no Vellum cloud.

03

MCP-native

Model Context Protocol is a first-class citizen, not a plugin afterthought. Connect your own tools, resources, and prompts.

04

Two surfaces, one brain

The GUI and the CLI share the engine, the config, and the permission model. Automate the same agent you supervise.

05

Reviewable, not magic

Nothing lands silently. Diffs are grouped by intent, gated by approval, and reversible with a snapshot.

06

Yours to extend

MIT licensed, config-driven, and honest about its own architecture. Fork it, teach it your standards, ship it to your team.

Point it at a repo.

Install the desktop app, run vellum init, and give it a first task. It'll show you everything it does next.

Download the installer Browse the repo
npm run dev Auto-updates in-app afterwards
FAQ

The questions that matter.

Do I need a subscription?
No. Vellum Code is MIT licensed and free. You bring your own provider key and pay that provider directly — or point it at a local Ollama model and pay nothing at all.
Does it need VSCode?
No. It's a standalone Electron desktop app with its own shell, editor pane, embedded terminal, and browser. There's no extension host to install and no VSCode dependency anywhere.
Is my code sent anywhere?
Only to the model provider you configured, and only what the turn needs. The privacy redactor scrubs secrets before they leave, an egress allowlist constrains hosts, and there is no Vellum-operated server in the path.
Can I run local models?
Yes — Ollama is a first-class provider. Mix it with cloud models: route the cheap, high-volume work locally and escalate the hard turns to a frontier model.
How does it handle two tasks at once?
One session keeps streaming while you work in another, and the fleet runs background tasks in isolated git worktrees. Each fleet task gets a real archived chat, so nothing happens in a place you can't inspect.
What about very large repositories?
The context engine indexes semantically rather than stuffing the tree into the prompt. Auto-context retrieval is opt-in, layered compaction prunes at 60% occupancy before any summarizing happens, and you can attach extra repos read-only as references.