Integrations

Herdr detects supported agents automatically. Install official integrations when you want native agent session restore, direct lifecycle reports, or both. See Agents for the full status authority model.

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 piherdr integration install ompherdr integration install claudeherdr integration install codexherdr integration install copilotherdr integration install devinherdr integration install droidherdr integration install kimiherdr integration install opencodeherdr integration install kiloherdr integration install hermesherdr integration install qodercliherdr integration install qwenherdr integration install cursorherdr integration install mastracodeherdr integration install antigravity-cliherdr integration install grok

Terminal window

Uninstall integrations

herdr integration uninstall piherdr integration uninstall ompherdr integration uninstall claudeherdr integration uninstall codexherdr integration uninstall copilotherdr integration uninstall devinherdr integration uninstall droidherdr integration uninstall kimiherdr integration uninstall opencodeherdr integration uninstall kiloherdr integration uninstall hermesherdr integration uninstall qodercliherdr integration uninstall qwenherdr integration uninstall cursorherdr integration uninstall mastracodeherdr integration uninstall antigravity-cliherdr integration uninstall grok

Terminal window

How Herdr uses integrations

Herdr uses integrations in two ways:

Custom integrations can also report state that is not visible in the native terminal UI. They do not need to be built into Herdr or use a recognized agent executable.

Integrate your own agent

An agent running in a Herdr pane inherits HERDR_ENV, HERDR_PANE_ID, HERDR_BIN_PATH, and HERDR_SOCKET_PATH. If the agent exposes lifecycle hooks, use those hooks to report semantic state through Herdr’s CLI:

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \  --source custom:my-agent \  --agent my-agent \  --state working

Terminal window

Report idle when the agent is ready for input and blocked when it needs a user decision. Use --message to describe a block. When the agent exits, release the same source’s lifecycle authority:

"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \  --source custom:my-agent \  --agent my-agent

Terminal window

Report only when HERDR_ENV=1 and the required variables are present. This keeps the integration a no-op outside Herdr. Keep --source stable and unique to the integration. If reports can arrive out of order, include a strictly increasing --seq; Herdr ignores stale sequence numbers from the same source.

You can include --agent-session-id or --agent-session-path with report-agent, or use pane report-agent-session when session identity changes independently of state. Herdr exposes that reference through its pane and agent APIs. Automatic session restore also requires Herdr to know how to launch that agent and resume the referenced session.

Use HERDR_BIN_PATH and the CLI wrappers for portable integrations. Code that needs direct IPC can send the equivalent pane.report_agent, pane.report_agent_session, and pane.release_agent requests described in the Socket API.

Prime Agent’s built-in Herdr reporter is a real-world example. It activates only inside Herdr, maps agent events to working, idle, and blocked, preserves report ordering across sessions, and releases authority on exit.

Some integrations report native agent session references. Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Qwen Code, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, MastraCode, and Antigravity CLI 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, OMP version 3, Claude Code version 6, Codex version 5, GitHub Copilot CLI version 2, Devin CLI version 2, Droid version 2, Kimi Code CLI version 3, Qoder CLI version 2, Qwen Code version 1, Cursor Agent CLI version 1, Grok CLI version 1, OpenCode version 5, Kilo Code CLI version 1, Hermes Agent version 5, MastraCode version 1, or Antigravity CLI version 1. Check installed versions with herdr integration status.

Pi

Install the Pi integration:

herdr integration install pi

Terminal window

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. Herdr creates the extensions directory when the Pi agent directory already exists. Uninstall removes only that extension file.

OMP

Install the OMP integration:

herdr integration install omp

Terminal window

Herdr writes the bundled extension to:

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

Herdr uses PI_CODING_AGENT_DIR as the complete agent directory when set. Otherwise, it uses $HOME/$PI_CONFIG_DIR/agent when PI_CONFIG_DIR is set, falling back to ~/.omp/agent. If Pi and OMP resolve to the same extension directory, Herdr refuses the OMP install so the OMP extension cannot be loaded by Pi. Configure separate agent directories before installing both integrations. Herdr creates the extensions directory when the resolved OMP agent directory already exists. Uninstall removes only that extension file.

The OMP integration reports omp as the agent label, lifecycle state, and native session identity through Herdr’s socket API. It does not require native process detection for the omp executable, and Herdr can resume an OMP pane with omp --resume=<session> after a server restart.

