Hermes Agent for VS Code

A native VS Code interface for the Hermes Agent CLI (Nous Research). It does not reimplement the agent: it speaks ACP (JSON-RPC over stdio) to hermes acp, so it uses the same config (~/.hermes), providers, models, skills, MCP servers, memory and toolsets as the CLI. Nothing the CLI can do becomes unreachable — whatever ACP does not expose falls back to the integrated terminal.

Status: milestones M1–M8 done (ACP connection, streaming chat, reasoning, tool calls, native diff, approvals, pickers, context meter, chips, parallel sessions, prompt queue, Manage panel, plan, working set and the CLI escape hatches). M9 (visual pass across the 4 themes, keyboard/screen reader and Remote) is partial — see docs/ARCHITECTURE.md §10. See docs/ARCHITECTURE.md (milestones and verified gaps) and docs/UX.md (wireframes).

MIT licensed · 4 languages (en, pt-BR, ru, zh-CN) · no hardcoded colors.

The in-repo docs (docs/, CHANGELOG.md, CONTRIBUTING.md) are written in Portuguese for now; this README is the English entry point.

Requirements

• Hermes Agent installed with a provider configured (hermes model). Windows only through WSL2.
• The ACP extra enabled: hermes acp --check must answer Hermes ACP check OK.
• Node 18+ and VS Code 1.100+ (developed and tested on 1.141.0).

Installation

git clone https://github.com/Danil0ws/hermes-agent-for-vscode.git ~/Dev/hermes-for-vs-code
cd ~/Dev/hermes-for-vs-code
export NODE_ENV=development   # devDependencies are required to build
npm install
npm run build                 # tsc --noEmit + esbuild (extension host) + vite (webviews)

Then open the folder in VS Code and press F5 (Extension Development Host), or package it:

npm run package               # produces hermes-agent-for-vscode-<version>.vsix
code --install-extension hermes-agent-for-vscode-0.1.0.vsix

Usage

1. Click the Hermes icon in the Activity Bar → the Chat view.
2. Start is the single control until a session exists: the centred block in the middle of the panel (title, one line on what the click does, and the button with a spinner while it runs). Before that nothing else in the panel is interactive — no toolbar, the field is disabled and says so, and the tab strip's +/worktree buttons are inert.
3. Once started the toolbar appears (+ for context, mode and model) and typing works (Enter; Shift+Enter for a newline; Esc cancels the turn). The send button sits inside the field (bottom right, text only); it opens the same menu — send, queue, steer, interrupt.
4. Attachments: the chips above the field carry what goes to the model. Removing one is the × (the session keeps the list, and the chip does not come back). Attaching a selection or a file also writes a textual reference (`.vscodeignore:4`) into the field, at the caret, so the prompt says where the content is. Paste works in the field: files/folders copied from Finder attach as chips, a clipboard image attaches as an image block, and plain text pastes normally. An attachment over the per-chip token cap is truncated to its beginning and the chip is marked truncated — the tooltip points at the whole content.
5. Tabs: each tab is one conversation (its own session), and the tab strip is the lane indicator — a spinner while that tab's turn runs, a warning dot when it is waiting for approval. Closing a tab does not delete the session (history keeps it). The view title holds the two entry points: + (new conversation = a new tab) and the branch icon (Hermes: New Worktree and Session), which opens one in a git worktree (Commands).
6. Native menus in the view title bar: new conversation, history, restart session, open in editor, Manage (the gear), and a "…" menu with Open Full CLI, Run CLI Command…, diagnostics, log and traffic.

Commands

The Command Palette holds the full list — the table above is the day-to-day subset.

Settings (hermes.*)

Icon

The Hermes art is one file, media/hermes-agent-for-vscode.svg, used on both themes:

• Activity Bar: the manifest points at it in contributes.viewsContainers.activitybar[0].icon. The VS Code schema requires icon to be a string (the {light, dark} pair is not accepted: the whole container is dropped and its views fall back to Explorer). VS Code also does not recolor view container icons — the color comes from the file, so a single color has to work on both backgrounds.
• Marketplace: media/icon.png, 128×128 RGBA with a transparent background, exported from media/icon-source.svg. vsce refuses to publish an SVG icon ("the icon provided in package.json may not be an SVG"), hence the PNG — the SVG is still valid for the Activity Bar, which is manifest-driven.

Measured contrast (WCAG for non-text elements, 3:1 minimum):

