hooks-daemon git:20260817.d609062A

Immutable. This exact content is served forever at /api/v1/blob/1bd06ac012339668.

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

```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.

### 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 `<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.

### 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.

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

    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 <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.