Herdr World

A visual control plane for Herdr. Connect local and SSH hosts, see their agents together in Town, Board or Desk, and chat with them, start them from profiles, and use independently qualified terminals, files and changes on desktop or mobile. Requires a running Herdr server.

What's new in 0.2.7

• Chat with each agent. Opening an agent opens its one window on Chat: the conversation from its transcript, tool calls with their diffs and test results, its current task and quest, and a composer with attachments and slash commands. Answer supported permission prompts and Claude Code questions, or Stop the agent. See the Chat guide.
• Start agents from profiles. Actions → New agent launches Claude Code, Codex or another supported harness from a profile (role, model, permissions, starting brief and Town look) after checking it is installed and logged in.
• Hear who needs you. Chimes say who needs you and why; set each agent to Watching, Muted or Focused.
• Teams and agent tools. Agents started by other agents are grouped with them. The herdr-world CLI lets agents pin and colour their cards, report results and ask you questions.
• Work beside agents. Your GitHub pull requests and Jira tickets appear in Board's Work lens and on Town desks, with confirmed merge, close and mark ready actions.
• A clearer Town. Rooms follow Spaces' tab order and resize as tabs open or close; explicitly expanded rooms keep their size until folded; pin desks, colour hosts, workspaces and terminals, and open Summary for everything needing you. Every view opens in Zen.
• Herdr setup. The published 0.2.7 standalone installer installs or upgrades Herdr to the verified release; set HERDR_WORLD_SKIP_HERDR=1 to leave yours untouched. Homebrew reuses existing Herdr and installs it on first launch only if missing. World updates refresh Herdr's harness integrations and plugin. See Herdr installation and upgrades.

Read the 0.2.7 release notes for upgrade steps and known limits.

Choose your layout

• Town is the default: host buildings contain workspace rooms, team tables and terminal seats. Find waiting agents at reception, read their peek and reply.
• Board puts workspace and tab cards beside your notes. Arrange cards, string a note to an exact pane and explicitly send it when ready.
• Desk groups agents into Needs you, To review and In flight, with a reading pane for Chat, terminal, files and changes.
• Spaces focuses one workspace's terminal panes and repository tools.

Town, Board and Desk share the Hosts filter. Open terminals and Inspectors retain their owning host when the filter changes. Use Actions → New workspace or New tab and confirm the destination; Town's New room and Board's + controls offer the same qualified creation flows.

Office, Tree and Graph have been retired: old /office addresses open Town, and /graph and /tree open Board. Board and these redirects are included in 0.2.6.

Screenshots

These captures show 0.2.7 with four disposable workspaces on a throwaway Herdr session. Three real Claude Code agents ran small tasks there: one added a first-run section to the demo README, one is waiting on you and one has finished. The notes and terminal commands are synthetic. Click a screenshot to open it at full resolution.

Desktop

Town: buildings, rooms and reception	Board: workspace cards, tabs and a strung note

Each agent has one window with Chat, Terminal, Files and Changes, whether opened from Town, Board or Desk. See Chat and the tutorial's review exercise for the complete flow.

Chat	Files	Changes

Mobile

Town	Chat	Board	Spaces

Quick start

1. Herdr World runs on Herdr. Homebrew reuses existing Herdr and installs it on first World launch only if missing. The published 0.2.7 standalone installer installs or upgrades Herdr to the verified release; set HERDR_WORLD_SKIP_HERDR=1 to leave yours untouched. With npm or a Windows archive, run herdr-world herdr upgrade --install once if needed. herdr-world herdr setup starts Herdr as a user service.

2. On Linux or macOS, install Herdr World with the standalone installer:

   # Empty selects latest; use X.Y.Z (no v prefix) to pin a Herdr World version.
   curl -fsSL \
     https://github.com/IvoryHeart/herdr-world/releases/latest/download/install-herdr-world.sh \
     | HERDR_WORLD_VERSION= sh
   

   For 0.2.0 and newer releases, Homebrew (brew install IvoryHeart/tap/herdr-world) and npm (npm install --global @ivoryheart/herdr-world) are alternative channels. npm requires Node.js 22.14.0 or newer and downloads only the binary for the current platform. On Windows, use npm or download the matching x64 or ARM64 archive from the latest release.

3. On Linux/macOS standalone installs, add ~/.local/bin to PATH. Run herdr-world (or herdr-world.exe from an extracted Windows archive) and open the printed URL.

Use Manage connections to add local sockets or an SSH destination. One World service owns every connection and the browser stays on that World origin. Hosts filters Town, Board, Desk, the navigator, counts and search; it never connects or disconnects a profile. Terminals and Inspectors on different ready hosts can operate together. Global creation visibly confirms one destination host.

Your GitHub pull requests and Jira tickets appear beside the agents working on them (Board's Work lens and Town desk badges). GitHub works once gh auth login is done for the user running World; add Jira in Settings → Sources.

See deployment for checksums, profiles, authentication, updates, and services.

Install as a PWA

PWA installation is recommended for daily use: a separate app window without browser tabs or the address bar. Open and authenticate with Herdr World, then install:

• iPhone/iPad Safari: Share -> Add to Home Screen.
• macOS Safari 17+: File -> Add to Dock.
• Chrome/Edge: browser menu -> Install app.

The process must stay running and reachable. PWA mode is not offline access.

Documentation

• Website and hands-on tutorial (Markdown): Town, Board, Desk, terminal/file review, mobile, and private remote access.
• Chat: reading and replying to agents, answering their prompts, and which harnesses Chat supports.
• Features and shortcuts, including the agent CLI: run herdr-world --skill to teach an agent to change World.
• Deployment: installation, configuration, services, builds.
• Architecture: system contracts.
• Repository knowledge map and foundation source guide: contracts, module owners, request paths, and focused tests for contributors and agents.
• Development, packaging, and , and .

Development

Use Bun 1.4.3 or newer and a running Herdr server:

bun install --frozen-lockfile
# Run in separate terminals:
bun run dev:server
bun run dev:web

Open http://localhost:5173. See CONTRIBUTING.md for checks and pull requests.

Security

Herdr World controls terminals and modifies real files. Keep the default loopback binding. Every listener requires login with a 15–1024-character configured password or a generated persistent token; read SECURITY.md before allowing another device access.

License

Code: MIT. Bundled dependencies, fonts and brand assets retain their original terms; see THIRD_PARTY_NOTICES.md and the generated dependency licence texts.