The original pair of blues (#007ACC for light, #3B9EFF for dark) does not survive the schema: one color has to serve both backgrounds, and #007ACC measured 2.80:1 on the #333 Activity Bar. Hence #2B8AD9, same family, above 3:1 on both — and 4.5:1 on the darkest background, since the bar draws the inactive item at reduced opacity.

Honest note on size: the art carries fine detail, and at the Activity Bar's real size (16–24px) the inner strokes land around 0.2px and it reads as a silhouette. That is a legitimate brand choice; if you want more definition there, the agent glyph from @vscode/codicons is the immediate alternative.

To regenerate the PNG: export media/icon-source.svg at 128×128, RGBA, transparent background. vsce refuses SVG and requires a PNG in icon.

Publishing to the Marketplace

npx vsce package                  # produces the .vsix (no warnings)
npx vsce publish                  # needs a publisher + PAT (or Entra ID)

What still depends on you:

1. publisher — currently Danil0ws; it must match your Marketplace publisher id exactly.
2. Token — an Azure DevOps PAT with the Marketplace → Manage scope, or Entra ID authentication (vsce publish --azure-credential). Global Azure DevOps PATs are retired on 2026-12-01, so Entra ID is Microsoft's own recommendation.

repository is already in the manifest (github.com/Danil0ws/hermes-agent-for-vscode), and it is what lets vsce resolve the local art in this README: with the field present, vsce package rewrites the image to the absolute GitHub URL and passes; without it, packaging fails (not a warning). The store icon comes from package.json > icon (media/icon.png) and is independent of that.

Checked: hermes-agent.hermes-agent-for-vscode is still free on the Marketplace (name and display name have to be unique; if it were taken, publishing would fail with "already exists").

Auto-approve (YOLO)

By default Hermes asks before running commands and editing files. The policy lives in hermes.permissions and takes three values: ask (default), allowSession (repeats, for this session, what you already approved once) and allowAll (never asks).

// settings.json — same as the palette command
{ "hermes.permissions": "allowAll" }

The extension answers with the options the agent offered — it never invents a permission — and never picks a deny option. While YOLO is on, an item sits in the status bar (Hermes: approving everything, warning background) and clicking it turns it off. A restricted workspace (Workspace Trust) still wins: nothing runs.

Languages

Every user-visible string in the extension host goes through tr() and the three dictionaries (src/l10n.en.ts, src/l10n.ru.ts, src/l10n.zh-cn.ts) must cover every key — a test fails on a pt-BR literal left outside tr() and another checks the key parity, so a new string cannot ship untranslated by accident.

The extension language follows the VS Code display language (there is no picker of its own): change it in Ctrl+Shift+P → Configure Display Language and reload the window.

How it works: the manifest uses package.nls.*.json (VS Code's native mechanism, one entry per command/setting string) and the runtime uses two dictionaries — webview/*/i18n.<locale>.ts (typed by Strings, so the compiler enforces key parity) and src/l10n.<locale>.ts (a pt-BR text → translation map).

pt-BR is the source language: it holds the original strings, and a string with no translation falls back to it instead of showing a raw key. This is not vscode.l10n plus a language pack: the language comes from vscode.env.language, which reflects the installed language packs without shipping bundle.l10n.*.json files (docs/ARCHITECTURE.md §11.18 explains the choice).

Contributing

See CONTRIBUTING.md (environment, mandatory gates, one-screen architecture, the parallel-lanes pattern and the documentation rules). MIT licensed — see LICENSE.

Development

npm run compile     # tsc --noEmit (the type gate)
npm run build       # everything
npm test            # unit + integration; the integration ones spawn the real `hermes acp`
npm run watch       # esbuild in watch mode (extension host)

The integration tests use the real Hermes and are skipped when hermes is not on the PATH — they never pretend to pass. Test and command counts are deliberately absent here: they drift, and npm test counts itself.

Troubleshooting

Documentation

• docs/ARCHITECTURE.md — transport, capability→UI map, turn flow, security, milestones and the verified gaps (modes, queue, skills, MCP, effort, cost, checkpoints). (pt-BR)
• docs/ROADMAP.md — what to do about each verified gap: ordered by value over cost, with the proof that closes it, who owns it (this repo × a human at the editor × upstream) and the items deliberately left undone, with the reason. (pt-BR)
• docs/UX.md — wireframes for the composer, pickers, context meter, Manage panel and sessions, each element mapped to its data source, plus the degraded states. (pt-BR)