github-code/claude-howto
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add blog post and new slash commands for development workflow

Browse Source 
- Add blog post: 4 Essential Slash Commands I Use in Every Project
- Add new slash commands: /doc-refactor, /setup-ci-cd, /unit-test-expand
- Update slash-commands README with comprehensive documentation
- Simplify /push-all command structure
- Archive add-blog-post-slash-commands change
- Add blog-post spec and pending openspec changes
This commit is contained in:
Luong NGUYEN
2025-12-26 11:02:19 +01:00
parent 8ef1e4a0c0
commit 0fcac18357
21 changed files with 1557 additions and 397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

163
openspec/changes/add-context-tracking-hooks/design.md Normal file
View File

@@ -0,0 +1,163 @@
# Design: Context Usage Tracking via Hook Pairs
## Context
Users need visibility into token consumption during Claude Code sessions. While Claude Code provides internal context management, users lack tools to:
- Track token usage per request
- Monitor cumulative context growth
- Understand when they're approaching context limits
The existing `Stop` hook example provides cumulative usage but not per-request deltas.
## Goals / Non-Goals
### Goals
- Document a reliable method to track per-request token consumption
- Provide a working example users can copy and modify
- Explain the methodology and its limitations clearly
- Use existing hook events (`UserPromptSubmit`, `Stop`) without requiring new capabilities
### Non-Goals
- Implement actual token counting (we use character-based estimation)
- Access internal Claude Code context metrics
- Modify Claude Code's behavior or internal state
- Track system prompt tokens (not in transcript)
## Decisions
### Decision 1: Use UserPromptSubmit + Stop Hook Pair
**What**: Use `UserPromptSubmit` as the "pre-message" hook and `Stop` as the "post-response" hook.
**Why**: These are the natural lifecycle points:
- `UserPromptSubmit` fires before the prompt is sent to the model
- `Stop` fires after Claude completes its response
**Alternatives Considered**:
| Option | Pros | Cons |
|--------|------|------|
| SessionStart + Stop | Captures full session | No per-request granularity |
| PreToolUse + PostToolUse | Captures tool overhead | Missing prompt/response tokens |
| UserPromptSubmit + Stop | Natural request boundaries | Requires temp file for state |
### Decision 2: Use Temp File for State Persistence
**What**: Store pre-message token count in a temp file keyed by session ID.
**Why**: Hooks are stateless processes; we need persistence between the two hook invocations.
**Implementation**:
```python
import tempfile
import os
def get_state_file(session_id: str) -> str:
return os.path.join(tempfile.gettempdir(), f"claude-tokens-{session_id}.json")
```
### Decision 3: Single Script with Mode Detection
**What**: One Python script handles both hooks, detecting mode via `hook_event_name`.
**Why**:
- Reduces file count and complexity
- Ensures consistent token calculation logic
- Easier for users to understand and modify
**Structure**:
```python
def main():
data = json.load(sys.stdin)
event = data.get("hook_event_name")
if event == "UserPromptSubmit":
record_pre_message_count(data)
elif event == "Stop":
report_delta(data)
```
### Decision 4: Two Offline Token Counting Methods (No API Key)
**What**: Provide two offline methods - tiktoken-based and simple character estimation.
**Why**:
- No API key should be required for context tracking hooks
- Anthropic hasn't released an official offline tokenizer
- Users have different dependency tolerance levels
#### Method A: tiktoken with p50k_base (Recommended)
```python
import tiktoken
def count_tokens_tiktoken(text: str) -> int:
enc = tiktoken.get_encoding("p50k_base")
return len(enc.encode(text))
```
**Characteristics**:
- ~90-95% accuracy compared to Claude's actual tokenizer
- Works completely offline
- Requires `tiktoken` dependency
- Fast execution (<10ms)
#### Method B: Character-Based Estimation (Zero Dependencies)
```python
def count_tokens_estimate(text: str) -> int:
return len(text) // 4
```
**Characteristics**:
- ~80-90% accuracy for English text
- No dependencies at all
- Sub-millisecond latency
- Less accurate for code and non-English text
**Trade-off Matrix**:
| Factor | tiktoken | Estimation |
|--------|----------|------------|
| Accuracy | ~90-95% | ~80-90% |
| Speed | <10ms | <1ms |
| Dependencies | tiktoken | None |
| Offline | Yes | Yes |
**Note**: Anthropic hasn't released their official tokenizer publicly. The `tiktoken` approach uses OpenAI's tokenizer with `p50k_base` encoding as a reasonable approximation since both use BPE (byte-pair encoding).
## Token Delta Calculation Flow
```
UserPromptSubmit Stop
| |
v v
Read transcript Read transcript
| |
v v
Count characters Count characters
| |
v v
Estimate tokens (T1) Estimate tokens (T2)
| |
v v
Save T1 to temp file Calculate delta = T2 - T1
|
v
Report: "Request used ~X tokens"
```
## Risks / Trade-offs
| Risk | Mitigation |
|------|------------|
| Temp file not found (hook failures) | Graceful fallback to cumulative-only reporting |
| Inaccurate token estimates | Clear documentation of limitations |
| Race conditions (concurrent sessions) | Session ID in filename for isolation |
| Temp file cleanup | Use system temp directory (auto-cleaned) |
## Example Output Format
```
Context Usage: ~12,500 tokens used (~125,000 remaining)
This request: ~850 tokens (+6.8% of total)
```
## Open Questions
None - design is straightforward given existing hook capabilities.

