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

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

See install.md for detailed install documentation.

Provision a Fresh Checkout

A fresh clone of a project that already uses the daemon has the tracked hooks and config but no daemon (.claude/hooks-daemon/ is gitignored). Build it, at the version the project names, without changing any tracked file:

/hooks-daemon provision

The same command syncs a clone that is already there but at another version than daemon.expected_version names (after a pull), through that release's pre-deploy gate; upgrade is for moving the project itself to a new version.

See provision.md.

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 --skip-reading-confirmation=<digest>  # after reading what the gate listed

See 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":

/hooks-daemon optimise

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 — it starts by running scripts/optimise-invoke.sh, which prints the procedure to follow.

Housekeeping Pass

One invocation for the whole housekeeping pass — plan QA, docs QA, the daemon's own audits, the formatters, and optimise to close:

/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

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.

See housekeeping.md for the step list and the sub-agent contract.

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.

Check Health & Status

Verify daemon is running correctly:

/hooks-daemon health           # Quick health check

See health.md for health check details, including where the logs and the verbose environment audit are.

Explain the Status Line

Every status-line icon, explained: what it is in general and what its current value means right now — the answer to "what does this icon mean?" for a segment that has no blocking rule to look up:

/hooks-daemon status-line-explained                 # text
/hooks-daemon status-line-explained --format json    # machine-readable

See status-line-explained.md for the full output shape and design notes (it is a read-only, reference rendering — see that page for what "reference" means here).

Report an Issue

Three different actions, and the first distinction is the one that matters: only issue-report produces something safe to publish.

/hooks-daemon issue-report                             # the SOP for filing UPSTREAM
/hooks-daemon bug-report "description of the issue"    # LOCAL diagnostic, for you to read
/hooks-daemon report "daemon stopped responding"       # LOCAL investigation with a timeline

issue-report drives the whole procedure for filing a defect against the daemon's own repository: the checks that establish there IS a defect, the generator that builds a filable body, and the filing. That repository's tracker is public and an issue cannot be retracted, so the generator collects a controlled field set and never gathers the hostname, git remote, .env, config dump or logs.

bug-report and report are diagnostics for the person running them. 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. Neither is a filing artefact — both reproduce project-specific material on purpose, because you are the reader.

See issue-report.md, bug-report.md and report.md.

Capabilities (CLI verbs)

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

.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 reference-repos     # freshness of reference clones (--json, --all)
.claude/hooks-daemon/bin/hooks-daemon housekeeping --list # the housekeeping pass, step by step

Detail per capability: check.md, regen-docs.md, rule-explain.md, dev-handlers.md, plan-qa.md. bin/hooks-daemon --help lists every verb.

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 health
/hooks-daemon health

# 2. View recent logs
.claude/hooks-daemon/bin/hooks-daemon logs

# 3. Generate a quick bug report with diagnostics — for YOU to read
/hooks-daemon bug-report "description of the issue"

# 4. Generate a full investigation report with timeline — also local
/hooks-daemon report "description of the issue"

# 5. Restart to recover
/hooks-daemon restart

# 6. Concluded it is a daemon defect? File it upstream properly:
/hooks-daemon issue-report

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

    provision)
        # The project's tracked .claude/provision.sh, which exists before the
        # daemon does. Never downloaded: it is the project's own file.
        bash "$SKILL_DIR/../../provision.sh" "$@"
        ;;

    upgrade)
        bash "$SKILL_DIR/scripts/upgrade.sh" "$@"
        ;;

    health)
        bash "$SKILL_DIR/scripts/health-check.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,
        # with the human's description standing in for report.md's $ARGUMENTS
        # placeholder.
        #
        # Bash parameter expansion substitutes LITERALLY, so the description is
        # data: no character in it can terminate the replacement or be read as
        # a further command. Handing it to a stream editor instead made every
        # character syntax — a `/` (a file path in the description) ended the
        # replacement and the remainder was parsed as more editor commands.
        REPORT_PROMPT="$(cat "$SKILL_DIR/report.md")"
        printf '%s\n' "${REPORT_PROMPT//\$ARGUMENTS/$*}"
        ;;

    status-line-explained)
        # Explain every status-line icon: what it is, current value (Plan 00369).
        bash "$SKILL_DIR/scripts/daemon-cli.sh" "$SUBCOMMAND" "$@"
        ;;

    issue-report)
        # Prints the upstream-reporting procedure for Claude to follow (like
        # `report`). NOT forwarded to the CLI verb of the same name: that verb
        # takes a --fields JSON file which is the OUTPUT of steps 1 and 2, so
        # running it first would be running the procedure backwards.
        cat "$SKILL_DIR/issue-report.md"
        ;;

    restart|bug-report)
        # 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 "  provision             Build the daemon for a fresh checkout, at the version the project names"
        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 "  health                Check daemon health and status"
        echo "  status-line-explained Explain every status-line icon (--format json)"
        echo "  issue-report          File a defect UPSTREAM: the checks, the generator, the filing"
        echo "  bug-report DESC       LOCAL diagnostic bundle — for you to read, never to publish"
        echo "  report DESC           LLM-driven investigation report with a timeline (also local)"
        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 "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.