Skip to content
Docs menu

VS Code extension

Use venom from a chat panel in VS Code, with inline approvals, per-hunk keep and undo, gears in the status bar, the inbox and evidence review, over a venom serve the extension starts or one already running.

View .md

The venom VS Code extension is a chat panel for the venom agent. It starts venom serve for the window, or connects to one already running, and drives it over the HTTP and SSE API. The agent works in the folder you have open, and its permission engine, sandbox, hooks and Claude Code files apply exactly as in the terminal.

The extension sends nothing anywhere except to the venom serve URL it uses: no telemetry, no update checks, and the webview loads no remote resources.

Install

It is not on the Marketplace. From a venom source checkout, build the .vsix and install it:

make vsix                                         # clients/vscode/dist/venom-vscode.vsix
code --install-extension clients/vscode/dist/venom-vscode.vsix

Spawn mode, the default, also needs the venom CLI on your PATH (Install) and whatever your terminal venom needs to reach a model (VENOM_BASE_URL, VENOM_API_KEY). The server gets VS Code's environment. If VS Code was started from the Dock and venom isn't on that PATH, set venom.cliPath to its absolute path.

Use it

  • Chat: the Venom icon in the activity bar. Enter sends, Shift+Enter adds a line. While the agent works, a new message is queued as a follow-up; Stop aborts the run and kills a running command.
  • Tool calls appear as collapsible cards with title, status, input and output (the last 64 KiB).
  • Approvals appear inline with Allow once, Allow for session and Deny. Allow for session stores the request's rules, one per segment of a compound command, listed on the card. An unanswered request is denied when the server's approval timeout expires (60 s by default).
  • Mode (header dropdown): plan, default, accept-edits, yolo. It switches the live session; switching to yolo asks for confirmation in a modal dialog.
  • Ask venom about selection (editor context menu, or Cmd+Alt+V on macOS, Ctrl+Alt+V elsewhere): asks a question and sends @path (lines a-b), the selected text including unsaved edits, and the question.
  • Edited files open in a preview editor without taking focus, unless venom.revealEdits is off. Each changed file has a diff link.
  • Changes cards list the files each turn changed (added, changed, deleted, line counts), including files bash changed.
  • Review hunks: Venom: Review Changes opens a file's diff (the text before the turn against the file on disk) with Keep and Undo above every hunk, plus Keep all and Undo all. Undo edits and saves the file; Keep hides the hunk.
  • Gear in the status bar: shows the session's gear. Click it, or run Venom: Switch Gear, to pick from the gears the server reads from venom.yaml. The session moves to the gear's model at its next turn; the choice is kept per workspace.
  • Cost: the panel's cost line and a status bar item show dollars at list price (0 for local models) and tokens in, out and cached.
  • Guardrail messages: when a guardrail stops, redacts or flags something, a notification gives the rule's code and a link to its page on your gateway.
  • Todos and subagents: the agent's todo list sits above the input; a task card lists the subagents it started with live status.
  • Images: paste or drop PNG, JPEG, GIF or WebP files on the input, at most 8 per message (about 7.5 MB each, 12 MB in all). A model that doesn't take images gets nothing, and the message returns to the input with a note.
  • Past Sessions: the sessions saved in this folder, newest first. Picking one resumes it. Chats are saved where the terminal keeps them, so venom --resume sees them too.
  • Inbox: the decisions only you can make, from every local session, most urgent first, with Approve, Reject, Request changes and Take over. It polls every 5 s while visible.
  • Evidence: the venom.evidence/v1 bundle of the folder's change, against a base ref you type.

Diffs come from venom's file checkpoints, so they are exact whatever wrote the file. No text is sent, and no diff shown, for secrets, binaries, symlinks, files over 256 KiB, or past 4 MiB of text in one turn.

Commands

All commands are in the Command Palette under Venom.

Command Title What it does
venom.focusChat Open Chat Show the chat panel.
venom.focusInbox Open Inbox Show the inbox view.
venom.focusEvidence Open Evidence Review Show the evidence view.
venom.refreshInbox Refresh Inbox Reload the inbox now.
venom.askAboutSelection Ask venom about selection Ask about the selected code (Cmd/Ctrl+Alt+V).
venom.newSession New Session Close the session and clear the chat.
venom.pastSessions Past Sessions Pick a saved session of this folder to resume.
venom.stop Stop Abort the run.
venom.reconnect Restart / Reconnect Server Start the server over, or reconnect.
venom.setServerToken Set Server Token (connect mode) Store the token in VS Code's secret storage.
venom.clearServerToken Clear Server Token Remove it.
venom.showOutput Show Log Open the extension's log.
venom.switchGear Switch Gear Pick a gear for the session.
venom.reviewChanges Review Changes (keep or undo each hunk) Open the hunk review.
venom.keepHunk Keep Hunk Keep one hunk.
venom.undoHunk Undo Hunk Undo one hunk.
venom.keepAllHunks Keep All Hunks Keep every hunk in the file.
venom.undoAllHunks Undo All Hunks Undo every hunk in the file.

Settings

Setting Default Scope What
venom.server.mode spawn machine spawn: run venom serve --root <folder> --host 127.0.0.1 --port 0 for this window. connect: use a running server.
venom.server.url http://127.0.0.1:8790 machine The server in connect mode.
venom.cliPath venom machine The executable spawn mode runs.
venom.mode default machine The permission mode new sessions start in: plan, default, accept-edits or yolo.
venom.model (server default) any The model alias for new sessions.
venom.revealEdits true any Open edited files in a preview editor.

The machine-scoped settings can't be set by a repository's .vscode/settings.json, so a cloned repository can't point the extension at another binary, send your prompts and token elsewhere, or start you in yolo. The extension also doesn't run in Restricted Mode (untrusted workspaces).

Tokens and security

  • Spawn mode makes a new 256-bit token for each server it starts and passes it in VENOM_SERVER_TOKEN (never in argv, which ps shows). The server listens on 127.0.0.1 on a free port and stops when the window closes.
  • Connect mode reads the token from VS Code's secret storage (the OS keychain), set with venom.setServerToken. It is never written to settings.json. Before sending it, the extension makes the server prove it holds the token (POST /v1/auth/proof), so another process listening on that URL gets neither the token nor a prompt. Plain http is refused to anything but a loopback address.
  • The webview's content security policy is default-src 'none': the extension's own script and stylesheet only, no network access. Model output, tool output and file names are HTML-escaped before rendering, and the markdown subset never produces links or images.

Troubleshooting

Symptom Fix
The panel says the server didn't start venom isn't on VS Code's PATH. Set venom.cliPath to its absolute path.
Connect mode sends no prompt The server didn't prove it holds the token: set it with Venom: Set Server Token, or check the URL. A venom serve from before 2026-10 can't answer the proof.
The extension does nothing in a folder The workspace is in Restricted Mode. Trust it.
Switch Gear says the server has no gears The server isn't venom serve from the CLI.
No diff links on a resumed session's earlier turns Not supported yet; diffs show for changes after the resume.