Integrations

Next docs describe unreleased work from master. Stable docs remain at /docs/.

PK-Herdr detects supported agents automatically. Official integrations can add native session identity for restore, lifecycle state reports, or both.

Use integrations when you want native agent session restore from Claude Code/Codex/Copilot/Devin-style hooks, direct lifecycle reports from Pi/OMP/Kimi/OpenCode/Kilo/Hermes-style hooks or plugins, or both. See Agents for the full status authority model.

Install integrations

Open settings inside PK-Herdr and use the integrations tab to install recommended integrations for agents found on your PATH, or run commands manually:

pk-herdr integration install pi
pk-herdr integration install omp
pk-herdr integration install ompk
pk-herdr integration install claude
pk-herdr integration install codex
pk-herdr integration install copilot
pk-herdr integration install devin
pk-herdr integration install droid
pk-herdr integration install kimi
pk-herdr integration install opencode
pk-herdr integration install kilo
pk-herdr integration install hermes
pk-herdr integration install qodercli
pk-herdr integration install cursor
pk-herdr integration install mastracode
pk-herdr integration install grok

Uninstall integrations

pk-herdr integration uninstall pi
pk-herdr integration uninstall omp
pk-herdr integration uninstall ompk
pk-herdr integration uninstall claude
pk-herdr integration uninstall codex
pk-herdr integration uninstall copilot
pk-herdr integration uninstall devin
pk-herdr integration uninstall droid
pk-herdr integration uninstall kimi
pk-herdr integration uninstall opencode
pk-herdr integration uninstall kilo
pk-herdr integration uninstall hermes
pk-herdr integration uninstall qodercli
pk-herdr integration uninstall cursor
pk-herdr integration uninstall mastracode
pk-herdr integration uninstall grok

How PK-Herdr uses integrations

PK-Herdr uses integrations in two different ways:

Integration type	Agents	Effect
Lifecycle authority	Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent, MastraCode	When installed and actively reporting for the pane, hook or plugin events author idle, working, and blocked. PK-Herdr does not also use screen manifest fallback for that same lifecycle authority.
Session identity	Claude Code, Codex, GitHub Copilot CLI, Devin CLI, Droid, Qoder CLI, Cursor Agent CLI, Grok CLI	The integration reports native session references for restore. State still comes from PK-Herdr’s screen manifest detection.

Custom socket integrations can also report state when they define state that is not visible in the native terminal UI.

Some integrations report native agent session references. PK-Herdr uses official session references to resume Claude Code, Codex, Devin CLI, Droid, Kimi Code CLI, Qoder CLI, Cursor Agent CLI, Grok CLI, GitHub Copilot CLI, Pi, OMP, Hermes Agent, OpenCode, Kilo Code CLI, and MastraCode panes after a PK-Herdr server restart unless [session] resume_agents_on_restore = false disables it.

Native session restore requires current PK-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, Cursor Agent CLI version 1, Grok CLI version 1, OpenCode version 5, Kilo Code CLI version 1, Hermes Agent version 2, or MastraCode version 1. Check installed versions with pk-herdr integration status.

Pi

Install the Pi integration:

pk-herdr integration install pi

PK-Herdr writes the bundled extension to:

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

For the ompk fork, run pk-herdr integration install ompk; PK-Herdr writes to ~/.ompk/agent/extensions/herdr-omp-agent-state.ts instead. omp and ompk share one integration. When OMP_PROFILE (or PI_PROFILE) is set, PK-Herdr writes to <config dir>/profiles/<profile>/agent/extensions/herdr-omp-agent-state.ts. PI_CONFIG_DIR overrides the default config directory name, and PI_CODING_AGENT_DIR overrides the whole agent directory. PK-Herdr creates the extensions directory when the OMP agent directory already exists. Uninstall removes only that extension file.

OMP

Install the OMP integration:

pk-herdr integration install omp
pk-herdr integration install ompk

PK-Herdr writes the bundled extension to:

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

PK-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, PK-Herdr refuses the OMP install so the OMP extension cannot be loaded by Pi. Configure separate agent directories before installing both integrations. PK-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 PK-Herdr’s socket API. It does not require native process detection for the omp executable, and PK-Herdr can resume an OMP pane with omp --resume=<session> after a server restart.

Claude Code

Install the Claude Code hook:

pk-herdr integration install claude

The hook reports Claude Code session identity to the local PK-Herdr socket on session start. Claude Code state comes from PK-Herdr’s screen manifest detection.

PK-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 PK-Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.

Codex

Install the Codex hook:

pk-herdr integration install codex

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

PK-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 PK-Herdr entries from hooks.json and deletes the hook script, but leaves config.toml unchanged.

GitHub Copilot CLI

Install the GitHub Copilot CLI hook:

pk-herdr integration install copilot

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

PK-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 PK-Herdr entries from settings.json and deletes the hook script.

After Copilot emits a session-bearing event, PK-Herdr can use the reported session id to resume the pane with copilot --resume=<id>.

Devin CLI

Install the Devin CLI hook:

pk-herdr integration install devin

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

PK-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 PK-Herdr hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes PK-Herdr entries from config.json and deletes the hook script.

PK-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:

pk-herdr integration install kimi

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

PK-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 PK-Herdr-managed [[hooks]] entries to config.toml. Uninstall removes the PK-Herdr-managed config block and deletes the hook script.

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

Droid

Install the Droid hook:

pk-herdr integration install droid

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

PK-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 PK-Herdr SessionStart hook entry, and removes older PK-Herdr Droid hook entries from hooks.json if present. Uninstall removes PK-Herdr entries from both config files and deletes the hook script.

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

OpenCode

Install the OpenCode plugin:

pk-herdr integration install opencode

PK-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 PK-Herdr pane. After OpenCode emits a session-bearing event, PK-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:

pk-herdr integration install kilo

PK-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 PK-Herdr pane. After Kilo emits a session-bearing event, PK-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:

pk-herdr integration install hermes

PK-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 PK-Herdr pane. PK-Herdr can use the reported session id to resume the pane with hermes --resume <id>. Native screen manifest detection remains available when the plugin is not installed.

Qoder CLI

Install the Qoder CLI hook:

pk-herdr integration install qodercli

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

PK-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 PK-Herdr hook entries. Uninstall removes the matching hook entries and deletes the hook script.

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

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

Cursor Agent CLI

Install the Cursor Agent CLI hook:

pk-herdr integration install cursor

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

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

After Cursor emits a session start event, PK-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 PK-Herdr restores the pane; PK-Herdr does not launch the generic agent command.

MastraCode

Install the MastraCode hook:

pk-herdr integration install mastracode

The hook reports MastraCode lifecycle state and thread identity to PK-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 PK-Herdr pane.

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

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

Grok CLI

Install the Grok CLI hook:

pk-herdr integration install grok

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

PK-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 PK-Herdr SessionStart entry next to the hooks/herdr-agent-state.sh script, and never edits other hook files. Uninstall removes exactly those two PK-Herdr-owned files.

After Grok emits a session start event, PK-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.

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

User hooks that run next to a PK-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.

pk-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

Tokens and state labels are visual-only. Waits, notifications, and workspace rollups still use the semantic state.

Debug integration state

List known agents:

pk-herdr agent list

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

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

If integration state looks wrong, first confirm the agent is running inside PK-Herdr and that the relevant hook or plugin was installed for the same user account.