[DOCS] Setup hook documentation missing (possible regression)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks#setup

Section/Topic

Setup hook event type

Current Documentation

The hooks reference page at https://code.claude.com/docs/en/hooks lists 9 hook events:

• PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification

The #setup anchor exists in the URL but shows no content.

<img width="2830" height="1812" alt="Image" src="https://github.com/user-attachments/assets/4dd019c9-5a76-4db7-ae6b-b7ae54c90cd8" />

What's Wrong or Missing?

The Setup hook event is not documented despite:

1. CHANGELOG 2.1.10 announcing it: "Added new Setup hook event that can be triggered via --init, --init-only, or --maintenance CLI flags"

1. Issue #18724 being closed as resolved on 2026-01-21, claiming documentation was added

1. A YouTube video from this week showing the Setup section was present in the docs (suggesting a regression)

<img width="2914" height="1828" alt="Image" src="https://github.com/user-attachments/assets/322cd5f2-c9e3-4096-9bb9-2da91bbf8d80" />

Missing documentation includes:

• Setup event description and when it fires
• Matchers: init, maintenance
• CLI flags: --init, --init-only, --maintenance
• Hook input schema (environment variables provided)
• Example configuration in settings.json

Suggested Improvement

The documentation should include a Setup section similar to other hook events:

Setup

Runs before Claude Code session starts. Triggered by CLI flags.

Matchers: init, maintenance

CLI Flags:

• --init: Run setup hooks, then start interactive session
• --init-only: Run setup hooks, then exit
• --maintenance: Run maintenance hooks, then exit

Example configuration:

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [{ "type": "command", "command": ".claude/hooks/setup.sh" }]
      }
    ]
  }
}

Impact

High - Prevents users from using a feature

Additional Context

Empirical Testing

As a side note, I did also verify the bug reported in #21860. I tested Setup hooks in a minimal project and got these results:

| Flag | Recognized? | Hook Fired? | Notes |
|------|-------------|-------------|-------|
| --init-only | ✅ | ✅ | Works correctly, exits after hook |
| --init | ✅ | ❌ | Opens console, hook never fires |
| --maintenance | ✅ | ❌ | Opens console, hook never fires |

// .claude/settings.json
{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.sh"
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# setup_init.sh
# This script runs when `claude --init` or `claude --init-only` is called

TIMESTAMP=$(date -Iseconds)
LOG_FILE="$(dirname "$0")/../../.hook-log.txt"

echo "[$TIMESTAMP] Setup:init hook fired" >> "$LOG_FILE"
echo "  PWD: $PWD" >> "$LOG_FILE"
echo "  CLAUDE_* env vars:" >> "$LOG_FILE"
env | grep CLAUDE_ >> "$LOG_FILE" 2>/dev/null || echo "  (none)" >> "$LOG_FILE"
echo "" >> "$LOG_FILE"

# Output for Claude to see
echo "Setup:init hook executed successfully"

#!/bin/bash
# setup_maintenance.sh
# This script runs when `claude --maintenance` is called

TIMESTAMP=$(date -Iseconds)
LOG_FILE="$(dirname "$0")/../../.hook-log.txt"

echo "[$TIMESTAMP] Setup:maintenance hook fired" >> "$LOG_FILE"
echo "  PWD: $PWD" >> "$LOG_FILE"
echo "  CLAUDE_* env vars:" >> "$LOG_FILE"
env | grep CLAUDE_ >> "$LOG_FILE" 2>/dev/null || echo "  (none)" >> "$LOG_FILE"
echo "" >> "$LOG_FILE"

# Output for Claude to see
echo "Setup:maintenance hook executed successfully"

## .hook-log.txt
[2026-02-01T14:13:15-06:00] Setup:init hook fired
  PWD: /Users/cedric/src/spantree-fluent/fluent-toolkit/.scratch/spikes/claude-code-setup-hook
  CLAUDE_* env vars:
CLAUDE_CODE_ENTRYPOINT=sdk-cli
CLAUDE_PROJECT_DIR=/Users/cedric/src/spantree-fluent/fluent-toolkit/.scratch/spikes/claude-code-setup-hook
CLAUDE_CODE_SSE_PORT=26667
CLAUDE_ENV_FILE=/Users/cedric/.claude/session-env/b1337b26-0ca0-4504-8e7c-cabc6703f3ae/setup-hook-0.sh

Related Issues

• #18724 - Original docs request (closed as resolved 2026-01-21)
• #21860 - Bug: --init doesn't trigger hooks (our testing shows --maintenance also affected)

Environment

Claude Code version: v2.1.29
Date checked: 2026-02-01