Integrations

Herdr detects supported agents automatically. Integrations make that detection more precise by reporting semantic state directly to Herdr.

Use integrations when you want reliable working, blocked, idle, and done state from agent hooks or plugins.

Install integrations

Open settings inside Herdr and use the integrations tab to install recommended integrations for agents found on your PATH, or run commands manually:

herdr integration install pi
herdr integration install claude
herdr integration install codex
herdr integration install opencode
herdr integration install hermes

Uninstall integrations

herdr integration uninstall pi
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall opencode
herdr integration uninstall hermes

How Herdr uses integrations

Herdr combines three signals:

Signal	Purpose
Process detection	Identifies which pane owns which running process.
Agent integration events	Reports semantic state such as working or blocked.
Screen heuristics	Fills gaps when hooks are unavailable or incomplete.

Integrations enrich state reporting. They do not replace process detection.

Pi

Install the Pi integration:

herdr integration install pi

Herdr writes the bundled extension to:

~/.pi/agent/extensions/herdr-agent-state.ts

If PI_CODING_AGENT_DIR is set, Herdr writes to $PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts instead. The extensions directory must already exist. Uninstall removes only that extension file.

Claude Code

Install the Claude Code hook:

herdr integration install claude

The hook reports agent state to the local Herdr socket when Claude Code exposes hook events.

Herdr uses ~/.claude by default, or CLAUDE_CONFIG_DIR when set. The Claude config directory must already exist. Install writes hooks/herdr-agent-state.sh and updates settings.json with Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.

Codex

Install the Codex hook:

herdr integration install codex

Codex state is reported through the same local socket API used by other integrations.

Herdr uses ~/.codex by default, or CODEX_HOME when set. The Codex config directory must already exist. Install writes herdr-agent-state.sh, updates hooks.json, and ensures [features] hooks = true in config.toml. It also removes the deprecated top-level codex_hooks flag when present. Uninstall removes Herdr entries from hooks.json and deletes the hook script, but leaves config.toml unchanged.

OpenCode

Install the OpenCode plugin:

herdr integration install opencode

Herdr writes the plugin to ~/.config/opencode/plugins/herdr-agent-state.js. The OpenCode config directory must already exist. Uninstall removes only that plugin file.

The plugin reports semantic state while OpenCode runs inside a Herdr pane.

Hermes Agent

Install the Hermes Agent plugin:

herdr integration install hermes

Herdr writes ~/.hermes/plugins/herdr-agent-state/ and enables herdr-agent-state in ~/.hermes/config.yaml. The Hermes config directory must already exist. Restart Hermes after installing so the plugin loads. Uninstall removes the plugin directory and removes herdr-agent-state from plugins.enabled.

The plugin reports lifecycle, tool, and approval state while Hermes runs inside a Herdr pane. Native screen heuristics remain available when the plugin is not installed.

Custom status labels

Integrations can report a short visual label without changing the semantic state.

For example, an agent can remain semantically working while showing indexing in the UI.

herdr pane report-agent 1-1 \
  --source custom:docs \
  --agent docs-bot \
  --state working \
  --custom-status indexing

Custom status is visual-only. Waits, notifications, and workspace rollups still use the semantic state.

Debug integration state

List known agents:

herdr agent list

Read a pane when you need to verify what Herdr can see:

herdr pane read 1-1 --source recent --lines 50

If integration state looks wrong, first confirm the agent is running inside Herdr and that the relevant hook or plugin was installed for the same user account.