1 files changed, 198 insertions, 0 deletions
diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md
new file mode 100644
index 00000000..2c5ccb72
--- /dev/null
+++ b/INTEGRATIONS.md
@@ -0,0 +1,198 @@
+# integrations
+
+herdr works without any hook or plugin setup.
+
+out of the box, it detects supported agents by combining foreground process detection with screen heuristics. that is enough to give you workspace awareness with zero configuration.
+
+optional integrations improve the semantic signal on top of that.
+
+## how herdr uses integrations
+
+herdr uses a hybrid model:
+
+- **process detection** owns pane identity, liveness, and "the process is gone"
+- **agent integrations** report semantic state like `working`, `blocked`, and `idle` when the tool exposes those events
+- **screen heuristics** remain the fallback for gaps, unsupported tools, or incomplete hook surfaces
+
+that means hooks/plugins do **not** become the source of truth for pane ownership. they enrich state reporting; they do not replace process detection.
+
+## install commands
+
+```bash
+herdr integration install pi
+herdr integration install claude
+herdr integration install codex
+herdr integration install opencode
+```
+
+## uninstall commands
+
+```bash
+herdr integration uninstall pi
+herdr integration uninstall claude
+herdr integration uninstall codex
+herdr integration uninstall opencode
+```
+
+## pi
+
+install:
+
+```bash
+herdr integration install pi
+```
+
+this writes the bundled pi extension to:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+pi is the cleanest integration. it already has an authoritative hook model, so herdr can get direct state reports without guessing as much from the terminal.
+
+uninstall:
+
+```bash
+herdr integration uninstall pi
+```
+
+this removes:
+
+```text
+~/.pi/agent/extensions/herdr-agent-state.ts
+```
+
+## claude code
+
+install:
+
+```bash
+herdr integration install claude
+```
+
+this:
+
+- writes the hook script to `~/.claude/hooks/herdr-agent-state.sh`
+- updates `~/.claude/settings.json`
+
+current hook mapping:
+
+- `UserPromptSubmit` → `working`
+- `PreToolUse` → `working`
+- `PermissionRequest` → `blocked`
+- `Stop` → `idle`
+- `SessionEnd` → `release`
+
+notes:
+
+- claude's current hook surface improves state reporting, but it is not a perfect permission lifecycle.
+- when a permission prompt is canceled, claude does not currently give herdr a clean hook event that always resolves the pane out of `blocked` immediately.
+- that is acceptable in herdr's model: process detection still owns liveness, and heuristics remain the fallback for unresolved edges.
+
+uninstall:
+
+```bash
+herdr integration uninstall claude
+```
+
+this:
+
+- removes `~/.claude/hooks/herdr-agent-state.sh`
+- removes herdr-owned hook entries from `~/.claude/settings.json`
+
+## codex
+
+install:
+
+```bash
+herdr integration install codex
+```
+
+this:
+
+- writes the hook script to `~/.codex/herdr-agent-state.sh`
+- updates `~/.codex/hooks.json`
+- ensures `codex_hooks = true` in `~/.codex/config.toml`
+
+current hook mapping:
+
+- `SessionStart` → `idle`
+- `UserPromptSubmit` → `working`
+- `PreToolUse` → `working`
+- `Stop` → `idle`
+
+notes:
+
+- codex does **not** currently expose a permission-specific hook like claude or opencode, so `blocked` still depends on herdr's normal heuristics.
+- codex currently renders hook lifecycle messages in its own tui, for example `Running SessionStart hook` and `SessionStart hook (completed)`.
+- that noise is an upstream codex limitation, not a herdr-specific issue.
+- codex has a `suppressOutput` field in its hook output schema, but it is currently not effective for suppressing those tui lifecycle lines.
+
+uninstall:
+
+```bash
+herdr integration uninstall codex
+```
+
+this:
+
+- removes `~/.codex/herdr-agent-state.sh`
+- removes herdr-owned hook entries from `~/.codex/hooks.json`
+- intentionally leaves `~/.codex/config.toml` alone
+
+that last point is deliberate: herdr does **not** try to guess whether `codex_hooks = true` is still needed for some other codex hook setup.
+
+## opencode
+
+install:
+
+```bash
+herdr integration install opencode
+```
+
+this writes the bundled plugin to:
+
+```text
+~/.config/opencode/plugins/herdr-agent-state.js
+```
+
+current plugin mapping:
+
+- `permission.asked` → `blocked`
+- `permission.replied: once|always` → `working`
+- `permission.replied: reject` → `idle`
+- `session.status: busy|retry` → `working`
+- `session.status: idle` → `idle`
+- `session.idle` → `idle`
+
+notes:
+
+- opencode has the richest event surface of the currently supported integrations.
+- herdr intentionally does **not** guess that `session.deleted` means process exit. process detection still owns liveness and pane identity.
+
+uninstall:
+
+```bash
+herdr integration uninstall opencode
+```
+
+this removes:
+
+```text
+~/.config/opencode/plugins/herdr-agent-state.js
+```
+
+## known limitations
+
+- these integrations only activate inside herdr-managed panes.
+- if an agent has an incomplete hook surface, herdr falls back to process detection and screen heuristics rather than inventing lease or ttl behavior.
+- codex currently shows hook lifecycle chatter in its own tui until upstream adds a real silent mode.
+
+## troubleshooting
+
+if an install command succeeds but you do not see improved state reporting:
+
+1. make sure you launched the agent inside a herdr pane
+2. restart the agent session so it picks up the new hook/plugin config
+3. verify the expected config file was written to the path above
+4. remember that unsupported transitions still fall back to herdr's built-in heuristics