Herdex — VS Code client for Herdr

A native VS Code extension that surfaces your Herdr workspaces and AI coding agents in the sidebar, with live status, an interactive terminal, and editor-native actions — without leaving the editor.

⚠️ Requires Herdr installed and running. Herdex is an unofficial, community client on top of a running Herdr server (it talks to Herdr's local socket). It is not affiliated with or endorsed by Herdr. Without a running Herdr server the views stay empty and prompt you to connect.

Herdex is a VS Code client on top of Herdr's socket API, rather than a reimplementation of its runtime. The protocol it speaks is documented in docs/research/herdr-socket-api.md (verified against a live server).

Features (MVP)

• Workspaces view — hierarchical Workspace → Tab → Pane, with agent status icons and roll-up badges.

• Agents view — flat, sorted by attention (blocked → done → working → unknown → idle), with a sidebar badge when agents need you.

• Open a pane terminal — an interactive terminal for any pane, in a selectable mode (herdex.terminalMode):

  • control (default, recommended) — full width + reflow and native text selection in one terminal. Streams herdr terminal session control decoded into a VS Code terminal; --cols/--rows drive the pane PTY (reflows on resize), the decoded stream has no mouse capture (selection works), and input is delivered via pane.send_text.
  • mirror — read-only pane.read poll. Native selection, non-intrusive, width capped to Herdr's grid.
  • observe — live decoded stream (terminal session observe). Native selection, no polling, width capped.
  • attach — real herdr agent attach. Full width, but a mouse-capturing TUI (no native selection).
  • attach+mirror — attach drives width in one terminal, mirror gives selection in another.

  Switch with "Herdex: Select Terminal Mode…".

• Commands

  • Start Agent (pick a shell pane + agent kind from Herdr's manifests)
  • Focus Agent / Open Pane Terminal
  • Prompt Agent / Send editor selection to an agent
  • Stop Agent (sends an interrupt)
  • Reconnect / Refresh

• Live connection status in the status bar, with auto-reconnect.

How it works

VS Code extension ("Herdex")
  runtime/  → NDJSON over ~/.config/herdr/herdr.sock
  model/    → session tree (hydrate from session.snapshot, apply events)
  views/    → TreeDataProviders
  terminal/ → pane terminals (control / mirror / observe / attach; pane.send_text input)
  commands/ → editor + tree actions
        │
        ▼
Herdr server (owns PTYs, agents, detection, state)

Because Herdr does not push continuous agent-status changes or terminal output on global subscriptions, the extension:

• reacts to global topology events instantly (create/close/focus/agent detected),
• polls session.snapshot (default 2s) to keep agent status live,
• polls pane.read while a terminal mirror is open.

See the API reference doc for the (hard-won) details.

Requirements

• Herdr installed and running locally (herdr status shows a running server).
• VS Code ^1.85.

Develop

npm install
npm run build        # bundle to dist/extension.js
npm run typecheck

Press F5 (Run Herdex Extension) to launch an Extension Development Host.

Settings

Status & direction

Phase 1 MVP, verified end-to-end against a live Herdr server (connect, hydrate, stable event stream, agent detection, interactive terminals, workspace management).

Architecture is settled: Herdex stays a VS Code-native client on top of Herdr. Herdr remains the source of truth for PTYs, agents, detection, and session state — the extension does not (and will not) build its own runtime/session-manager. This requires Herdr installed and running, and couples Herdex to Herdr's socket protocol (see docs/research/herdr-socket-api.md).

Next up is Phase 2 — editor-native workflows (send selection/file to an agent, diff review, worktrees, blocked/done notifications, jump-to-agent). The "independent runtime daemon" idea from the project notes is intentionally not planned.