> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commanderplugin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks Reference — All 25 CC Commander Lifecycle Hooks

> Complete reference for all 25 CC Commander hooks: what each one does, when it fires, what lifecycle event it attaches to, and how to disable it.

Hooks are lifecycle scripts that run automatically during Claude Code sessions. They attach to specific events — `PreToolUse`, `PostToolUse`, `PreCompact`, and `Stop` — and fire without any prompting. CC Commander ships 15 kit-native hooks in its standalone configuration, plus an extended set when ECC is installed.

There are two hook configurations:

| File                    | For                      | Hook count                                  |
| ----------------------- | ------------------------ | ------------------------------------------- |
| `hooks.json`            | Users with ECC installed | 34 hooks (15 kit-native + 19 ECC-inherited) |
| `hooks-standalone.json` | Users without ECC        | 15 kit-native hooks only                    |

The hooks below cover all 25 hooks referenced in the CC Commander hook directory: 15 wired in the standalone configuration plus 10 additional hooks that ship with CC Commander and are ready to activate.

***

## Hook Directory

<AccordionGroup>
  <Accordion title="careful-guard — Block destructive commands">
    **Event:** PreToolUse (`Bash`)

    Intercepts Bash tool calls and blocks destructive patterns: `rm -rf`, `DROP TABLE`, `--force` git push, and similar commands. Uses regex pattern matching — this is a best-effort safety net, not a security boundary. Always combine with a `settings.json` deny list.

    **Disable:** `KZ_DISABLE_CAREFUL_GUARD=1`
  </Accordion>

  <Accordion title="pre-commit-verify — TypeScript check before git commit">
    **Event:** PreToolUse (`Bash`)

    Runs `tsc --noEmit` before any `git commit` Bash call. Blocks the commit if TypeScript errors are present, forcing you to fix type errors before they enter version control.

    **Disable:** `KZ_DISABLE_PRE_COMMIT_VERIFY=1`
  </Accordion>

  <Accordion title="confidence-gate — Warn on risky multi-file operations">
    **Event:** PreToolUse (`Bash`)

    Warns before executing multi-file Bash operations like `sed -i` on globs or `find -exec`. Gives you a chance to review scope before a command touches many files at once.

    **Disable:** `KZ_DISABLE_CONFIDENCE_GATE=1`
  </Accordion>

  <Accordion title="context-guard — Monitor context window and auto-save">
    **Event:** PostToolUse (`*`)

    Monitors context window fill level. Warns at approximately 70% usage and auto-saves the session so you can resume cleanly after compaction.

    **Disable:** `KZ_DISABLE_CONTEXT_GUARD=1`
  </Accordion>

  <Accordion title="auto-checkpoint — Git-stash checkpoint every 10 edits">
    **Event:** PostToolUse (`Edit|Write`)

    Creates a git-stash checkpoint every 10 file edits. Gives you a rollback point without interrupting the session. Default interval is 10 edits.

    **Disable:** `KZ_DISABLE_AUTO_CHECKPOINT=1`
  </Accordion>

  <Accordion title="cost-alert — Warn when approaching budget">
    **Event:** PostToolUse (`*`)

    Fires cost proxy alerts at two thresholds: approximately $0.50 (after ~30 tool calls) and approximately $2.00 (after \~60 tool calls). Helps you stay aware of session spend before it escalates.

    **Disable:** `KZ_DISABLE_COST_ALERT=1`
  </Accordion>

  <Accordion title="auto-lessons — Extract lessons from corrections">
    **Event:** PostToolUse (`*`)

    Captures errors and corrections as they happen and appends them to `tasks/lessons.md`. These lessons are available at the next session start and feed into the knowledge compounding system.

    **Disable:** `KZ_DISABLE_AUTO_LESSONS=1`
  </Accordion>

  <Accordion title="rate-predictor — Predict rate limit timing">
    **Event:** PostToolUse (`*`)

    Calculates your tool call rate and predicts when you will hit rate limits. Surfaces this as a warning so you can plan compaction or model switches in advance.

    **Disable:** `KZ_DISABLE_RATE_PREDICTOR=1`
  </Accordion>

  <Accordion title="auto-notify — Desktop notifications for significant events">
    **Event:** PostToolUse (`Bash`)

    Fires desktop notifications when significant events occur — PR created, deploy complete, build finished. Lets you step away from the terminal during long tasks.

    **Disable:** `KZ_DISABLE_AUTO_NOTIFY=1`
  </Accordion>

  <Accordion title="preuse-logger — Log all tool use">
    **Event:** PostToolUse (`Bash`)

    Logs every tool call with timestamps and arguments for cost analysis and audit trails. Outputs to a structured log that you can analyze later.

    **Disable:** `KZ_DISABLE_PREUSE_LOGGER=1`
  </Accordion>

  <Accordion title="self-verify — Verify file changes against stated intent">
    **Event:** Stop (`*`)

    After each Stop event, automatically checks modified files against the task's stated intent. Catches drift — situations where Claude changed something it was not asked to change.

    **Disable:** `KZ_DISABLE_SELF_VERIFY=1`
  </Accordion>

  <Accordion title="status-checkin — Session end status summary">
    **Event:** Stop (`*`)

    Prints a branded status footer at session end with a summary of what was completed, what remains, and cost. Fires every 10 responses by default.

    **Disable:** `KZ_DISABLE_STATUS_CHECKIN=1`
  </Accordion>

  <Accordion title="session-end-verify — Final verification at session end">
    **Event:** Stop (`*`)

    At session end, checks all modified files for incomplete tasks, uncommitted changes, and leftover `TODO`/`FIXME` markers. Surfaces anything that should be resolved before the session closes.

    **Disable:** `KZ_DISABLE_SESSION_END_VERIFY=1`
  </Accordion>

  <Accordion title="session-coach — Periodic coaching nudges">
    **Event:** Stop (`*`)

    Fires periodic coaching nudges during long sessions: skill suggestions, checkpoint reminders, and workflow tips. Interval is configurable. Disable entirely with `CC_COACH_DISABLE=1`.

    **Controls:** `CC_COACH_DISABLE=1` to disable · `CC_COACH_INTERVAL=<n>` to set nudge interval (number of responses between nudges, default: 10)
  </Accordion>

  <Accordion title="pre-compact — Save state before context compaction">
    **Event:** PreCompact (`*`)

    Saves the current working directory, git branch, list of modified files, and active tasks before context compaction fires. This state is restored automatically when you resume.

    **Disable:** `KZ_DISABLE_PRE_COMPACT=1`
  </Accordion>

  <Accordion title="context-rot-monitor — Tiered context quality warnings">
    **Event:** PostToolUse (`*`) — requires ECC

    Monitors context window fill level with tiered warnings at 60%, 75%, 85%, and 90%. More granular than `context-guard`. Available in the ECC hook configuration.

    **Disable:** `CC_CONTEXT_ROT_DISABLE=1`
  </Accordion>

  <Accordion title="vendor-update-notify — Alert when vendor packages have updates">
    **Event:** Available, not wired by default

    Scans vendor submodules for available updates and surfaces an alert. Run `ccc --update` to pull the latest vendor packages.
  </Accordion>

  <Accordion title="claude-md-staleness — Warn when CLAUDE.md needs updating">
    **Event:** Available, not wired by default

    Checks the age and content of your `CLAUDE.md` files and warns when they appear stale — for example, when the stack has changed but the instructions have not been updated.
  </Accordion>

  <Accordion title="openclaw-adapter — Bidirectional OpenClaw event forwarding">
    **Event:** PostToolUse (`Edit|Write|Bash`)

    Forwards CC Commander tool events to the OpenClaw platform in real time. Requires OpenClaw to be running before launching CCC.
  </Accordion>

  <Accordion title="openclaw-sync — Sync CCC state with OpenClaw">
    **Event:** Available, not wired by default

    Synchronises CC Commander session state with the OpenClaw gateway so other agents in the platform can see current context, cost, and task status.
  </Accordion>

  <Accordion title="linear-auto-track — Auto-track work in Linear">
    **Event:** Available, not wired by default

    Automatically creates or updates Linear issues based on the tasks CCC dispatches. Requires Linear credentials configured in settings.
  </Accordion>

  <Accordion title="linear-phase-gate — Phase gates for Linear issue progression">
    **Event:** Available, not wired by default

    Enforces Linear workflow phase gates — prevents an issue from advancing to the next status until the required conditions are met.
  </Accordion>

  <Accordion title="linear-pr-link — Link PRs to Linear issues">
    **Event:** Available, not wired by default

    Detects when a pull request is created and automatically links it to the related Linear issue.
  </Accordion>

  <Accordion title="status-reporter — Progress updates for long-running tasks">
    **Event:** Available, not wired by default

    Generates structured progress reports during long-running sessions and can forward them to Slack, Discord, or email at configurable intervals.
  </Accordion>

  <Accordion title="daily-improvement-scan — Scan for improvement opportunities">
    **Event:** Available, not wired by default

    Runs a daily scan of the codebase and knowledge base to surface improvement opportunities. Outputs a proposal queue that feeds into the continuous improvement workflow.
  </Accordion>
