feat(ccusage): support context_window field from Claude Code statusline hook (#749)

ryoppippi · web-flow · commit 7515103bb506 · 2025-12-11T21:23:13.000Z
* feat(ccusage): support context_window field from Claude Code statusline hook

Claude Code now provides context_window data in its statusline hook JSON,
containing total_input_tokens, total_output_tokens, and context_window_size.

This change:
- Adds context_window field to statuslineHookJsonSchema in _types.ts
- Updates statusline command to prefer context_window data when available
- Falls back to existing transcript-based calculation when not provided
- Refactors context info formatting into reusable helper function
- Uses Result type pattern for consistent functional error handling

The context_window data from Claude Code is more accurate than parsing
the transcript file, as it reflects the actual token counts used by the API.

* docs: add context_window reference to statusline guide

Add note about Claude Code's context_window data being used for accurate
token counts, with link to official documentation.

* chore(ccusage): fix typo colour to color
diff --git a/apps/ccusage/src/_types.ts b/apps/ccusage/src/_types.ts
@@ -173,6 +173,11 @@ export const statuslineHookJsonSchema = v.object({
 		total_lines_added: v.optional(v.number()),
 		total_lines_removed: v.optional(v.number()),
 	})),
+	context_window: v.optional(v.object({
+		total_input_tokens: v.number(),
+		total_output_tokens: v.optional(v.number()),
+		context_window_size: v.number(),
+	})),
 });
 
 /**
diff --git a/apps/ccusage/src/commands/statusline.ts b/apps/ccusage/src/commands/statusline.ts
@@ -430,28 +430,40 @@ export const statuslineCommand = define({
 						Result.unwrap({ blockInfo: 'No active block', burnRateInfo: '' }),
 					);
 
-					// Calculate context tokens from transcript with model-specific limits
-					const contextInfo = await Result.pipe(
-						Result.try({
-							try: calculateContextTokens(hookData.transcript_path, hookData.model.id, mergedOptions.offline),
-							catch: error => error,
-						}),
+					// Helper function to format context info with color coding
+					const formatContextInfo = (inputTokens: number, contextLimit: number): string => {
+						const percentage = Math.round((inputTokens / contextLimit) * 100);
+						const color = percentage < ctx.values.contextLowThreshold
+							? pc.green
+							: percentage < ctx.values.contextMediumThreshold
+								? pc.yellow
+								: pc.red;
+						const coloredPercentage = color(`${percentage}%`);
+						const tokenDisplay = inputTokens.toLocaleString();
+						return `${tokenDisplay} (${coloredPercentage})`;
+					};
+
+					// Get context tokens from Claude Code hook data, or fall back to calculating from transcript
+					const contextDataResult = hookData.context_window != null
+						// Prefer context_window data from Claude Code hook if available
+						? Result.succeed({
+								inputTokens: hookData.context_window.total_input_tokens,
+								contextLimit: hookData.context_window.context_window_size,
+							})
+						// Fall back to calculating context tokens from transcript
+						: await Result.try({
+								try: async () => calculateContextTokens(hookData.transcript_path, hookData.model.id, mergedOptions.offline),
+								catch: error => error,
+							})();
+
+					const contextInfo = Result.pipe(
+						contextDataResult,
 						Result.inspectError(error => logger.debug(`Failed to calculate context tokens: ${error instanceof Error ? error.message : String(error)}`)),
 						Result.map((contextResult) => {
 							if (contextResult == null) {
 								return undefined;
 							}
-							// Format context percentage with color coding using option thresholds
-							const color = contextResult.percentage < ctx.values.contextLowThreshold
-								? pc.green
-								: contextResult.percentage < ctx.values.contextMediumThreshold
-									? pc.yellow
-									: pc.red;
-							const coloredPercentage = color(`${contextResult.percentage}%`);
-
-							// Format token count with thousand separators
-							const tokenDisplay = contextResult.inputTokens.toLocaleString();
-							return `${tokenDisplay} (${coloredPercentage})`;
+							return formatContextInfo(contextResult.inputTokens, contextResult.contextLimit);
 						}),
 						Result.unwrap(undefined),
 					);
diff --git a/apps/ccusage/test/statusline-test-opus4.json b/apps/ccusage/test/statusline-test-opus4.json
@@ -21,5 +21,10 @@
 		"total_lines_added": 0,
 		"total_lines_removed": 0
 	},
+	"context_window": {
+		"total_input_tokens": 85000,
+		"total_output_tokens": 5000,
+		"context_window_size": 200000
+	},
 	"exceeds_200k_tokens": false
 }
diff --git a/apps/ccusage/test/statusline-test-sonnet4.json b/apps/ccusage/test/statusline-test-sonnet4.json
@@ -21,5 +21,10 @@
 		"total_lines_added": 0,
 		"total_lines_removed": 0
 	},
+	"context_window": {
+		"total_input_tokens": 35000,
+		"total_output_tokens": 2500,
+		"context_window_size": 200000
+	},
 	"exceeds_200k_tokens": false
 }
diff --git a/apps/ccusage/test/statusline-test-sonnet41.json b/apps/ccusage/test/statusline-test-sonnet41.json
@@ -21,5 +21,10 @@
 		"total_lines_added": 0,
 		"total_lines_removed": 0
 	},
+	"context_window": {
+		"total_input_tokens": 52000,
+		"total_output_tokens": 3800,
+		"context_window_size": 200000
+	},
 	"exceeds_200k_tokens": false
 }
diff --git a/apps/ccusage/test/statusline-test.json b/apps/ccusage/test/statusline-test.json
@@ -21,5 +21,10 @@
 		"total_lines_added": 0,
 		"total_lines_removed": 0
 	},
+	"context_window": {
+		"total_input_tokens": 42500,
+		"total_output_tokens": 3200,
+		"context_window_size": 200000
+	},
 	"exceeds_200k_tokens": false
 }
diff --git a/docs/guide/statusline.md b/docs/guide/statusline.md
@@ -105,6 +105,7 @@ When using `--cost-source both`, the session cost shows both Claude Code and ccu
   - Green text: Low usage (< 50% by default)
   - Yellow text: Medium usage (50-80% by default)
   - Red text: High usage (> 80% by default)
+  - Uses Claude Code's [`context_window` data](https://code.claude.com/docs/en/statusline) when available for accurate token counts
 
 When no active block exists:
 