100
openspec/changes/add-context-tracking-hooks/proposal.md Normal file
View File

@@ -0,0 +1,100 @@
# Change: Add Context Usage Tracking Documentation via Pre-Message and Post-Response Hooks
## Why
Users want to monitor token consumption per request and overall context usage throughout a Claude Code session. Currently, the hooks documentation shows a basic context-usage example using the Stop hook, but it doesn't demonstrate how to track **per-request** token consumption by comparing measurements at two points in time.
By documenting how to use `UserPromptSubmit` as a "pre-message" hook and `Stop` as a "post-response" hook, users can calculate the delta in token usage for each request, enabling accurate per-request consumption metrics.
## What Changes
- **ADDED**: Documentation for using `UserPromptSubmit` and `Stop` hooks together for context tracking
- **ADDED**: A new example demonstrating token delta calculation between pre-message and post-response
- **MODIFIED**: Enhance the existing context usage reporting requirement with delta-based tracking approach
- **ADDED**: Detailed explanation of token estimation methodology and its limitations
## Impact
- Affected specs: `hooks-documentation`
- Affected code: `06-hooks/README.md` (documentation updates)
- No breaking changes - purely additive documentation
## Technical Analysis
### Current Hook Events Mapping
| Desired Hook | Claude Code Event | Trigger Point |
|--------------|-------------------|---------------|
| Pre-Message Hook | `UserPromptSubmit` | Before user prompt is processed by the model |
| Post-Response Hook | `Stop` | After model completes its full response |
### Token Counting Methods (Offline, No API Key)
Since we need offline token counting without an API key, we offer **two local approaches**:
#### Method 1: tiktoken with p50k_base (More Accurate)
Use OpenAI's `tiktoken` library with the `p50k_base` encoding as an approximation for Claude's tokenizer:
```python
import tiktoken
enc = tiktoken.get_encoding("p50k_base")
tokens = enc.encode(text)
token_count = len(tokens)
```
**Pros:**
- More accurate than character estimation (~90-95% accuracy)
- Works completely offline
- No API key required
- Fast execution
**Cons:**
- Requires `tiktoken` dependency (`pip install tiktoken`)
- Not Claude's exact tokenizer (approximation)
#### Method 2: Character-Based Estimation (Simplest)
For zero-dependency estimation:
```python
estimated_tokens = len(text) // 4
```
**Pros:**
- No dependencies at all
- Works offline
- Extremely fast
**Cons:**
- Less accurate (~80-90% for English text)
- Varies more with code and non-English text
### Token Delta Calculation Approach
1. **Pre-Message (UserPromptSubmit)**: Read transcript, count tokens (via tiktoken or estimation)
2. **Post-Response (Stop)**: Read transcript again, calculate new total, compute delta
**Accuracy Evaluation:**
| Factor | tiktoken Method | Character Estimation |
|--------|-----------------|---------------------|
| Token accuracy | ~90-95% | ~80-90% |
| Dependencies | tiktoken | None |
| Speed | Fast (<10ms) | Very fast (<1ms) |
| Offline | Yes | Yes |
### Limitations
- **No official offline Claude tokenizer exists** - Anthropic hasn't released their tokenizer publicly
- System prompts and internal Claude Code context are NOT in the transcript
- The delta includes: user prompt + Claude's response + any tool outputs
- Both methods are approximations; actual API token counts may differ slightly
## Open Questions
1. Should we persist the pre-message count to a file, or can we rely on the hook's transient state?
- **Recommendation**: Use a simple temp file in the session directory for reliability
2. Should the example be a single Python script handling both hooks, or two separate scripts?
- **Recommendation**: Single script with mode detection based on `hook_event_name`