Claude Code

Install the Claude Code hook:

herdr integration install claude

Terminal window

The hook reports Claude Code session identity to the local Herdr socket on session start. Claude Code state comes from Herdr’s screen manifest 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

Terminal window

The Codex hook reports session identity through the same local socket API used by other integrations. Codex state comes from Herdr’s screen manifest 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

Terminal window

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

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 a SessionStart hook entry. 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>.

Devin CLI

Install the Devin CLI hook:

herdr integration install devin

Terminal window

The hook reports native session identity from Devin session, prompt, tool-use, permission, and stop events. Devin state still comes from Herdr’s screen manifest and OSC detection because Devin hooks do not emit a reliable state transition after every permission cancellation or user interrupt.

On Linux and macOS, Herdr uses ~/.config/devin by default, or $XDG_CONFIG_HOME/devin when XDG_CONFIG_HOME is set. The Devin config directory must already exist. Install writes herdr-agent-state.sh and updates config.json with Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdr entries from config.json and deletes the hook script.

Devin integration installation is not currently supported on Windows. Devin stores its Windows config under %APPDATA%\devin, which Herdr does not yet resolve. Native process and screen detection still work without the hook.

Herdr resumes stored Devin sessions with devin --resume <id>. Native screen manifest detection remains the state authority whether or not the hook is installed.

Kimi Code CLI

Install the Kimi Code CLI hook:

herdr integration install kimi

Terminal window

The hook reports Kimi session identity and lifecycle state to Herdr for native restore and authoritative idle, working, and blocked status. It requires Kimi Code CLI 0.14.0 or newer.

Herdr uses ~/.kimi-code by default, or KIMI_CODE_HOME when set. The Kimi Code config directory must already exist. Install writes hooks/herdr-agent-state.sh and appends Herdr-managed [[hooks]] entries to config.toml. Uninstall removes the Herdr-managed config block and deletes the hook script.

Herdr resumes stored Kimi sessions with kimi --session <id>.

Droid

Install the Droid hook:

herdr integration install droid

Terminal window

The Droid hook reports session identity through the same local socket API used by other integrations. Lifecycle state still comes from Herdr’s screen manifest detection because Droid hooks do not cover every lifecycle transition.

Herdr uses ~/.factory for Droid hooks. The Factory config directory must already exist. Install writes hooks/herdr-agent-state.sh, updates settings.json with a Herdr SessionStart hook entry, and removes older Herdr Droid hook entries from hooks.json if present. Uninstall removes Herdr entries from both config files and deletes the hook script.

After Droid emits a session start event, Herdr can use the reported session id to resume the pane with droid --resume <id>.

OpenCode

Install the OpenCode plugin:

herdr integration install opencode

Terminal window

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 lifecycle state and 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>. Native screen manifest detection remains available when the plugin is not installed.

Kilo Code CLI

Install the Kilo Code CLI plugin:

herdr integration install kilo

Terminal window

Herdr writes the plugin to ~/.config/kilo/plugin/herdr-agent-state.js. The Kilo config directory must already exist. Uninstall removes only that plugin file.

The plugin reports lifecycle state and session identity while Kilo runs inside a Herdr pane. After Kilo emits a session-bearing event, Herdr can use the reported session id to resume the pane with kilo --session <id>. Native screen manifest detection remains available when the plugin is not installed.

Hermes Agent

Install the Hermes Agent plugin:

herdr integration install hermes

Terminal window

Herdr writes plugins/herdr-agent-state/ under the Hermes home directory and enables herdr-agent-state in its config.yaml. HERMES_HOME defaults to ~/.hermes on Unix and %LOCALAPPDATA%\hermes on Windows. 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 the resumable session id while Hermes runs inside a Herdr pane. Herdr uses screen manifest detection for working, idle, and blocked, and can use the reported session id to resume the pane with hermes --resume <id>.

Qoder CLI

Install the Qoder CLI hook:

herdr integration install qodercli

Terminal window

The hook reports Qoder CLI session identity to Herdr for native restore. Lifecycle state still comes from Herdr’s screen manifest detection because Qoder hooks do not cover every lifecycle transition.

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.

Herdr resumes stored Qoder CLI sessions with qodercli --resume <id>.

Native screen manifest detection remains available when the hook is not installed.

Qwen Code

Install the Qwen Code hook:

herdr integration install qwen

Terminal window

