SOP: Integration Setup

Fresh

Install official agent integrations so Herdr gets authoritative lifecycle state, native session identity for restore, or both.

Decide what you need

Integration type	Agents	What you get
Lifecycle authority	Pi, OMP, Kimi Code CLI, OpenCode, Kilo Code CLI, Hermes Agent	Hook/plugin events author idle, working, blocked directly
Session identity	Claude Code, Codex, GitHub Copilot CLI, Droid, Qoder CLI, Cursor Agent CLI	Native session references for restore; state still comes from screen manifest detection

Procedure

1. Confirm the agent's config directory exists (each integration requires it). Examples: ~/.claude for Claude Code, ~/.codex for Codex, ~/.copilot for Copilot, ~/.factory for Droid, ~/.kimi-code for Kimi, ~/.config/opencode for OpenCode, ~/.config/kilo for Kilo, ~/.hermes for Hermes, ~/.qoder for Qoder, ~/.cursor for Cursor.

2. Install from inside Herdr (Settings > integrations tab installs recommended integrations for agents found on PATH), or run manually:

herdr integration install claude
herdr integration install codex
herdr integration install pi
herdr integration install copilot
herdr integration install cursor
herdr integration install droid
herdr integration install kimi
herdr integration install opencode
herdr integration install kilo
herdr integration install hermes
herdr integration install qodercli
herdr integration install omp

3. Verify versions:

herdr integration status
herdr integration status --outdated-only

4. For Hermes only: restart Hermes after installing so the plugin loads.

5. Confirm native session restore minimums (run herdr integration status and compare):

Agent	Minimum integration version	Resume command
Pi	2	pi --session <path-or-id>
Claude Code	5	claude --resume <id>
Codex	5	codex resume <id>
Cursor Agent CLI	1	cursor-agent --resume <id>
GitHub Copilot CLI	2	copilot --resume=<id>
Droid	2	droid --resume <id>
Kimi Code CLI	3	kimi --session <id>
Qoder CLI	2	qodercli --resume <id>
OpenCode	5	opencode --session <id>
Kilo Code CLI	1	kilo --session <id>
Hermes Agent	2	hermes --resume <id>

OMP version 2 reports state only, no session restore.

What each install writes

Agent	Files written
Claude Code	hooks/herdr-agent-state.sh + Herdr hook entries in settings.json (in ~/.claude or CLAUDE_CONFIG_DIR)
Codex	herdr-agent-state.sh, hooks.json update, [features] hooks = true in config.toml (in ~/.codex or CODEX_HOME)
Copilot	hooks/herdr-agent-state.sh + SessionStart hook in settings.json
Pi / OMP	extensions/herdr-agent-state.ts / herdr-omp-agent-state.ts under ~/.pi / ~/.omp (or PI_CODING_AGENT_DIR)
Kimi	hooks/herdr-agent-state.sh + [[hooks]] block in config.toml
OpenCode / Kilo	plugin .js file under the agent's config plugins directory
Hermes	~/.hermes/plugins/herdr-agent-state/ + enabled in config.yaml

Uninstall (herdr integration uninstall <agent>) removes only Herdr's own entries and scripts.

Troubleshooting

• Wrong state shown: run herdr agent explain <target> to see which manifest rule matched and why.
• Integration state looks wrong: confirm the agent runs inside Herdr and the hook/plugin was installed for the same user account.
• Read what Herdr sees: herdr pane read 1-1 --source recent --lines 50

Verification checklist

• [ ] herdr integration status lists the expected integrations at current versions
• [ ] Agent shows correct working / blocked / done / idle in the sidebar
• [ ] After herdr server stop + restart, supported agent panes resume their native sessions