diff options
Diffstat (limited to 'INTEGRATIONS.md')
| -rw-r--r-- | INTEGRATIONS.md | 44 |
1 files changed, 32 insertions, 12 deletions
diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index ec4e4884..23b41ab8 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -55,6 +55,14 @@ this writes the bundled pi extension to: ~/.pi/agent/extensions/herdr-agent-state.ts ``` +if `PI_CODING_AGENT_DIR` is set, herdr uses that agent directory instead and writes to: + +```text +$PI_CODING_AGENT_DIR/extensions/herdr-agent-state.ts +``` + +`~` is expanded in `PI_CODING_AGENT_DIR`. + pi is the cleanest integration. it already has an authoritative hook model, so herdr can get direct state reports over the socket api without guessing as much from the terminal. bundled source: [`src/integration/assets/pi/herdr-agent-state.ts`](./src/integration/assets/pi/herdr-agent-state.ts) @@ -65,11 +73,7 @@ uninstall: herdr integration uninstall pi ``` -this removes: - -```text -~/.pi/agent/extensions/herdr-agent-state.ts -``` +this removes the same extension path herdr would install, using `PI_CODING_AGENT_DIR` when it is set. ## claude code @@ -84,6 +88,8 @@ this: - writes the hook script to `~/.claude/hooks/herdr-agent-state.sh` - updates `~/.claude/settings.json` +if `CLAUDE_CONFIG_DIR` is set, herdr uses that directory instead, for example `$CLAUDE_CONFIG_DIR/hooks/herdr-agent-state.sh` and `$CLAUDE_CONFIG_DIR/settings.json`. `~` is expanded in `CLAUDE_CONFIG_DIR`. + bundled source: [`src/integration/assets/claude/herdr-agent-state.sh`](./src/integration/assets/claude/herdr-agent-state.sh) current hook mapping: @@ -102,6 +108,7 @@ notes: - claude code hooks also run inside subagents. herdr treats subagent `working` and `blocked` reports as real pane state. - subagent stop/release events are converted to `working` by the bundled hook script so a completed subagent does not make the parent claude pane look idle. - `PostToolUse` and `PostToolUseFailure` move the pane back to `working` after a permissioned tool call resolves. +- some non-claude tools, including grok cli, may load claude settings or plugins. herdr ignores conflicting known-agent hook labels once native foreground-process detection identifies a different known agent. uninstall: @@ -109,10 +116,7 @@ uninstall: herdr integration uninstall claude ``` -this: - -- removes `~/.claude/hooks/herdr-agent-state.sh` -- removes herdr-owned hook entries from `~/.claude/settings.json` +this removes the same hook path and settings entries herdr would install, using `CLAUDE_CONFIG_DIR` when it is set. ## codex @@ -129,6 +133,8 @@ this: - ensures `hooks = true` under `[features]` in `~/.codex/config.toml` - migrates the deprecated top-level `[features] codex_hooks = true` setting to `hooks = true` +if `CODEX_HOME` is set, herdr uses that directory instead, for example `$CODEX_HOME/herdr-agent-state.sh`, `$CODEX_HOME/hooks.json`, and `$CODEX_HOME/config.toml`. `~` is expanded in `CODEX_HOME`. + bundled source: [`src/integration/assets/codex/herdr-agent-state.sh`](./src/integration/assets/codex/herdr-agent-state.sh) current hook mapping: @@ -153,9 +159,9 @@ 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 +- removes the same hook path herdr would install, using `CODEX_HOME` when it is set +- removes herdr-owned hook entries from the matching `hooks.json` +- intentionally leaves the matching `config.toml` alone that last point is deliberate: herdr does **not** try to guess whether `hooks = true` is still needed for some other codex hook setup. @@ -204,6 +210,20 @@ this removes: ~/.config/opencode/plugins/herdr-agent-state.js ``` +## grok cli + +herdr does not currently install a grok hook or plugin. + +grok is heuristic-only in herdr. herdr detects `grok` and `grok-build` from the foreground process and uses screen heuristics for `working`, `blocked`, and `idle` states. + +grok cli may load claude settings or plugins as a compatibility feature, including hooks from `~/.claude/settings.json`. if that causes the claude herdr hook to run in a grok pane, herdr ignores the conflicting `claude` hook label once native foreground-process detection identifies the pane as `grok`. + +## amp + +herdr does not currently install an Amp plugin. + +Amp's public plugin API exposes lifecycle and tool-call hooks, but not passive permission/request-blocked events. A Herdr Amp plugin that only reports `idle` and `working` would take hook authority for the pane and mask Herdr's existing screen heuristics for Amp `blocked` states. Until Amp exposes permission state as an observable plugin event, Amp remains heuristic-only in Herdr. + ## known limitations - these integrations only activate inside herdr-managed panes. |