</AccordionGroup>

***

## Environment Controls

| Variable                   | Effect                                                 | Scope               |
| -------------------------- | ------------------------------------------------------ | ------------------- |
| `CC_COACH_DISABLE=1`       | Disable `session-coach` nudges entirely                | session-coach       |
| `CC_COACH_INTERVAL=<n>`    | Number of responses between coach nudges (default: 10) | session-coach       |
| `CC_NO_COLOR=1`            | Disable ANSI colors in all hook output                 | all hooks           |
| `CC_NO_ANIMATION=1`        | Disable spinner and animation output                   | all hooks           |
| `CC_CONTEXT_ROT_DISABLE=1` | Disable `context-rot-monitor` warnings                 | context-rot-monitor |

Individual hooks respect their own disable flags (e.g. `KZ_DISABLE_CAREFUL_GUARD=1`) so you can turn off specific behavior without affecting the rest.

***

## Activating an Unactivated Hook

Hooks that ship with CC Commander but are not wired by default can be activated by adding them to `~/.claude/settings.json`:

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/vendor-update-notify.js"
          }
        ]
      }
    ]
  }
}
```

<Warning>
  Hooks run with the same permissions as your Claude Code session. Review any hook script before activating it. The `careful-guard` hook is a best-effort safety net based on regex matching — always back it up with explicit deny rules in `settings.json`.
</Warning>