> ## 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: Lifecycle Automation for Every Claude Code Session

> CC Commander's 25 hooks run at Claude Code lifecycle events to guard your code, track costs, extract lessons, and coach your workflow — no setup required.

Hooks are JavaScript scripts that run at specific Claude Code lifecycle events — before a tool executes, after it completes, when the context is about to compact, and when a session ends. CCC ships 25 hooks that handle safety checks, cost monitoring, knowledge extraction, and session coaching without any wiring on your part.

The installer copies all hooks to `~/.claude/hooks/` and registers them in your `settings.json` automatically.

## Lifecycle events

Claude Code fires hooks at these events:

| Event                | When it fires                          |
| -------------------- | -------------------------------------- |
| `PreToolUse`         | Before any tool call executes          |
| `PostToolUse`        | After a tool call completes            |
| `PreCompact`         | Before the context window is compacted |
| `SessionStart`       | When a new Claude Code session begins  |
| `Stop`               | When Claude finishes a response turn   |
| `SessionEnd`         | When the session terminates            |
| `PostToolUseFailure` | When a tool call fails                 |

## The 25 kit-native hooks

### Safety hooks (PreToolUse)

<AccordionGroup>
  <Accordion title="careful-guard">
    Blocks destructive commands before they run — `rm -rf`, `DROP TABLE`, force push, and other irreversible operations. Uses regex pattern matching as a best-effort safety net. Combine with your `settings.json` deny list for stronger protection.
  </Accordion>

  <Accordion title="pre-commit-verify">
    Runs a TypeScript check (`tsc`) before every `git commit`. Blocks the commit if type errors exist, preventing broken code from entering your history.
  </Accordion>

  <Accordion title="confidence-gate">
    Warns before multi-file bash operations — `sed -i` on globs, `find -exec`, and similar broad-scope commands — giving you a chance to review before Claude touches many files at once.
  </Accordion>
</AccordionGroup>

### Monitoring hooks (PostToolUse)

<AccordionGroup>
  <Accordion title="context-guard">
    Tracks context window usage after every tool call. Warns at approximately 70% usage and auto-saves the session so you can resume cleanly after compaction.
  </Accordion>

  <Accordion title="auto-checkpoint">
    Creates a `git stash` checkpoint automatically every 10 file edits. If a session goes sideways, you have a recent rollback point.
  </Accordion>

  <Accordion title="cost-alert">
    Monitors estimated session cost. Fires alerts at approximately $0.50 (around 30 tool calls) and $2.00 (around 60 tool calls) so you are never surprised at the end of a long session.
  </Accordion>

  <Accordion title="auto-lessons">
    Captures errors and corrections during the session and appends them to `tasks/lessons.md` in your project. Builds a running log of what went wrong and how it was fixed.
  </Accordion>

  <Accordion title="rate-predictor">
    Tracks the tool call rate across the session and predicts when you are likely to hit Claude's rate limit. Surfaces a timing estimate so you can plan breaks.
  </Accordion>

  <Accordion title="self-verify">
    Runs a post-edit verification pass on changed files, checking for drift between what Claude said it would do and what it actually wrote.
  </Accordion>

  <Accordion title="preuse-logger">
    Logs every tool call — tool name, inputs, and timing — to a local file for cost analysis and debugging after the session.
  </Accordion>

  <Accordion title="auto-notify">
    Sends a notification when significant events occur during a session, such as a deploy completing or a long-running test suite finishing.
  </Accordion>

  <Accordion title="status-reporter">
    Generates progress updates during long-running sessions so you can see what Claude has done without scrolling through the full transcript.
  </Accordion>
</AccordionGroup>

### Context hooks (PreCompact)

<AccordionGroup>
  <Accordion title="pre-compact">
    Saves session state — current working directory, git branch, modified files list, and active tasks — immediately before context compaction. After compaction, Claude resumes with the right context rather than starting blind.
  </Accordion>
</AccordionGroup>

### Session end hooks (Stop)

<AccordionGroup>
  <Accordion title="session-coach">
    Fires periodic coaching nudges at session end: skill suggestions based on what you built, workflow tips, and checkpoint reminders. Toggleable — set `CC_COACH_DISABLE=1` to turn it off.
  </Accordion>

  <Accordion title="status-checkin">
    Renders a status summary at session end — what was built, files modified, cost incurred, and time elapsed.
  </Accordion>

  <Accordion title="session-end-verify">
    Runs an end-of-session checklist: verifies modified files, checks for leftover `console.log` statements, and flags uncommitted changes.
  </Accordion>
