Herd

Docs Index

Document	What it covers
docs/quickstart.md	Fastest path from clone to a running local Herd app, plus the main dev and test commands
docs/session-and-layout.md	Session settings, saved session files, browser backend switching, tile locking, minimizing, and layout workflows
docs/architecture.md	Runtime architecture, tile/session model, networks, Root vs worker roles, messaging, and persistence
docs/keyboard-shortcuts.md	Keyboard-driven UI controls, navigation, sidebars, command bar, and close-confirmation shortcuts
docs/socket-and-test-driver.md	Detailed CLI, socket API, MCP bridge, and integration test_driver reference

Herd is an experiment platform for agent collaboration. It gives agents explicit message channels, LAN-style local service discovery over visible tile networks, a per-session Root agent that can inspect and configure the shared canvas, and browser tiles that can host local extension pages with discoverable APIs. Under the hood, Herd runs an isolated tmux server, projects terminal-backed tiles into a spatial workspace, and exposes a local socket, CLI, and MCP bridge so users and agents operate inside the same environment.

Why Herd

• Experiment with how worker agents coordinate when they communicate through explicit channels instead of hidden shared context.
• Model local collaboration as visible connected components, so service discovery and callable capabilities come from the agent’s current network rather than a global registry.
• Separate coordination from orchestration: workers collaborate locally, while a Root agent can inspect and reconfigure the shared canvas and session state.
• Keep the collaboration graph visible. Herd’s canvas makes agent placement, network topology, lineage, activity, and ownership legible instead of burying them in logs or background processes.
• Treat browser pages as first-class local tools. Browser tiles can load project-local extension pages, expose discoverable methods to agents, and return screenshots as PNG or text-oriented formats.

Mental Model

• tmux owns terminal process lifecycle and scrollback.
• Herd owns semantic state: tile identity, messaging, local networks, work ownership, activity, and canvas layout.
• A tab maps to a tmux session. Terminal-backed tiles are tmux-backed, but public control flows target Herd-owned tile_id, not tmux pane ids.
• Workers discover and call services through their visible local network. Root is the privileged coordinator for layout, lifecycle, topology, and other session-wide changes.

See docs/architecture.md for the detailed runtime model.

Stack

• Frontend: Svelte 5, TypeScript, Vite, xterm.js
• Desktop shell: Tauri v2
• Backend: Rust
• Terminal runtime: tmux control mode
• Agent bridge: Model Context Protocol (MCP) over stdio, backed by Herd's Unix socket
• Test stack: Vitest plus a typed socket-driven integration harness

Prerequisites

You need:

• Node.js and npm
• Rust toolchain
• Tauri system prerequisites for your OS
• tmux
• zsh

Optional but useful:

• socat for manually testing the Unix socket API

Development

Install root dependencies:

npm install

Build the MCP bridge if you want to use the checked-in .mcp.json entry:

cd mcp-server
npm install
npm run build
cd ..

Run the desktop app:

npm run tauri dev

That starts the Vite dev server, launches Tauri, ensures the private tmux server exists, and opens the Herd window.

For frontend-only iteration:

npm run dev

Frontend-only production bundle:

npm run build

Desktop build:

npm run tauri build

CLI

The app binary also exposes a grouped local CLI:

• installed usage: herd
• source-tree usage: bin/herd

When the app starts, it refreshes ~/.local/bin/herd to point at the installed executable. In the repo, bin/herd wraps the Rust CLI directly.

The CLI mirrors the local collaboration model: inspect tiles and networks, message agents, and let Root handle privileged session changes. See docs/socket-and-test-driver.md for the full CLI and socket reference.

Examples:

herd network list
herd tile list
herd message public "Need another pair of eyes on #delivery" --mention agent-1234
herd message channel "#delivery" "Taking the browser pass"
herd message root "Please inspect the local session and assign follow-up"
herd tile create work --title "Socket API follow-up"

Agent, channel, chatter, network, and work commands are session-private. They only expose the current tmux tab/session's registry data.

Channel chatter is subscription-gated per session. Root or local user automation can inspect channels and manage subscriptions with herd message channel list, herd message channel subscribe, and herd message channel unsubscribe. The full command surface is documented in docs/socket-and-test-driver.md.

Browser Tiles And Extensions

Browser tiles can host normal web content, local files, or built-in extension pages under extensions/browser/. The repo currently ships browser-playable pages including checkers, draw-poker, pong, snake-arena, texas-holdem, game-boy, and jsnes.

Each session can run browser tiles on either the default live_webview backend or the optional agent_browser backend, configured from the settings sidebar.

Examples:

herd tile create browser --browser-path extensions/browser/game-boy/index.html
herd browser load MnOpQr extensions/browser/texas-holdem/index.html

