Hermes AI Agent — VS Code / VSCodium Extension

VS Code / VSCodium sidebar for the Hermes Agent runtime. Streams chat, executes tools, manages sessions, and tracks context usage over the Agent Client Protocol (ACP).

Requires the hermes CLI installed and authenticated. The extension spawns hermes acp as a local subprocess — no cloud proxy, no hosted backend.

Fork note. This repository ships from https://spacecruft.org/hermes/hermes-vscode. It is a maintained fork of joaompfp/hermes-vscode, which has an unmerged security PR and twelve open feature/bug reports with no maintainer responses. This fork picks up the XSS fix and adds more. MIT licensed; upstream authorship credited in the commit history.

Features

Chat

• Sidebar panel with streaming markdown rendering (DOMPurify-sanitized)
• Extended thinking shown as gold status line
• Inline image rendering from Hermes MEDIA:/path protocol
• Copy buttons on code blocks

Tool Use

• Tool calls displayed with kind labels (Read, Edit, Bash, Search, Fetch) and file paths
• Status: ✓ done, ⋯ running, ✗ error
• Optional auto-open for files Hermes reads/edits (off by default — see hermes.autoOpenEditedFiles)
• Dismissable / collapsible todo overlay from Hermes's todo tool (auto-collapses once all items complete)

Skills

• Skills picker (✦ button) loads from ~/.hermes/skills/
• Multi-select — injected as advisory prefix in the prompt

Slash Commands

Grouped command menu (/ button). Three dispatch modes: immediate execute, inline argument prompt, or confirmation dialog. Only commands actually handled end-to-end (by the Hermes ACP adapter or intercepted client-side by the extension) are exposed.

Section	Commands
Session	/title (client-side rename), /compact
Info	/context, /tools, /help
Danger	/reset (with confirmation)

Slash command responses render as centered system messages, not conversation bubbles.

Context & Attachments

• Active file, selection, and open tabs sent automatically
• File attachment via ⊕ button, drag & drop, or Ctrl+V paste
• Files sent as path references — Hermes reads on demand

Sessions

• Persistent across VS Code reloads (stored in workspaceState)
• Session picker: switch, create, rename, delete
• Auto-titled from first user message
• ACP session ID stored for context resume

Models

• Model picker populated dynamically from the Hermes ACP availableModels list returned by session/new — shows exactly the models your configured provider (anthropic, openai, ai-gateway / Vercel, openrouter, ollama, …) can route to. No hardcoded list.
• Switch via header dropdown or /model provider:model-id

Token Tracking

• Context usage displayed as Xk / 1M with progress bar
• Color warnings at 70% (gold) and 90% (red)

Queue & Interrupt

• Send follow-ups while busy (queued)
• New messages cancel the current turn
• Gold glow on composer while agent is working
• ArrowUp / ArrowDown recall previous prompts from the composer (shell-style history)

Requirements

• Hermes CLI installed (pip install hermes-agent)
• Hermes authenticated (hermes setup)
• VS Code 1.85+
• Remote SSH: runs on the workspace/server side (extensionKind: ["workspace"])

Getting Started

1. pip install hermes-agent && hermes setup
2. Install extension from Marketplace or .vsix
3. Open Hermes panel from the activity bar
4. Send a message

Settings

Setting	Default	Description
hermes.path	hermes	Path to the Hermes binary (machine scope)
hermes.cwd	(empty)	Working directory for Hermes. Empty ⇒ first workspace folder, then $HOME.
hermes.autoOpenEditedFiles	never	never / edit-only / always — should Hermes's reads & edits pop open as tabs?
hermes.debugLogs	false	ACP diagnostic logs in the Output channel

Architecture

Extension Host (Node.js)
├── extension.ts       — activation, wiring
├── acpClient.ts       — JSON-RPC 2.0 over stdio
├── sessionManager.ts  — ACP session lifecycle, streaming dedup
├── sessionStore.ts    — workspaceState persistence
├── chatPanel.ts       — WebviewViewProvider, message dispatch
├── htmlTemplate.ts    — HTML/CSS builder
├── protocol.ts        — typed ACP parsing
├── types.ts           — shared type definitions
└── skillCatalog.ts    — skill directory loader

Webview (sandboxed)
├── main.ts       — event handlers, send logic
├── state.ts      — state factory
├── renderers.ts  — markdown, messages, todo overlay
├── autoScroll.ts — stream-aware scroll controller
└── menus.ts      — dropdown builders (model picker, session picker, skills) + status bar

Communication: JSON-RPC 2.0 over stdio to hermes acp subprocess. Webview sandboxed with CSP + DOMPurify. Media isolated to extension storage.

Credits

• Hermes Agent by Nous Research — the AI agent runtime this extension connects to
• Agent Client Protocol (ACP) — the communication protocol between extension and agent
• marked — Markdown parsing for chat rendering
• DOMPurify — HTML sanitization for agent-generated content
• VS Code Extension API — WebviewViewProvider, workspace state, editor integration

License

MIT