Claude Token Watchdog

Claude Token Watchdog Watches conversation length and fires a handoff before you hit the token limit.

---

Compatibility

This skill is built on the Claude SKILL.md format and works on the three Anthropic surfaces that support it.

| Platform | Supported | |---|---| | Claude.ai (web and desktop apps) | Yes | | Claude Cowork | Yes | | Claude Code (CLI) | Yes | | ChatGPT, Gemini, Copilot, or any non-Anthropic LLM | No - SKILL.md is Anthropic-specific | | LangChain, LiteLLM, or other orchestration frameworks | Not directly - the watchdog logic could be ported as a Python module, but that is a separate implementation |

The skill activates the same way on all three Anthropic surfaces: Claude reads the frontmatter, decides whether to load the full instructions based on the trigger phrases, and applies the threshold logic to the visible conversation. Output is identical across surfaces. Platform-specific behavior (described below) covers minor differences in how the continuation brief is consumed (paste into a new chat for web/Cowork, paste into a new Claude Code session for CLI).

---

What this does

A token-usage watchdog. Counts visible messages, applies threshold logic, and at the forced tier delegates to claude-session-handoff to produce a continuation brief. Prevents token burn and avoids hitting Claude's usage or context limits mid-task.

Role Monitor token-usage risk. Decide when to hand off. Delegate the actual handoff to claude-session-handoff.

Trigger Automatic at message thresholds 15 / 20 / 25 (dropped to ~12 in dense conversations). Manual via /watchdog-check.

Output Notification text at soft and strong tiers. Forced tier invokes claude-session-handoff and prints the brief that skill generates.

Side effects None. Print-only contract. No file writes, no commands, no repo edits.

---

Architecture

[User chats with Claude]
          |
          v
+---------------------------------+
|  claude-token-watchdog        |   Heads up: this conversation is getting long. If you want to continue this work in a fresh chat with full context, just say `/handoff` and I'll generate a continuation brief.

Do not invoke `claude-session-handoff`. Do not block the current task.

#### Strong tier (20+ messages)

Before responding to the user's next request, print:

> This conversation is getting long enough that token limits are a real risk. I recommend we generate a continuation brief before starting the next task. Want me to do that now? (Or say `continue` to keep going.)

Wait for user response. If they say `continue` or anything ignoring the offer, proceed with their request but stay alert. If they accept, invoke `claude-session-handoff`.

#### Forced tier (25+ messages)

Open with:

> This conversation is approaching a context/usage limit. Generating the continuation brief now before we continue.

Then invoke `claude-session-handoff` and print the brief that skill returns. After printing, ask the user to paste the brief into a new chat before continuing.

---

### Manual trigger

The user can invoke this skill at any time with `/watchdog-check`. Response format:

> Current estimated message count: [N].
> Tier: [soft / strong / forced / below threshold].
> [Tier-specific notification text from above.]

For natural-language handoff requests ("create handoff", "summarize for new chat", "move to new window"), defer to `claude-session-handoff` directly. This skill only owns `/watchdog-check`.

---

### Platform-Specific Behavior

#### Claude web / app

- Output is copy/paste only.
- At forced tier, claude-session-handoff produces a self-contained brief the user pastes into a new Claude chat.

#### Claude Cowork

- Preserve collaboration context: ownership, reviewers, unresolved questions.
- claude-session-handoff includes coworker comments visible in the conversation.

#### Claude Code

- claude-session-handoff includes repo path, files changed, commands run, tests run, errors seen, and next command or edit.
- Watchdog adds: "Inspect the repo before editing if current file state is uncertain."

---

### Quality Rules

- Do not over-trigger. Below threshold and not in dense mode means stay silent.
- Do not invoke `claude-session-handoff` at soft or strong tiers. Only at forced.
- Do not invent message counts. If unsure, use inference fallback.
- Do not block user requests at soft tier. Notify and continue.
- At strong tier, ask once. If the user says continue, do not ask again until forced tier.
- At forced tier, generate the brief before doing any new work. No exceptions.

---

### Failure Modes

| Failure | What to do |
|---|---|
| User refuses handoff at forced tier | Generate the brief anyway. Print it. Tell the user it's available if they change their mind. Then proceed with their request. |
| Conversation contains no project work, just casual chat | Stay silent at all tiers. Watchdog only fires when there's state worth preserving. |
| User invokes claude-session-handoff directly | Stay silent. Manual intent wins. |
| Exact message count is ambiguous | Use inference fallback. Err earlier. |
| claude-session-handoff is unavailable | Print a basic continuation message with goal, last action, and next task. Tell the user to install claude-session-handoff for full briefs. |

---

### Final Operational Instruction

Watch. Notify at soft. Recommend at strong. Delegate at forced. Never produce a brief yourself - that is `claude-session-handoff`'s job. Never write files. Never run commands. Never modify the repo.

---

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nicholashidalgo](https://github.com/nicholashidalgo)
- **Source:** [nicholashidalgo/claude-skillforge](https://github.com/nicholashidalgo/claude-skillforge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.