---
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=<id>`.

## 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 <id>`. 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 <id>`. 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.
