Files
Tejas ChopraandClaude Opus 5.5 df9eefd4f0 fix(plugins): keep the hook launcher's Python fallback off the project dir
When no headroom executable is found, headroom-hook.sh falls back to
`python -c 'import headroom'` and `python -m headroom.cli`, both of
which put the current directory (the opened project) first on sys.path.
A headroom/ directory in the project was imported instead of the
installed package. Both calls now pass -P (Python 3.11+), so only an
installed headroom is used; older interpreters reject -P and are skipped.

Assay-Kind: bugfix
Assay-Ask: The agent-hooks launcher's Python fallback imported a headroom package from the opened
 project's directory instead of the installed one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:29:34 -08:00
..

Headroom agent hooks

This plugin exposes lightweight startup hooks for Claude Code and GitHub Copilot CLI.

The hooks resolve and call:

headroom init hook ensure

That hidden helper checks for a matching durable headroom init deployment and starts it if needed.

When CLAUDE_PLUGIN_ROOT points to a readable launcher, resolution order is HEADROOM_BIN, headroom on PATH, then headroom and headroom.exe in $HOME/.local/bin, $HOME/.local/share/uv/tools/headroom-ai/bin, ${PIPX_HOME:-$HOME/.local/pipx}/venvs/headroom-ai/bin, /opt/homebrew/bin, and /usr/local/bin. If no executable is found, HEADROOM_PYTHON, python3, and python are checked for an importable headroom module and invoked as python -m headroom.cli init hook ensure.

Set HEADROOM_BIN or HEADROOM_PYTHON to override discovery. An absent CLI emits one actionable diagnostic and exits successfully, so the host hook remains nonblocking. Without a readable launcher, the hook runs bare headroom init hook ensure from PATH with none of the discovery above. Copilot CLI on Windows uses the manifest's powershell entry, which does the same.