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.
Install integrations
Section titled “Install integrations”Open settings inside Herdsman and use the integrations tab to install recommended integrations for agents found on your PATH, or run commands manually:
herdsman integration install piherdsman integration install ompherdsman integration install claudeherdsman integration install codexherdsman integration install copilotherdsman integration install devinherdsman integration install droidherdsman integration install kimiherdsman integration install opencodeherdsman integration install kiloherdsman integration install hermesherdsman integration install qodercliherdsman integration install qwenherdsman integration install lettaherdsman integration install cursorherdsman integration install mastracodeherdsman integration install antigravity-cliherdsman integration install grokThe Claude Code, Codex, and OpenCode integrations also install Herdsman’s agent skill for that agent.
Uninstall integrations
Section titled “Uninstall integrations”herdsman integration uninstall piherdsman integration uninstall ompherdsman integration uninstall claudeherdsman integration uninstall codexherdsman integration uninstall copilotherdsman integration uninstall devinherdsman integration uninstall droidherdsman integration uninstall kimiherdsman integration uninstall opencodeherdsman integration uninstall kiloherdsman integration uninstall hermesherdsman integration uninstall qodercliherdsman integration uninstall qwenherdsman integration uninstall lettaherdsman integration uninstall cursorherdsman integration uninstall mastracodeherdsman integration uninstall antigravity-cliherdsman integration uninstall grokHerdsman 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.
How Herdsman uses integrations
Section titled “How Herdsman uses integrations”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.
Integrate your own agent
Section titled “Integrate your own agent”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:
herdsman integration install piHerdsman writes the bundled extension to:
~/.pi/agent/extensions/herdsman-agent-state.tsIf 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:
herdsman integration install ompHerdsman writes the bundled extension to:
~/.omp/agent/extensions/herdsman-omp-agent-state.tsHerdsman 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.
Claude Code
Section titled “Claude Code”Install the Claude Code hook:
herdsman integration install claudeThe 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:
herdsman integration install codexThe 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.
GitHub Copilot CLI
Section titled “GitHub Copilot CLI”Install the GitHub Copilot CLI hook:
herdsman integration install copilotThe 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>.
Devin CLI
Section titled “Devin CLI”Install the Devin CLI hook:
herdsman integration install devinThe 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.
Kimi Code CLI
Section titled “Kimi Code CLI”Install the Kimi Code CLI hook:
herdsman integration install kimiThe 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:
herdsman integration install droidThe 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>.
OpenCode
Section titled “OpenCode”Install the OpenCode plugin:
herdsman integration install opencodeThe 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.
Kilo Code CLI
Section titled “Kilo Code CLI”Install the Kilo Code CLI plugin:
herdsman integration install kiloHerdsman 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.
Hermes Agent
Section titled “Hermes Agent”Install the Hermes Agent plugin:
herdsman integration install hermesHerdsman 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>.
Qoder CLI
Section titled “Qoder CLI”Install the Qoder CLI hook:
herdsman integration install qodercliThe 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.
Qwen Code
Section titled “Qwen Code”Install the Qwen Code hook:
herdsman integration install qwenThe 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
Section titled “Letta Code”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:
herdsman integration install lettaThe 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>.
Cursor Agent CLI
Section titled “Cursor Agent CLI”Install the Cursor Agent CLI hook:
herdsman integration install cursorThe 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.
MastraCode
Section titled “MastraCode”Install the MastraCode hook:
herdsman integration install mastracodeThe 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>.
Antigravity CLI
Section titled “Antigravity CLI”Install the Antigravity CLI hook:
herdsman integration install antigravity-cliHerdsman 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.
Grok CLI
Section titled “Grok CLI”Install the Grok CLI hook:
herdsman integration install grokThe 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>.
Custom status labels
Section titled “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.
herdsman pane report-agent w1:p1 \ --source custom:docs \ --agent docs-bot \ --state workingUser 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.
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 3600000Tokens and state labels are visual-only. Waits, notifications, and workspace rollups still use the semantic state.
Debug integration state
Section titled “Debug integration state”List known agents:
herdsman agent listRead a pane when you need to verify what Herdsman can see:
herdsman pane read w1:p1 --source recent --lines 50If 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.