hooks-daemon

name	hooks-daemon
description	Manage Claude Code Hooks Daemon - install, upgrade, check health, restart, and develop project-level handlers
argument-hint	[install|upgrade|health|restart|check|dev-handlers|regen-docs|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):

/hooks-daemon install          # Install daemon from GitHub
/hooks-daemon install --force  # Force reinstall over existing

See install.md for detailed install documentation.

Upgrade Daemon

Update to a new version of the hooks daemon:

/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 for detailed upgrade documentation.

Restart Daemon

Required after editing .claude/hooks-daemon.yaml or project handlers:

/hooks-daemon restart

The daemon caches config at startup — restart picks up any config or handler changes.

See restart.md for details.

Regenerate Generated Docs

Force-regenerate the daemon's generated documentation without restarting:

/hooks-daemon regen-docs

Rewrites both generated artifacts to their canonical form in one shot:

• .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 for details.

Check Health & Status

Verify daemon is running correctly:

/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 for health check details.

Check Environment & Configuration

Run a verbose, on-demand audit of the Claude Code environment:

/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 for details.

Develop Project Handlers

Scaffold new project-level handlers:

/hooks-daemon dev-handlers     # Interactive handler scaffolding

See dev-handlers.md for handler development guide.

Investigate an Issue

Generate a detailed investigation report with timeline, evidence, and analysis:

/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 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:

/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:

/hooks-daemon restart   # Apply config changes
/hooks-daemon health    # Verify it's running

If you're experiencing issues:

# 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 for common issues and solutions.

Implementation

Parse subcommand and route to appropriate script:

# 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 "$@"
        ;;

    logs|status|restart|handlers|validate-config|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 <command> [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 "  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 <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.