Skip to content

Integrations

Herdsman detects the agents it supports automatically. Install an agent’s integration so Herdsman can resume the same session after a server restart. Some integrations also report the agent’s state directly. See Agents for which agents Herdsman supports and which support Herdsman themselves.

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

Terminal window
herdsman integration install pi
herdsman integration install omp
herdsman integration install claude
herdsman integration install codex
herdsman integration install copilot
herdsman integration install devin
herdsman integration install droid
herdsman integration install kimi
herdsman integration install opencode
herdsman integration install kilo
herdsman integration install hermes
herdsman integration install qodercli
herdsman integration install qwen
herdsman integration install letta
herdsman integration install cursor
herdsman integration install mastracode
herdsman integration install antigravity-cli
herdsman integration install grok

The Claude Code, Codex, and OpenCode integrations also install Herdsman’s agent skill for that agent.

Terminal window
herdsman integration uninstall pi
herdsman integration uninstall omp
herdsman integration uninstall claude
herdsman integration uninstall codex
herdsman integration uninstall copilot
herdsman integration uninstall devin
herdsman integration uninstall droid
herdsman integration uninstall kimi
herdsman integration uninstall opencode
herdsman integration uninstall kilo
herdsman integration uninstall hermes
herdsman integration uninstall qodercli
herdsman integration uninstall qwen
herdsman integration uninstall letta
herdsman integration uninstall cursor
herdsman integration uninstall mastracode
herdsman integration uninstall antigravity-cli
herdsman integration uninstall grok

Herdsman saves integration configs atomically on Linux/macOS and for new files; existing Windows files keep their permissions through a backup-first, in-place update. If Windows reports a backup, close the agent and inspect the config before retrying: discard—not restore—an unfinished .herdsman-backup.pending only after verifying the config, or restore completed .herdsman-backup contents into the existing file if needed (if missing, establish its intended permissions first), then verify the config and remove the backup.

Every integration tells Herdsman which session the agent is in, so Herdsman can resume it after a server restart. Turn this off with [session] resume_agents_on_restore = false.

The Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, and MastraCode integrations also report the agent’s state. While they report, Herdsman uses them instead of reading the screen. The others leave state to screen detection.

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

If you build a coding agent, you can report its state and resume command to Herdsman from your own code, without adding native support to Herdsman. See Add Herdsman support to your agent.

Install the Pi integration:

Terminal window
herdsman integration install pi

Herdsman writes the bundled extension to:

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

If PI_CODING_AGENT_DIR is set, Herdsman writes to $PI_CODING_AGENT_DIR/extensions/herdsman-agent-state.ts instead. Herdsman creates the extensions directory when the Pi agent directory already exists. Uninstall removes only that extension file.

Install the OMP integration:

Terminal window
herdsman integration install omp

Herdsman writes the bundled extension to:

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

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

Install the Claude Code hook:

Terminal window
herdsman integration install claude

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

Claude integration v10 matches only the documented SessionStart sources: startup, resume, clear, compact, and fork. This prevents Grok’s new and load events from launching the imported Herdsman Claude hook, without disabling unrelated Claude-compatible hooks. Reinstall the Claude integration after upgrading to migrate the previous wildcard matcher. New Claude source values require an integration update.

Herdsman uses ~/.claude by default, or CLAUDE_CONFIG_DIR when set. The Claude config directory must already exist. Install writes hooks/herdsman-agent-state.sh and updates settings.json with Herdsman hook entries. Uninstall removes the matching hook entries and deletes the hook script.

Install the Codex hook:

Terminal window
herdsman integration install codex

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

Herdsman uses ~/.codex by default, or CODEX_HOME when set. The Codex config directory must already exist. Install writes herdsman-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 Herdsman entries from hooks.json and deletes the hook script, but leaves config.toml unchanged.

Install the GitHub Copilot CLI hook:

Terminal window
herdsman integration install copilot

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

Herdsman uses ~/.copilot by default, or COPILOT_HOME when set. The Copilot config directory must already exist. Install writes hooks/herdsman-agent-state.sh and updates settings.json with a SessionStart hook entry. Uninstall removes Herdsman entries from settings.json and deletes the hook script.

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

Install the Devin CLI hook:

Terminal window
herdsman integration install devin

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

Herdsman uses $XDG_CONFIG_HOME/devin when XDG_CONFIG_HOME is set. Otherwise, it uses ~/.config/devin on Linux and macOS or %APPDATA%\devin on Windows. The Devin config directory must already exist. Install writes herdsman-agent-state.sh on Unix or herdsman-agent-state.ps1 on Windows and updates config.json with Herdsman hook entries. The hook refreshes the session reference while Devin runs. Uninstall removes Herdsman entries from config.json and deletes the hook script.

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

Install the Kimi Code CLI hook:

Terminal window
herdsman integration install kimi

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

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

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

Install the Droid hook:

Terminal window
herdsman integration install droid

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

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

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

Install the OpenCode plugin:

Terminal window
herdsman integration install opencode

