/smartzone hooks

Install

Install just this, from a clone of the repo. It is copied, not wired: the installer prints the settings.json snippet to add.

./scripts/install-skills.sh --skill smartzone   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill smartzone   # Windows PowerShell

What it does

UserPromptSubmit hook. Prints a one-line warning into the conversation when the live context passes ~75k tokens, so both you and Claude see it and can wrap up: /divide the rest, then /session-handoff (or, for an orchestrator, the rotation step in meta-orchestrator, see ROTATION.md). Heuristic only; /context is the precise check.

How to invoke

mkdir -p .claude/hooks
cp <skills repo>/hooks/smartzone.py .claude/hooks/

.claude/settings.json (merge into an existing hooks block if there is one):

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/smartzone.py\" || exit 0"
          }
        ]
      }
    ]
  }
}

Claude Code asks you to approve the hook once per repo.

Install at user level (covers sessions started in your home directory too).

• In a home-dir session $CLAUDE_PROJECT_DIR is ~, so a per-repo .claude/hooks/ copy is never loaded there.
• Copy the script to ~/.claude/hooks/ and register it in ~/.claude/settings.json with an absolute path:

mkdir -p ~/.claude/hooks
cp <skills repo>/hooks/smartzone.py ~/.claude/hooks/

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"/home/you/.claude/hooks/smartzone.py\" || exit 0"
          }
        ]
      }
    ]
  }
}

Use your real absolute path (on Windows e.g. C:/Users/you/.claude/hooks/smartzone.py).

Self-test (fixtures in temp dirs, no network):

python hooks/smartzone.py --self-test

How it works

On every prompt you submit, Claude Code passes the hook JSON on stdin; the script reads transcript_path and only the tail of that file (never the whole transcript).

• It takes the last main-chain assistant entry (not a sidechain) with message.usage and sums input_tokens + cache_creation_input_tokens + cache_read_input_tokens.
• /compact appends a compact_boundary line and never truncates the file, so usage from before the last boundary is ignored.
• If there is no usage after it (or at all), it falls back to the bytes after the last boundary (whole file if none) at ~20 bytes per token.
• If the result is at least the threshold it prints the warning (stdout is injected into the conversation).
• Below it, or on any error (missing file, malformed lines, bad env), it prints nothing and never blocks.

Threshold: env var SMARTZONE_TOKENS (integer tokens), default 75000 (the same as the hook's earlier 1.5 MB transcript-size check, at ~20 bytes per token).

• A bad value falls back to the default.
• Set it in the hook command or your shell env.

Example

[smart-zone] Session transcript context is ~82k tokens, past the 75k warning threshold; quality tends to drop around 100-120k (a heuristic, verify with /context). Wrap up: run /divide on the remaining work, then /session-handoff, and continue in a fresh session.

Related

divide, session-handoff, meta-orchestrator (rotates early on this warning).

Sample workflows

• Wrap up a long session
  smartzone → divide → you → session-handoff → you
  Install just this one: ./scripts/install-skills.sh --workflow wrap-up-long-session or .\scripts\install-skills.ps1 -Workflow wrap-up-long-session

Source

• hooks/smartzone.py
• hooks/README.md#smartzonepy--your-context-has-left-the-smart-zone-warning