The SessionStart hook reports only Qwen Code’s session identity for native restore. Lifecycle state remains under Herdr’s screen manifest detection.

Herdr uses ~/.qwen by default, or QWEN_HOME when set. The Qwen config directory must already exist. Install writes hooks/herdr-agent-session.sh (hooks/herdr-agent-session.ps1 on Windows) and adds a Herdr entry to settings.json. Uninstall removes only the matching entry and managed script.

Herdr resumes stored Qwen Code sessions with qwen --resume <id>.

Cursor Agent CLI

Install the Cursor Agent CLI hook:

herdr integration install cursor

Terminal window

The hook reports session identity through Cursor’s sessionStart hook while Cursor Agent CLI runs inside a Herdr pane. Cursor state comes from Herdr’s screen manifest detection.

Herdr uses ~/.cursor by default, or CURSOR_CONFIG_DIR when set. The Cursor config directory must already exist. Install writes herdr-agent-state.sh (herdr-agent-state.ps1 on Windows) and adds a Herdr sessionStart entry to hooks.json. Uninstall removes the matching hook entry and deletes the hook script.

After Cursor emits a session start event, Herdr can use the reported session id to resume the pane with cursor-agent --resume <id>. The cursor-agent command must be on PATH when Herdr restores the pane; Herdr does not launch the generic agent command.

MastraCode

Install the MastraCode hook:

herdr integration install mastracode

Terminal window

The hook reports MastraCode lifecycle state and thread identity to Herdr for authoritative idle, working, and blocked status and native restore. MastraCode has no screen manifest fallback; state comes from the hook while MastraCode runs inside a Herdr pane.

Herdr uses ~/.mastracode. Install writes hooks/herdr-agent-state.sh (hooks/herdr-agent-state.ps1 on Windows) and adds Herdr command entries to hooks.json, creating the directory when missing. Uninstall removes the matching hook entries and deletes the hook script.

Herdr resumes stored MastraCode threads with mastracode --thread <id>.

Antigravity CLI

Install the Antigravity CLI hook:

herdr integration install antigravity-cli

Terminal window

Herdr uses ~/.gemini/config/ by default, or ANTIGRAVITY_CLI_CONFIG_DIR when set. This is the directory Antigravity CLI reads global customizations from, and it must already exist. Install writes hooks/herdr-agent-state.sh (or herdr-agent-state.ps1 on Windows) and adds a Herdr-owned herdr block to hooks.json. Antigravity CLI keys hooks.json by hook name, so install rewrites only that block and leaves other named hooks untouched. Uninstall removes the herdr block and deletes the hook script.

This session-only integration reports the pane’s current conversation, but not agent state. Herdr keeps deriving working, idle, and blocked from what Antigravity CLI draws on screen.

The hook runs on PreInvocation, so Herdr learns the conversation once the first prompt is sent. From then on Herdr can resume the pane with agy --conversation <id> after a Herdr server restart.

Grok CLI

Install the Grok CLI hook:

herdr integration install grok

Terminal window

The hook reports session identity through Grok’s SessionStart hook while Grok CLI runs inside a Herdr pane. Grok state comes from Herdr’s screen manifest detection.

Herdr uses ~/.grok by default, or GROK_HOME when set. The Grok config directory must already exist. Grok merges every hooks/*.json file in that directory, so install writes a self-contained hooks/herdr.json with the Herdr SessionStart entry next to hooks/herdr-agent-state.sh (hooks/herdr-agent-state.ps1 on Windows), and never edits other hook files. Uninstall removes exactly those two Herdr-owned files.

After Grok emits a session start event, Herdr can use the reported session id to resume the pane with grok --resume <id>.

Custom status labels

Integrations report lifecycle state as semantic state only. For example, report an agent as working without adding display fields to the lifecycle report.

herdr pane report-agent w1:p1 \  --source custom:docs \  --agent docs-bot \  --state working

Terminal window

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 and --applies-to-source guard only presentation fields (--title, --display-agent, and --state-label). Token patches always apply; their reporter owns clearing or TTL refresh. --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" \  --token summary="refactor auth" \  --state-label working="refactoring auth" \  --ttl-ms 3600000

Terminal window

Tokens 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

Terminal window

Read a pane when you need to verify what Herdr can see:

herdr pane read w1:p1 --source recent --lines 50

Terminal window

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.

Last updated Oct 08, 2026