goose-herdr

A goose integration for Herdr — the terminal workspace manager for AI coding agents.

The repo ships two complementary pieces:

Both directions are "goose → Herdr". Herdr itself needs no code change: it detects agents by foreground process and exposes a local socket + CLI.

Prerequisites

• goose installed.

• Herdr installed and on your PATH (or HERDR_BIN_PATH set), with a Herdr server running.

The MCP extension works from any shell that can reach the Herdr server. The state-reporting hook only activates when goose itself is running inside a Herdr-managed pane (HERDR_ENV=1).

Related MCP server: Terminal MCP Server

Install the MCP extension

goose extensions are MCP servers. The package exposes a herdr-mcp console script.

Option A — config file (persistent)

Add an entry under extensions in ~/.config/goose/config.yaml:

extensions:
  herdr:
    name: Herdr
    cmd: uvx
    args: ["--from", "git+https://github.com/aquaherd/goose-herdr", "herdr-mcp"]
    enabled: true
    envs: {}
    type: stdio
    timeout: 300

Once the package is published to PyPI, you can use the shorter form:

    args: ["--from", "goose-herdr", "herdr-mcp"]

Option B — interactive CLI

goose configure

Choose Add Extension → Command-line Extension, then enter:

uvx --from git+https://github.com/aquaherd/goose-herdr herdr-mcp

Option C — one-off session (not installed)

goose session --with-extension "uvx --from git+https://github.com/aquaherd/goose-herdr herdr-mcp"

Option D — local development install

git clone https://github.com/aquaherd/goose-herdr
cd goose-herdr
uv pip install -e .          # or: pip install -e .

Then register the extension with cmd: herdr-mcp (and empty args):

extensions:
  herdr:
    name: Herdr
    cmd: herdr-mcp
    args: []
    enabled: true
    envs: {}
    type: stdio
    timeout: 300

Install the state-reporting hook

Copy the agent-state/ directory into a goose plugin location, for example:

mkdir -p ~/.agents/plugins/goose-herdr-agent-state
cp -r agent-state/plugin.json agent-state/hooks agent-state/scripts \
  ~/.agents/plugins/goose-herdr-agent-state/
chmod +x ~/.agents/plugins/goose-herdr-agent-state/scripts/report-state.sh

This reports working on SessionStart/PreToolUse, idle on Stop, and releases the agent on SessionEnd. It is a no-op unless HERDR_ENV=1 and HERDR_PANE_ID are set (i.e. goose is running in a Herdr pane).

Tools

The extension registers herdr_* tools. The read-only ones are safe to call anytime; the rest perform one Herdr action each.

Agent states used by Herdr: idle, working, blocked, done, unknown.

Development

uv venv .venv
uv pip install --python .venv/bin/python -e .
.venv/bin/herdr-mcp      # starts the MCP server over stdio

The package uses the official mcp Python SDK (>= 2.0) and wraps the herdr CLI rather than speaking the raw socket protocol.