</AccordionGroup>

### Additional hooks

<AccordionGroup>
  <Accordion title="context-rot-monitor">
    Monitors context window fill level with tiered warnings at 60%, 75%, 85%, and 90%. Disable with `CC_CONTEXT_ROT_DISABLE=1`.
  </Accordion>

  <Accordion title="vendor-update-notify">
    Alerts you when any of CCC's 19 vendor packages have published updates, so your tool set stays current.
  </Accordion>

  <Accordion title="claude-md-staleness">
    Checks whether your `CLAUDE.md` is out of date compared to the latest CCC template and nudges you to refresh it.
  </Accordion>

  <Accordion title="openclaw-adapter">
    Forwards tool use events to the OpenClaw gateway for multi-agent coordination when OpenClaw is detected.
  </Accordion>

  <Accordion title="openclaw-sync">
    Syncs session state bidirectionally with the OpenClaw platform after edits, writes, and bash operations.
  </Accordion>

  <Accordion title="daily-improvement-scan">
    Scans the CCC ecosystem for new techniques and improvements, feeds findings into the continuous improvement pipeline.
  </Accordion>

  <Accordion title="linear-auto-track">
    Automatically tracks progress against Linear issues when a Linear integration is configured.
  </Accordion>

  <Accordion title="linear-phase-gate">
    Enforces phase gates on Linear issues — blocks advancement until defined criteria are met.
  </Accordion>

  <Accordion title="linear-pr-link">
    Links pull requests back to their originating Linear issues automatically after `git push`.
  </Accordion>
</AccordionGroup>

## Hook configuration structure

Hooks are registered in your `settings.json` as entries under their lifecycle event. Here is what the structure looks like (key fields only):

```json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/careful-guard.js" }],
        "description": "Block destructive commands"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/context-guard.js" }],
        "description": "Track context usage — warns at ~70%"
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/auto-checkpoint.js" }],
        "description": "Auto git-stash checkpoint every 10 file edits"
      }
    ],
    "PreCompact": [
      {
        "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/pre-compact.js" }],
        "description": "Save session state before compaction"
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "node ~/.claude/hooks/session-coach.js" }],
        "description": "Periodic coaching nudges"
      }
    ]
  }
}
```

The `matcher` field controls which tools trigger the hook. `"*"` fires on every tool call; `"Bash"` fires only on shell commands; `"Edit|Write"` fires on file writes.

## Two hook configurations

CCC ships two ready-to-use hook configurations:

| File                    | Use when                                                                                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hooks.json`            | You have [Everything Claude Code (ECC)](https://github.com/affaan-m/everything-claude-code) installed — includes 34 hooks (15 kit-native + 19 ECC-inherited) |
| `hooks-standalone.json` | You do not have ECC — includes the 15 kit-native hooks only                                                                                                  |

The installer selects the right file automatically based on whether it detects ECC in your environment.

## Environment variable controls

| Variable                   | Effect                                                               |
| -------------------------- | -------------------------------------------------------------------- |
| `CC_COACH_DISABLE=1`       | Disable the `session-coach` nudges entirely                          |
| `CC_COACH_INTERVAL`        | Set the coaching nudge interval (number of responses between nudges) |
| `CC_NO_COLOR=1`            | Strip all color output from hook messages                            |
| `CC_NO_ANIMATION=1`        | Disable animation effects in hook output                             |
| `CC_CONTEXT_ROT_DISABLE=1` | Disable the context-rot-monitor tiered warnings                      |

## Writing your own hook

Hooks receive session data as JSON on stdin and must write JSON to stdout. A `PreToolUse` hook can block the tool call by exiting with code `2`.

```javascript theme={null}
let data = '';
process.stdin.on('data', chunk => data += chunk);
process.stdin.on('end', () => {
  const input = JSON.parse(data);
  // your logic here
  console.log(data); // pass through unchanged
});
```

To activate a custom hook, add it to the appropriate lifecycle event in `~/.claude/settings.json` using the same structure shown above.

<Warning>
  The `careful-guard` hook is a best-effort safety net, not a security boundary. Its regex-based blocking can be bypassed. Always combine it with a `settings.json` deny list and OS-level file permissions for production environments.
</Warning>