hooks-daemon · diff
git:20260908.f458057 to git:20260908.bf5da1f
130 added, 79 removed. Audit A to A.
---
name: hooks-daemon
- description: Manage Claude Code Hooks Daemon - install, upgrade, check health, restart, run the housekeeping pass, and report issues
- argument-hint: "[install|upgrade|optimise|housekeeping|restart|health|bug-report|report] [args...]"
+ description: Manage Claude Code Hooks Daemon - install, upgrade, check health, restart, and develop project-level handlers
+ argument-hint: "[install|upgrade|optimise|health|restart|check|dev-handlers|regen-docs|rule-explain|logs|release-notes] [args...]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Bash, Read, Write, Edit
---
# Hooks Daemon Management
Manage your Claude Code Hooks Daemon installation with these commands.
- The routed surface is deliberately small (Plan 00330): a subcommand exists
- only for something a human types. Everything else the daemon can do is a
- CLI verb, listed under [Capabilities](#capabilities-cli-verbs) below with the
- exact command — the same verb agents already run directly.
-
## Available Commands
### Install Daemon
Install the hooks daemon on a fresh clone (daemon not yet present):
```claude-code
/hooks-daemon install # Install daemon from GitHub
/hooks-daemon install --force # Force reinstall over existing
```
See [install.md](install.md) for detailed install documentation.
### Upgrade Daemon
Update to a new version of the hooks daemon:
```claude-code
/hooks-daemon upgrade # Auto-detect and upgrade to latest version
/hooks-daemon upgrade 2.14.0 # Upgrade to specific version
/hooks-daemon upgrade --force # Force reinstall current version
```
See [upgrade.md](upgrade.md) for detailed upgrade documentation.
### Optimise Configuration
The config-optimisation review — the mandatory closing step of every upgrade,
and the repeatable answer to "enable all relevant handlers and ensure optimal
configuration for this project":
```claude-code
/hooks-daemon optimise
```
- Scores five areas, surfaces handlers that are new or disabled-but-relevant, and
- applies its recommendations only on explicit confirmation.
+ Scores every registered handler across six derived areas, surfaces handlers
+ that are new or disabled-but-relevant, reports the inapplicable ones as such,
+ and applies its recommendations only on explicit confirmation.
See [optimise.md](optimise.md) — it starts by running
`scripts/optimise-invoke.sh`, which prints the procedure to follow.
- ### Housekeeping Pass
+ ### Restart Daemon
- One invocation for the whole housekeeping pass — plan QA, docs QA, the
- daemon's own audits, the formatters, and `optimise` to close:
+ **Required after editing `.claude/hooks-daemon.yaml` or project handlers:**
```claude-code
- /hooks-daemon housekeeping # report everything; formatters act
- /hooks-daemon housekeeping --apply prune-venvs # also release one held step
- /hooks-daemon housekeeping --list # the steps, in order
+ /hooks-daemon restart
```
- Report-only steps run first, in parallel, one sub-agent each; mutating steps
- follow in a fixed order with `optimise` last because it restarts the daemon.
- Only `format-markdown` and `regenerate-docs` act without confirmation — every
- other mutating step is HELD and acts only when named on `--apply`. Each
- sub-agent reports what it CHANGED, never what it read.
+ The daemon caches config at startup — restart picks up any config or handler changes.
- See [housekeeping.md](housekeeping.md) for the step list and the sub-agent
- contract.
+ See [restart.md](restart.md) for details.
- ### Restart Daemon
+ ### Regenerate Generated Docs
- **Required after editing `.claude/hooks-daemon.yaml` or project handlers:**
+ Force-regenerate the daemon's generated documentation **without restarting**:
```claude-code
- /hooks-daemon restart
+ /hooks-daemon regen-docs
```
- The daemon caches config at startup — restart picks up any config or handler changes.
+ Rewrites both generated artifacts to their canonical form in one shot:
- See [restart.md](restart.md) for details.
+ - `.claude/HOOKS-DAEMON.md` — the active-handler summary.
+ - The `<hooksdaemon>` guidance block inside your project `CLAUDE.md`.
+ This is the explicit way to recover both files after a **git merge/rebase conflict**
+ left them stale or conflict-marked — run it, then stage the clean result. (A normal
+ `restart` also refreshes these, but `regen-docs` does it as a one-shot with no daemon
+ bounce.)
+
+ See [regen-docs.md](regen-docs.md) for details.
+
+ ### Explain a Rule
+
+ Get the full, verbatim detail for any daemon rule on demand — independent of
+ whether it has already fired this session:
+
+ ```claude-code
+ /hooks-daemon rule-explain R-GIT-RESET-HARD
+ /hooks-daemon rule-explain --list # every known rule ID + handler
+ ```
+
+ See [rule-explain.md](rule-explain.md) for details.
+
+ ### Plan QA
+
+ Lint and sweep the plan tree on demand — the same checks the edit-time lint,
+ commit gate and session sweep run automatically:
+
+ ```bash
+ .claude/hooks-daemon/bin/hooks-daemon plan-qa --sweep # whole tree (exit 1 on findings)
+ .claude/hooks-daemon/bin/hooks-daemon plan-qa --lint <PLAN.md> # one plan document
+ .claude/hooks-daemon/bin/hooks-daemon plan-qa --check-staged # what the commit gate will say
+ ```
+
+ See [plan-qa.md](plan-qa.md) for details.
+
### Check Health & Status
Verify daemon is running correctly:
```claude-code
/hooks-daemon health # Quick health check
+ /hooks-daemon logs # View last 50 lines of logs
+ /hooks-daemon logs --follow # Stream logs in real-time
```
- See [health.md](health.md) for health check details, including where the logs
- and the verbose environment audit are.
+ See [health.md](health.md) for health check details.
- ### Report an Issue
+ ### Check Environment & Configuration
- Two different actions — pick by what you need:
+ Run a verbose, on-demand audit of the Claude Code environment:
```claude-code
- /hooks-daemon bug-report "description of the issue" # diagnostic bundle for maintainers
- /hooks-daemon report "daemon stopped responding" # LLM-driven investigation with a timeline
+ /hooks-daemon check
```
- `bug-report` is fast and mechanical: version, status, config, handlers, recent
- logs and a health checklist, written to `untracked/bug-reports/`. `report` is
- an investigation: it collects evidence, builds a timeline, and writes a
- narrative to `./untracked/hooks-daemon-{description}.md`. Reach for
- `bug-report` first; use `report` when the bug-report was not enough to explain
- what happened.
+ Reports Claude Code optimal-config settings (max output tokens, bash working
+ directory, effort level, extended thinking, agent teams, auto-memory) with
+ fix instructions, plus the container runtime, git `core.fileMode`, and
+ hook-registration drift. This is the detail that SessionStart deliberately
+ keeps quiet — SessionStart now only speaks when something needs action.
- See [bug-report.md](bug-report.md) and [report.md](report.md).
+ See [check.md](check.md) for details.
- ## Capabilities (CLI verbs)
+ ### Develop Project Handlers
- These are things the daemon does that nobody types as a skill subcommand, so
- they are not routed. Run the verb directly (on a self-install the wrapper is
- `bin/hooks-daemon` at the repository root):
+ Scaffold new project-level handlers:
- ```bash
- .claude/hooks-daemon/bin/hooks-daemon logs # last 50 log lines (--follow to stream)
- .claude/hooks-daemon/bin/hooks-daemon status # one-line daemon status
- .claude/hooks-daemon/bin/hooks-daemon handlers # every loaded handler with its priority
- .claude/hooks-daemon/bin/hooks-daemon config-validate # validate the project config (validate-config also works)
- .claude/hooks-daemon/bin/hooks-daemon check # verbose environment & configuration audit
- .claude/hooks-daemon/bin/hooks-daemon regenerate-docs # rewrite HOOKS-DAEMON.md + the CLAUDE.md block, no restart
- .claude/hooks-daemon/bin/hooks-daemon explain-rule R-GIT-RESET-HARD # full detail for a rule (--list for every ID)
- .claude/hooks-daemon/bin/hooks-daemon explain-handler destructive_git # a handler's rules + guidance
- .claude/hooks-daemon/bin/hooks-daemon init-project-handlers # scaffold project-level handlers
- .claude/hooks-daemon/bin/hooks-daemon release-notes # installed version's notes (--latest, --version, --list)
- .claude/hooks-daemon/bin/hooks-daemon plan-qa --sweep # plan-tree drift (--lint <PLAN.md>, --check-staged)
- .claude/hooks-daemon/bin/hooks-daemon housekeeping --list # the housekeeping pass, step by step
+ ```claude-code
+ /hooks-daemon dev-handlers # Interactive handler scaffolding
```
- Detail per capability: [check.md](check.md), [regen-docs.md](regen-docs.md),
- [rule-explain.md](rule-explain.md), [dev-handlers.md](dev-handlers.md),
- [plan-qa.md](plan-qa.md). `bin/hooks-daemon --help` lists every verb.
+ See [dev-handlers.md](dev-handlers.md) for handler development guide.
+ ### Investigate an Issue
+
+ Generate a detailed investigation report with timeline, evidence, and analysis:
+
+ ```claude-code
+ /hooks-daemon report "daemon stopped responding during edits"
+ ```
+
+ The report is saved to `./untracked/hooks-daemon-{description}.md` for sharing with maintainers.
+
+ See [report.md](report.md) for details.
+
+ ### Read Release Notes
+
+ Show the daemon's release notes without leaving the terminal. With no flag it
+ shows the notes for the version you currently have installed:
+
+ ```claude-code
+ /hooks-daemon release-notes # installed version's notes
+ /hooks-daemon release-notes --latest # newest available version
+ /hooks-daemon release-notes --version 3.27.0 # a specific version
+ /hooks-daemon release-notes --from 3.20.0 --to 3.27.0 # everything you gained upgrading
+ /hooks-daemon release-notes --list # list available versions
+ /hooks-daemon release-notes --version 3.27.0 --format json
+ ```
+
+ Notes are read from the per-version `RELEASES/vX.Y.Z.md` files that ship with
+ the install — no network access required. `--from` is exclusive and `--to` is
+ inclusive, matching the upgrade semantics (the notes for everything you gained).
+
## Quick Start
After editing `.claude/hooks-daemon.yaml`:
```claude-code
/hooks-daemon restart # Apply config changes
/hooks-daemon health # Verify it's running
```
If you're experiencing issues:
```claude-code
- # 1. Check daemon health
+ # 1. Check daemon status
/hooks-daemon health
# 2. View recent logs
- .claude/hooks-daemon/bin/hooks-daemon logs
+ /hooks-daemon logs
# 3. Generate a quick bug report with diagnostics
/hooks-daemon bug-report "description of the issue"
# 4. Generate a full investigation report with timeline
/hooks-daemon report "description of the issue"
# 5. Restart to recover
/hooks-daemon restart
```
## Troubleshooting
See [references/troubleshooting.md](references/troubleshooting.md) for common issues and solutions.
## Implementation
Parse subcommand and route to appropriate script:
```bash
# Get skill directory (where this SKILL.md is located)
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# Parse subcommand from $ARGUMENTS
SUBCOMMAND="${1:-help}"
shift || true # Remove subcommand from arguments
# Route to appropriate script
case "$SUBCOMMAND" in
install)
bash "$SKILL_DIR/scripts/install.sh" "$@"
;;
upgrade)
bash "$SKILL_DIR/scripts/upgrade.sh" "$@"
;;
health)
bash "$SKILL_DIR/scripts/health-check.sh" "$@"
;;
+ dev-handlers)
+ bash "$SKILL_DIR/scripts/init-handlers.sh" "$@"
+ ;;
+
optimise|optimize)
# Prints the review procedure for Claude to follow (like `report`).
# `optimize` is accepted so the US spelling does not hit the
# unknown-subcommand branch.
bash "$SKILL_DIR/scripts/optimise-invoke.sh" "$@"
;;
- housekeeping)
- # Prints the full-pass procedure (Plan 00330); every step is then
- # delegated to a sub-agent. --apply <step> releases a held step.
- bash "$SKILL_DIR/scripts/daemon-cli.sh" housekeeping "$@"
- ;;
-
report)
# LLM-driven investigation report — outputs prompt for Claude to follow
cat "$SKILL_DIR/report.md" | sed "s/\$ARGUMENTS/$*/"
;;
- restart|bug-report)
- # Forward to daemon CLI wrapper.
+ regen-docs|regenerate-docs)
+ # User-facing alias regen-docs maps to the CLI command regenerate-docs.
+ bash "$SKILL_DIR/scripts/daemon-cli.sh" regenerate-docs "$@"
+ ;;
+
+ rule-explain)
+ # User-facing alias rule-explain maps to the CLI command explain-rule.
+ bash "$SKILL_DIR/scripts/daemon-cli.sh" explain-rule "$@"
+ ;;
+
+ logs|status|restart|handlers|config-validate|validate-config|bug-report|check|release-notes)
+ # Forward to daemon CLI wrapper. The CLI accepts validate-config as
+ # an alias of config-validate, and defaults the path to the project
+ # config, so both spellings work with no argument.
bash "$SKILL_DIR/scripts/daemon-cli.sh" "$SUBCOMMAND" "$@"
;;
help|--help|-h|"")
# Show help (this SKILL.md content)
echo "Usage: /hooks-daemon <command> [args...]"
echo ""
echo "Available commands:"
echo " install [--force] Install daemon (fresh clone)"
- echo " upgrade [VERSION] Upgrade daemon to new version"
- echo " optimise Config-optimisation review (closes every upgrade)"
- echo " housekeeping [--apply STEP] [--list]"
- echo " Full housekeeping pass: reports first, held steps on request, optimise last"
echo " restart Restart daemon (required after config changes)"
+ echo " optimise Config-optimisation review (closes every upgrade)"
+ echo " regen-docs Force-regenerate HOOKS-DAEMON.md + CLAUDE.md block"
+ echo " rule-explain ID Full detail for a rule ID, or --list every rule"
echo " health Check daemon health and status"
- echo " bug-report DESC Diagnostic bundle for maintainers"
- echo " report DESC LLM-driven investigation report with a timeline"
+ echo " upgrade [VERSION] Upgrade daemon to new version"
+ echo " dev-handlers Scaffold new project handlers"
+ echo " logs [--follow] View daemon logs"
+ echo " status Show daemon status"
+ echo " handlers List loaded handlers"
+ echo " check Verbose environment & configuration audit"
+ echo " config-validate [PATH] Validate a config (default: the project's); validate-config also works"
+ echo " bug-report DESC Generate bug report with diagnostics"
+ echo " report DESC Investigate an issue and generate a detailed report"
+ echo " release-notes [opts] Show release notes (installed version by default)"
echo ""
echo "After editing .claude/hooks-daemon.yaml, always run: /hooks-daemon restart"
echo ""
- echo "Everything else is a CLI verb: .claude/hooks-daemon/bin/hooks-daemon --help"
- echo "(logs, status, handlers, config-validate, check, regenerate-docs, explain-rule,"
- echo " init-project-handlers, release-notes, plan-qa ...)"
+ echo "For detailed documentation, see the skill files or run:"
+ echo " /hooks-daemon <command> --help"
;;
*)
echo "Error: Unknown subcommand: $SUBCOMMAND"
echo ""
echo "Usage: /hooks-daemon <command> [args...]"
echo "Run '/hooks-daemon help' for available commands."
exit 1
;;
esac
```
**Note**: All daemon management commands require manual user approval. The daemon will not auto-invoke these operations.