Integrations

Herdr detects supported agents automatically. Official integrations can add native session identity for restore, semantic state reports, or both. Claude Code, Codex, and OpenCode state comes from screen detection even when their session identity integrations are installed.

Use integrations when you want native agent session restore, direct state reports from Pi/OMP/Copilot/Hermes/Qoder-style hooks or plugins, or both.

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 omp
herdr integration install claude
herdr integration install codex
herdr integration install copilot
herdr integration install opencode
herdr integration install hermes
herdr integration install qodercli

Uninstall integrations

herdr integration uninstall pi
herdr integration uninstall omp
herdr integration uninstall claude
herdr integration uninstall codex
herdr integration uninstall copilot
herdr integration uninstall opencode
herdr integration uninstall hermes
herdr integration uninstall qodercli

How Herdr uses integrations

Herdr combines three signals:

Signal	Purpose
Process detection	Identifies which pane owns which running process.
Screen heuristics	Infers visible native agent state such as working or blocked.
Integration events	Reports native session identity, semantic state, or both depending on the integration.

Claude Code, Codex, and OpenCode state detection is screen-read first. Their Herdr-owned integrations do not author idle, working, or blocked state. Pi, GitHub Copilot CLI, and Hermes Agent report semantic state and session identity. OMP and Qoder CLI report semantic state but do not provide native session restore. Custom socket integrations can report state when they define state that is not visible in the native terminal UI.

Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, GitHub Copilot CLI, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart unless [session] resume_agents_on_restore = false disables it.

Native session restore requires current Herdr integrations: Pi integration version 2, Claude Code version 5, Codex version 5, GitHub Copilot CLI version 1, OpenCode version 4, or Hermes Agent version 2. OMP integration version 2 and Qoder CLI integration version 1 report agent state only. Check installed versions with herdr integration status.

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.

OMP

Install the OMP integration:

herdr integration install omp

Herdr writes the bundled extension to:

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

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

The OMP integration reports omp as the agent label through Herdr’s socket API. It does not require native process detection for the omp executable.

Claude Code

Install the Claude Code hook:

herdr integration install claude

The hook reports Claude Code session identity to the local Herdr socket on session start. Claude Code state comes from Herdr’s screen detection.

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

The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Herdr’s screen detection.

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.

GitHub Copilot CLI

Install the GitHub Copilot CLI hook:

herdr integration install copilot

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

Herdr uses ~/.copilot by default, or COPILOT_HOME when set. The Copilot config directory must already exist. Install writes hooks/herdr-agent-state.sh and updates settings.json with Herdr hook entries. The hook maps prompt submission, tool use, post-tool progress after approvals, ask_user prompts, exit_plan_mode plan review prompts, permission notifications, agent idle notifications, turn stops, and session exits into Herdr state. Uninstall removes Herdr entries from settings.json and deletes the hook script.

After Copilot emits a session-bearing event, Herdr can use the reported session id to resume the pane with copilot --resume=<id>.

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 session identity while OpenCode runs inside a Herdr pane. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with opencode --session <id>. OpenCode state comes from Herdr’s screen detection.

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, approval state, and session id while Hermes runs inside a Herdr pane. Herdr can use the reported session id to resume the pane with hermes --resume <id>. Native screen heuristics remain available when the plugin is not installed.

Qoder CLI

Install the Qoder CLI hook:

herdr integration install qodercli

The hook reports semantic state to Herdr when Qoder CLI emits lifecycle events.

Herdr uses ~/.qoder by default, or QODER_CONFIG_DIR when set. The Qoder 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.

Native screen heuristics remain available when the hook 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

User hooks that run next to a Herdr-managed integration should use metadata instead of report-agent. Metadata changes presentation without taking over the integration’s idle, working, blocked, or session restore authority. --agent guards the report so it only applies while that authoritative agent is active. --applies-to-source guards the report so it only applies while that lifecycle authority source is active. --display-agent changes the visible name.

herdr pane report-metadata "$HERDR_PANE_ID" \
  --source user:claude-title \
  --agent claude \
  --title "Refactor auth middleware" \
  --display-agent "Claude: auth" \
  --custom-status "refactor auth" \
  --state-label working="refactoring auth" \
  --ttl-ms 3600000

Custom status and state labels are 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.