---
title: VS Code extension
description: 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.
section: integrations
order: 20
audience: [user, operator]
sources: [clients/vscode/README.md, clients/vscode/package.json, clients/vscode/src/extension.ts, clients/vscode/src/core/spawn.ts]
features: [integrations.vscode]
---

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 {#install}

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

```bash
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](/docs/getting-started/install.md)) 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 {#use}

- **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 {#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 {#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 {#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 {#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. |

## Related

- [Server API](/docs/server-api.md): what the extension talks to.
- [The inbox](/docs/automation/inbox.md).
- [Gears](/docs/configuration/gears.md).
