Files
claude-howto/openspec/changes/add-context-usage-hook-example/proposal.md
T
Luong NGUYEN 9c5c7c5049 docs: Add context usage reporter hook example
Add Example 6 showing how to create a hook that reports context/token
usage after each Claude response:

- Python script reads transcript_path to access conversation history
- Estimates tokens using ~4 chars/token heuristic
- Outputs one-line report: "Context: ~45k/200k tokens (77% remaining)"
- Documents both Stop and UserPromptSubmit hook configurations
- Explains limitations (estimate vs exact /context command)
2025-12-24 23:21:38 +01:00

889 B

Change: Add Context Usage Reporting Hook Example

Why

Users want to monitor their context window usage during Claude Code sessions. The hooks documentation currently lacks a practical example showing how to create a hook that reports context/token usage after each user request. This is valuable for understanding when context is getting full and when auto-compaction might occur.

What Changes

  • Add a detailed example hook that reports context usage after each user prompt
  • The hook will read the transcript file and estimate token usage
  • Include step-by-step explanation of how the hook works
  • Document the limitations (estimation vs exact token counts)

Impact

  • Affected specs: hooks-documentation (add new example)
  • Affected code: 06-hooks/README.md (add new example section)
  • User impact: Users gain a practical example for monitoring context usage