106
openspec/changes/add-context-tracking-hooks/specs/hooks-documentation/spec.md Normal file
View File

@@ -0,0 +1,106 @@
# hooks-documentation Spec Delta
## ADDED Requirements
### Requirement: Pre-Message and Post-Response Hook Pairs Documentation
The hooks lesson SHALL document how to use `UserPromptSubmit` and `Stop` hooks together for context/token usage tracking.
#### Scenario: Understanding hook event timing for context tracking
- **WHEN** a user wants to track per-request token consumption
- **THEN** they find documentation explaining that `UserPromptSubmit` fires before the prompt is processed (pre-message)
- **AND** they find documentation explaining that `Stop` fires after Claude completes its response (post-response)
- **AND** they understand how to calculate the delta between these two points
#### Scenario: Token delta calculation methodology
- **WHEN** a user implements a context tracking hook pair
- **THEN** they find documentation explaining how to:
- Record token count at `UserPromptSubmit` time
- Calculate new token count at `Stop` time
- Compute the delta representing per-request consumption
### Requirement: Context Tracking Hook Pair Example
The hooks lesson SHALL provide a working example script that tracks context usage using pre-message and post-response hooks.
#### Scenario: Single script handles both hook events
- **WHEN** a user copies the context-tracker.py example
- **THEN** the script detects the hook event type via `hook_event_name`
- **AND** handles `UserPromptSubmit` by saving current token estimate to a temp file
- **AND** handles `Stop` by loading the saved count, calculating delta, and reporting usage
#### Scenario: Complete configuration for hook pair
- **WHEN** a user wants to configure both hooks
- **THEN** they find a complete settings.json example showing:
- `UserPromptSubmit` hook configuration pointing to the context tracker script
- `Stop` hook configuration pointing to the same script
- Both hooks using the same script for consistent token calculation
#### Scenario: Per-request usage reporting
- **WHEN** the context tracking hooks execute
- **THEN** the Stop hook outputs a report showing:
- Total estimated tokens used in session
- Tokens consumed by the current request (delta)
- Remaining capacity estimate
### Requirement: Token Counting Methods Documentation
The hooks lesson SHALL document two offline token counting methods that require no API key.
#### Scenario: tiktoken-based token counting documented
- **WHEN** a user wants more accurate offline token counts
- **THEN** they find documentation for using `tiktoken` with `p50k_base` encoding
- **AND** they see a Python example using `tiktoken.get_encoding("p50k_base")`
- **AND** they understand it provides ~90-95% accuracy compared to Claude's tokenizer
- **AND** they learn it requires the `tiktoken` dependency
#### Scenario: Character estimation token counting documented
- **WHEN** a user wants zero-dependency token estimation
- **THEN** they find documentation for the ~4 characters per token estimation ratio
- **AND** they understand this provides ~80-90% accuracy for English text
- **AND** they learn it works with no external dependencies
#### Scenario: Method comparison provided
- **WHEN** a user needs to choose between token counting methods
- **THEN** they find a comparison showing:
- tiktoken method: ~90-95% accuracy, requires tiktoken, <10ms latency
- Estimation method: ~80-90% accuracy, no dependencies, <1ms latency
- **AND** both methods work completely offline without API keys
#### Scenario: Transcript contents explained
- **WHEN** a user wants to understand what's included in token counts
- **THEN** they find documentation explaining that the transcript includes:
- User prompts
- Claude's responses
- Tool inputs and outputs
- **AND** they understand that system prompts and internal context are NOT included
#### Scenario: No official Claude tokenizer caveat
- **WHEN** a user reads about token counting accuracy
- **THEN** they understand that Anthropic hasn't released an official offline tokenizer
- **AND** they understand both methods are approximations based on similar BPE tokenizers
## MODIFIED Requirements
### Requirement: Context Usage Reporting Hook Example
The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.
#### Scenario: Token calculation is correct
- **WHEN** a user copies the context-usage.py example
- **AND** runs it as a Stop hook
- **THEN** the hook correctly calculates estimated tokens from total character count
- **AND** displays a non-zero token count proportional to conversation length
#### Scenario: User learns to create context monitoring hook
- **WHEN** a user reads the context usage reporter example
- **THEN** they find a complete Python script that reads the transcript file
- **AND** they understand how to estimate token usage from conversation history
- **AND** they see the configuration for Stop hooks
- **AND** they understand the limitations of token estimation
#### Scenario: Hook output format is documented
- **WHEN** a user implements the context usage hook
- **THEN** they can generate a one-line report showing used tokens and remaining capacity
- **AND** the output shows realistic token counts based on conversation size
#### Scenario: Delta-based tracking is documented
- **WHEN** a user wants per-request token consumption
- **THEN** they find documentation pointing to the pre-message/post-response hook pair approach
- **AND** they understand how to use `UserPromptSubmit` + `Stop` for delta calculation

