--- title: Integrations description: Install Herdr integrations for Pi, OMP, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Hermes Agent, and Qoder CLI. --- 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: ```bash 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 ```bash 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: ```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 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: ```bash 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: ```bash 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=`. ## 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 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 `. OpenCode state comes from Herdr's screen detection. ## 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 \ --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.