Project-local pages loaded from extensions/browser/... can publish a discoverable API by defining globalThis.HerdBrowserExtension with a manifest and synchronous call(method, args, caller) function. Herd surfaces that metadata through tile_get / network_get and adds extension_call to the browser tile RPC surface when the page is loaded.

Browser screenshots support:

• image PNG capture
• braille
• ascii
• ansi
• layout-preserving text

The built-in Game Boy and JSNES emulator pages use the same screenshot contract and also expose extension methods for ROM loading and controller input.

Sessions And Layout

Session-level controls live in the SETTINGS sidebar and the toolbar. From there you can change the session spawn directory, rename the session, save/load/delete a saved session configuration, switch browser backends, adjust visible port count, and toggle wire sparks.

Saved session configurations are stored under sessions/<config_name>_session.json, and the toolbar's OPEN SESSION dropdown restores a selected save into a fresh tab instead of replacing the current one. For the full saved-session contract and layout tools such as shift-multi-select, lock/unlock, minimize/restore, anchored arrange, and ELK arrange, see docs/session-and-layout.md.

Runtime Files

By default, Herd uses the runtime name herd and writes:

• /tmp/herd.sock: local newline-delimited JSON socket API
• tmp/herd-socket.log: socket traffic log
• tmp/herd-cc.log: tmux control-mode log
• tmp/herd.sqlite: SQLite store for tile registry/layout state, chatter, agents, channels, network state, and work metadata/stage content

If you set HERD_RUNTIME_ID, Herd namespaces those files under herd-<runtime_id> instead. The integration suite uses that to run isolated app instances without colliding with the default runtime.

Saved session configurations live separately under sessions/ as repo-local JSON snapshots.

MCP Server

The repo includes a separate MCP server in mcp-server/ that forwards tool calls to Herd over the local socket. That same server also declares the experimental Claude channel capability when it is running inside a Herd-managed agent tile.

The checked-in .mcp.json points at:

{
  "mcpServers": {
    "herd": {
      "type": "stdio",
      "command": "./bin/herd-mcp-server"
    }
  }
}

bin/herd-mcp-server is a tracked wrapper that resolves the repo root and runs mcp-server/run.mjs. mcp-server/run.mjs rebuilds mcp-server/dist/ automatically when the TypeScript source is newer, so new agent tiles do not silently boot a stale MCP bridge.

Herd-managed agent launches pass the repo-root .mcp.json explicitly with --mcp-config, so they can run from the configured session spawn directory without carrying duplicate MCP config files in subdirectories.

Workers and Root use the same checked-in server:herd entry, but they do not see the same interface. Workers get messaging, self_info, self_display_draw, self_led_control, self_display_status, local-network discovery, network tile-event subscriptions, and network_call; Root gets the broader session control surface, including session-wide tile-event subscriptions. The MCP bridge also forwards inbound Herd events into the Claude channel when it runs inside a Herd-managed agent tile.

The exact worker/root split, channel behavior, and browser/service-control details are documented in docs/socket-and-test-driver.md.

Agent Integration

Herd agents currently run on top of the Claude CLI, so they work best when launched inside a Herd shell rather than from an unrelated terminal.

The active project hooks are configured in .claude/settings.json:

• PreToolUse matcher Agent -> .claude/hooks/on-agent-start.sh
• PreToolUse matcher Bash -> .claude/hooks/on-bg-bash.sh

In practice, Herd injects the local socket and tile/agent context into managed launches, keeps Root present as the session coordinator, and relies on the Claude hooks to spawn or observe additional collaborator tiles. The detailed hook/runtime behavior lives in docs/architecture.md and docs/socket-and-test-driver.md.

Typical flow:

1. Open a shell in Herd or click + Agent.
2. The agent starts in the session spawn directory with claude --mcp-config <repo-root>/.mcp.json --teammate-mode tmux --dangerously-load-development-channels server:herd.
3. Ask the agent to create teammates or run background tool work.
4. Herd renders those hook-spawned or tmux-created children as additional linked tiles on the canvas and tracks agent messaging activity.

Command Bar

See docs/keyboard-shortcuts.md for the current keyboard and command-bar surface, including :sudo, :dm, and :cm.

Testing

Static checks and tests:

npm run check
npm run test:unit
npm run test:integration

Lower-level tmux integration script:

bash bin/test-herd.sh

The managed integration suite currently covers:

• the typed in-app test_driver API
• the configured Claude PreToolUse Agent hook
• the configured Claude PreToolUse background Bash hook
• tmux-created teammate panes appearing as linked child tiles with preserved lineage

Repo Layout

• docs/: reference docs and screenshots
• sessions/: saved session configuration snapshots
• src/: Svelte frontend
• src-tauri/: Rust backend and Tauri app
• mcp-server/: stdio MCP bridge
• tests/integration/: typed socket-driven integration suite
• bin/: helper scripts and lower-level tmux test utilities