36
openspec/changes/add-context-tracking-hooks/tasks.md Normal file
View File

@@ -0,0 +1,36 @@
# Tasks: Add Context Usage Tracking Documentation
## 1. Documentation Updates
- [x] 1.1 Add "Context Tracking Hook Pairs" section to README explaining pre-message/post-response concept
- [x] 1.2 Document how UserPromptSubmit serves as pre-message hook
- [x] 1.3 Document how Stop serves as post-response hook
- [x] 1.4 Explain token delta calculation methodology
## 2. Example Scripts
- [x] 2.1 Create `context-tracker.py` example script with character estimation (zero dependencies)
- [x] 2.2 Create `context-tracker-tiktoken.py` example script with tiktoken method (more accurate)
- [x] 2.3 Implement UserPromptSubmit handler (save pre-message count)
- [x] 2.4 Implement Stop handler (calculate and report delta)
- [x] 2.5 Add clear inline comments explaining both approaches
## 3. Configuration Examples
- [x] 3.1 Add hook configuration example for UserPromptSubmit event
- [x] 3.2 Add hook configuration example for Stop event
- [x] 3.3 Provide combined configuration showing both hooks together
## 4. Token Counting Methods Documentation
- [x] 4.1 Document tiktoken with p50k_base method (more accurate, ~90-95%)
- [x] 4.2 Document character-based estimation method (simple, ~80-90%)
- [x] 4.3 Create comparison table of both offline methods
- [x] 4.4 Explain what's included/excluded from transcript
- [x] 4.5 Add caveat that no official Claude offline tokenizer exists
## 5. Validation
- [x] 5.1 Test example script with sample JSON input
- [x] 5.2 Verify configuration examples have valid JSON syntax
- [x] 5.3 Run openspec validate to confirm proposal is complete