--- name: hooks-daemon 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. ## 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. See [optimise.md](optimise.md) — it starts by running `scripts/optimise-invoke.sh`, which prints the procedure to follow. ### Restart Daemon **Required after editing `.claude/hooks-daemon.yaml` or project handlers:** ```claude-code /hooks-daemon restart ``` The daemon caches config at startup — restart picks up any config or handler changes. See [restart.md](restart.md) for details. ### Regenerate Generated Docs Force-regenerate the daemon's generated documentation **without restarting**: ```claude-code /hooks-daemon regen-docs ``` Rewrites both generated artifacts to their canonical form in one shot: - `.claude/HOOKS-DAEMON.md` — the active-handler summary. - The `` 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 # 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. ### Check Environment & Configuration Run a verbose, on-demand audit of the Claude Code environment: ```claude-code /hooks-daemon check ``` 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 [check.md](check.md) for details. ### Develop Project Handlers Scaffold new project-level handlers: ```claude-code /hooks-daemon dev-handlers # Interactive handler scaffolding ``` 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 status /hooks-daemon health # 2. View recent 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" "$@" ;; report) # LLM-driven investigation report — outputs prompt for Claude to follow cat "$SKILL_DIR/report.md" | sed "s/\$ARGUMENTS/$*/" ;; 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|bug-report|check|release-notes) # Forward to daemon CLI wrapper bash "$SKILL_DIR/scripts/daemon-cli.sh" "$SUBCOMMAND" "$@" ;; help|--help|-h|"") # Show help (this SKILL.md content) echo "Usage: /hooks-daemon [args...]" echo "" echo "Available commands:" echo " install [--force] Install daemon (fresh clone)" echo " restart Restart daemon (required after config changes)" 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 " 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 " 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 "For detailed documentation, see the skill files or run:" echo " /hooks-daemon --help" ;; *) echo "Error: Unknown subcommand: $SUBCOMMAND" echo "" echo "Usage: /hooks-daemon [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.