--- title: Integrations description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, OpenCode, Hermes Agent, and Qoder CLI. --- 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: ```bash herdr integration install pi herdr integration install omp herdr integration install claude herdr integration install codex herdr integration install opencode herdr integration install hermes herdr integration install qodercli ``` ## Uninstall integrations ```bash herdr integration uninstall pi herdr integration uninstall omp herdr integration uninstall claude herdr integration uninstall codex 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. | | 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. Some integrations also report native agent session references. If `[session] resume_agents_on_restore = true` is enabled, Herdr uses official session references to resume Claude Code, Codex, Pi, Hermes Agent, and OpenCode panes after a Herdr server restart. Native session restore requires current Herdr integrations: Pi integration version `2`, Claude Code version `4`, Codex version `4`, OpenCode version `2`, or Hermes Agent version `2`. OMP integration version `2` reports agent state only. Check installed versions with `herdr integration status`. ## Pi Install the Pi integration: ```bash herdr integration install pi ``` Herdr writes the bundled extension to: ```text ~/.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: ```bash herdr integration install omp ``` Herdr writes the bundled extension to: ```text ~/.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: ```bash 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: ```bash 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: ```bash 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. After OpenCode emits a session-bearing event, Herdr can use the reported session id to resume the pane with `opencode --session `. ## Hermes Agent Install the Hermes Agent plugin: ```bash 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 `. Native screen heuristics remain available when the plugin is not installed. ## Qoder CLI Install the Qoder CLI hook: ```bash 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. ```bash 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. ```bash herdr pane report-metadata "$HERDR_PANE_ID" \ --source user:claude-title \ --agent claude \ --applies-to-source herdr: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: ```bash herdr agent list ``` Read a pane when you need to verify what Herdr can see: ```bash 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.