Weherd

weherd_demo.mp4

Vibe-coded: All code and documentation in this repository were generated by AI agents. No code or documentation was human-written.

Created by Codex and its implementation and review agents, from an idea by Luís Cleto.

A Three.js office you can walk through, populated by the coding agents in your local Herdr session. Working agents use their laptops, blocked agents hold their heads, and idle or finished agents head for coffee. Walk up to a character to open its terminal, or equip the shotgun to close its terminal.

Run

Requires Node.js 22 or newer. Live mode also needs a running Herdr session and herdr on your PATH. The terminal bridge has been verified against Herdr 0.8.2, socket protocol 20.

npm install
npm run dev

Open http://127.0.0.1:5173. The Vite server proxies the API and terminal WebSockets to the local bridge on port 4317.

To run the built application:

npm run build
npm start

Open http://127.0.0.1:4317. Both servers bind to loopback.

Configuration

Variable	Purpose
HERDR_SOCKET_PATH	Explicit path to the Herdr API socket.
HERDR_SESSION	Select a named Herdr session when no explicit socket path is supplied.
HERDR_BIN_PATH	Override the herdr executable used for interactive terminal streams.
HERDR_CONFIG_PATH	Herdr configuration file; its directory supplies the socket location.
XDG_CONFIG_HOME	Used for the default herdr/herdr.sock config path. Otherwise the bridge uses ~/.config/herdr/herdr.sock.
PORT	Bridge port; defaults to 4317. Update the Vite proxy if changing it during development.
WEHERD_MODE	Initial bridge mode: live (default) or demo.
WEHERD_ALLOWED_ORIGINS	Exact additional allowed browser origins, comma separated. Defaults to localhost and 127.0.0.1 on port 5173. The bridge's own origin is always accepted.

The bridge serves the built frontend itself; no reverse proxy is required for local use.

Controls

Control	Action
WASD or arrow keys	Walk in screen directions.
Shift	Sprint.
E near a character	Open its terminal.
Q or 1	Equip or holster the shotgun.
Mouse + left click	Aim and fire while equipped.
Mouse wheel	Zoom.
Shift+Esc or Close	Close the terminal panel. Plain Esc is sent to the terminal.
Esc	Close settings.

Use the mode switch to choose Live or Demo. Demo is also available directly at http://127.0.0.1:5173/?mode=demo. Reset demo restores closed demo characters.

Live actions

Live mode operates on real Herdr terminals. Demo mode is a separate playground for trying the controls and shotgun.

The closure settings start with busy-agent closure disabled and workspace closure disabled. Busy-agent protection covers working, blocked, and unknown states. Keeping a workspace after closing its final agent requires creating a replacement shell tab: Herdr otherwise removes the workspace when its last pane closes.

Closing an entire workspace includes its panes. This setting does not delete checkout directories or Git worktrees. A workspace close that would cascade into other linked Herdr workspaces is refused.

The bridge refreshes state and checks occupant identity before an action. Herdr does not provide an atomic identity-check-and-close operation, so a small race remains between validation and closure. A same-kind process replacement without a native session identifier may also be indistinguishable from its previous occupant.

Development

npm run typecheck
npm test
npm run build

src/ contains the browser game. server/ contains the local socket and terminal bridge. The scene uses procedural geometry, with no external 3D model downloads. See PROJECT.md for scope and the review approach.

See server/PROTOCOL.md for the API contract, terminal transport, identity limits, and backend validation evidence.

Validation on 2026-09-05 covered the production build, backend tests, independent identity/origin checks, demo gameplay, roster resizing, disconnect handling, and a real disposable Codex agent. The reviewer walked to that agent, opened its terminal, fired at it through the game, and confirmed its workspace survived with a replacement shell. Existing agents were preserved. See the AI review summary for results and limitations.

Protocol references: Herdr socket API and terminal session CLI. The installed herdr api schema --json is the authority for the locally running version.