---
title: Integrations
description: Install Herdr integrations for Pi, Claude Code, Codex, OpenCode, and Hermes Agent.
---

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 claude
herdr integration install codex
herdr integration install opencode
herdr integration install hermes
```

## Uninstall integrations

```bash
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:

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

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

## 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, 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.

```bash
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:

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