The integration supports OpenCode V1 1.18.29 or later and OpenCode V2 (tested with beta 19242). The OpenCode config directory must already exist. Herdsman installs the server entrypoint at ~/.config/opencode/plugins/herdsman-agent-state.js, the shared TUI plugin at herdsman-tui-session.js, and a V2 TUI entrypoint at herdsman-opencode/tui.js in that config directory.

Install registers the V1 TUI plugin in tui.jsonc and the V2 TUI plugin in cli.json, preserving other preferences and plugins. An existing V1 registration in tui.json also counts as installed and is reused without creating tui.jsonc. Uninstall removes the Herdsman registration from both TUI config files while keeping the files and other preferences. If OpenCode still has V1 TUI preferences to import (tui.json or kv.json), Herdsman defers registration so the first-start migration can run; start opencode2 once and reinstall the integration afterward. Otherwise Herdsman creates cli.json with the plugin registration. Restart the OpenCode TUI after installation. Uninstall removes the managed plugin files and their configuration entries.

V2 lifecycle reporting runs in the pane-local TUI, which associates events with its selected root session even when multiple panes share one OpenCode server. Completion and interruption clear the working state; pending permission requests, pending forms, and failed executions keep the pane blocked. V2 Mini and headless clients do not run the TUI plugin and therefore do not provide this lifecycle reporting.

V1 TUI reporting follows the pane’s selected session and its descendants. The pane stays working while any of them is busy or retrying, and blocked while any has a pending permission or question. Attaching loads existing activity; cancelled tool requests do not become blockers again after reconnecting. Browsing a subagent keeps the original session family, while directly attaching to a child tracks that child’s subtree rather than its siblings.

Local V1 opencode run and opencode --mini retain their legacy server hooks; this change does not add pane-local lifecycle reporting to Mini/headless clients. After updating the integration, restart shared OpenCode servers as well as their TUIs so the old server reporter cannot overwrite pane-local state.

The plugin reports lifecycle state and session identity while OpenCode runs inside a Herdsman pane. After OpenCode emits a session-bearing event, Herdsman 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.

Install the Kilo Code CLI plugin:

Terminal window
herdsman integration install kilo

Herdsman writes the plugin to ~/.config/kilo/plugin/herdsman-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 Herdsman pane. After Kilo emits a session-bearing event, Herdsman 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.

Install the Hermes Agent plugin:

Terminal window
herdsman integration install hermes

Herdsman writes plugins/herdsman-agent-state/ under the Hermes home directory and enables herdsman-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 herdsman-agent-state from plugins.enabled.

The plugin reports the resumable session id while Hermes runs inside a Herdsman pane. Herdsman uses screen manifest detection for working, idle, and blocked, and can use the reported session id to resume the pane with hermes --resume <id>.

Install the Qoder CLI hook:

Terminal window
herdsman integration install qodercli

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

Herdsman uses ~/.qoder by default, or QODER_CONFIG_DIR when set. The Qoder config directory must already exist. Install writes hooks/herdsman-agent-state.sh and updates settings.json with Herdsman hook entries. Uninstall removes the matching hook entries and deletes the hook script.

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

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

Install the Qwen Code hook:

Terminal window
herdsman integration install qwen

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

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

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

Letta Code integration installation is experimental and CLI-only. It is not listed in the Settings integration screen or the JSON integration API. herdsman integration status reports it as letta (experimental). Agent detection and herdsman agent start --kind letta are supported independently of this installation restriction.

Install the Letta Code hook:

Terminal window
herdsman integration install letta

The quiet SessionStart hook reports the conversation ID for native restore. Letta Code state still comes from Herdsman’s screen manifest detection.

Herdsman uses ~/.letta. The config directory must already exist. Install writes hooks/herdsman-agent-session.sh (hooks/herdsman-agent-session.ps1 on Windows) and adds a Herdsman entry to settings.json. Uninstall removes only the matching entry and managed script.

Herdsman resumes named conversations with letta --conversation <id>. It records the default conversation as default:<agent-id> and resumes it with letta --conversation default --agent <agent-id>.

Install the Cursor Agent CLI hook:

Terminal window
herdsman integration install cursor

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

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

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

Install the MastraCode hook:

Terminal window
herdsman integration install mastracode

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

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

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

Install the Antigravity CLI hook:

Terminal window
herdsman integration install antigravity-cli

Herdsman 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/herdsman-agent-state.sh (or herdsman-agent-state.ps1 on Windows) and adds a Herdsman-owned herdsman 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 herdsman block and deletes the hook script.

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

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

Install the Grok CLI hook:

Terminal window
herdsman integration install grok

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

Herdsman 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/herdsman.json with the Herdsman SessionStart entry next to hooks/herdsman-agent-state.sh (hooks/herdsman-agent-state.ps1 on Windows), and never edits other hook files. Uninstall removes exactly those two Herdsman-owned files.

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

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

Terminal window
herdsman pane report-agent w1:p1 \
--source custom:docs \
--agent docs-bot \
--state working

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

Terminal window
herdsman pane report-metadata "$HERDSMAN_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.

List known agents:

Terminal window
herdsman agent list

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

Terminal window
herdsman pane read w1:p1 --source recent --lines 50

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