Herdr GPUI macOS Setup: Daemon & Client

Herdr GPUI is an independent desktop client for Herdr. A successful setup needs the daemon, the desktop application, and whichever coding agent you want to use. Treat these as separate installations so you can identify the component behind an error.

Herdr GPUI overview and setup builder

Check your environment

The client repository documents macOS 14.2 or newer and supports Apple Silicon and Intel through its macOS package. The Homebrew installation below assumes Homebrew is already available. Check the client installation instructions before applying this guide to a newer release.

Open your ordinary terminal and check Homebrew:

brew --version

If this command is missing, follow Homebrew's installation instructions first. This guide does not install development toolchains or change your system settings automatically.

Install the Herdr daemon

The daemon manages terminal processes and session state. Install it through Homebrew:

brew install herdr
command -v herdr

The second command should print the executable's location. If it prints nothing, resolve the installation or PATH issue before trying to diagnose the GUI. Herdr's installation documentation also describes direct downloads and other installation methods.

Install and launch the native client

Install the separate desktop application:

brew install penso/tap/herdr-gpui
open -a Herdr

The application can start an already installed local Herdr server when needed. It does not install or upgrade the daemon for you. When the daemon was installed after the application started, the client documentation describes Terminal > Reconnect. See the native-client scope and configuration for current discovery behavior.

If the app reports that Herdr is missing, return to the executable check. Reinstalling a coding agent will not repair daemon discovery.

Verify one local project

Choose a familiar repository and a small task. Start your agent only after completing its own installation and authentication. You can first confirm its command exists in an ordinary terminal:

command -v claude
command -v codex

You only need the agent you intend to use; a missing command for an unselected agent is not a setup failure.

Open the intended workspace and confirm its directory. Ask the agent to explain a small module before authorizing edits. Verify its output, inspect any changes, and keep the terminal available for approval requests. An agent-state indicator helps navigation but does not replace reviewing the actual result.

Update the right component

Keep a note of which installer owns each component. For a Homebrew-installed daemon, update it through Homebrew rather than using the direct-install update flow. The client repository documents Homebrew ownership and its client update behavior.

To manage the client by its short cask name, the repository documents tapping its source first:

brew tap penso/tap
brew upgrade --cask herdr-gpui

Read the release notes before updating a long-running workspace. Detaching a client, updating software, and restarting a server are distinct events. The session-state documentation explains which processes remain alive and which restoration paths depend on supported agent integrations.

Next steps

Once one task works, use separate Git worktrees for parallel agent tasks. If a connection fails, follow the client and daemon connection checklist before changing unrelated settings.

The instructions above come from upstream documentation; they are not a claim that we installed the software on your machine.