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

* 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

Author: ryoppippi

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(),
+})),
 });
 
 /**

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),
 );

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
 }

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
 }

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
 }

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
 }

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: