fix(statusline): respect timezone for today cost (#1121)

Add a statusline timezone option so the compact today total uses the same date grouping semantics as daily reports instead of forcing UTC.

The statusline today loader now builds its since/until filter from the requested IANA timezone and passes that timezone through to entry loading, keeping the filtered entry dates aligned with the selected local day.

Update CLI help, config schema coverage, and snapshots for the new option. Fixes #1114.

Author: ryoppippi

apps/ccusage/config-schema.json

@@ -973,6 +973,11 @@
 											"minimum": 0.0,
 											"type": "integer"
 										},
+										"timezone": {
+											"description": "Timezone for date grouping (IANA).",
+											"markdownDescription": "Timezone for date grouping (IANA).",
+											"type": "string"
+										},
 										"visualBurnRate": {
 											"default": "off",
 											"description": "Visual burn-rate display mode.",
@@ -2667,6 +2672,11 @@
 									"minimum": 0.0,
 									"type": "integer"
 								},
+								"timezone": {
+									"description": "Timezone for date grouping (IANA).",
+									"markdownDescription": "Timezone for date grouping (IANA).",
+									"type": "string"
+								},
 								"visualBurnRate": {
 									"default": "off",
 									"description": "Visual burn-rate display mode.",

rust/crates/ccusage/src/cli-help.json

@@ -367,6 +367,10 @@
 			"description": "Context usage percentage below which status is shown in yellow (0-100)",
 			"default": "80"
 		},
+		{
+			"flags": "-z, --timezone <timezone>",
+			"description": "Timezone for date grouping (IANA)"
+		},
 		{
 			"flags": "--config <config>",
 			"description": "Path to configuration file",

rust/crates/ccusage/src/cli.rs

@@ -110,6 +110,7 @@ pub(crate) struct StatuslineArgs {
     pub(crate) refresh_interval: u64,
     pub(crate) context_low_threshold: u8,
     pub(crate) context_medium_threshold: u8,
+    pub(crate) timezone: Option<String>,
     pub(crate) config: Option<PathBuf>,
     pub(crate) debug: bool,
 }
@@ -164,6 +165,7 @@ impl Default for StatuslineArgs {
             refresh_interval: 1,
             context_low_threshold: 50,
             context_medium_threshold: 80,
+            timezone: None,
             config: None,
             debug: false,
         }
@@ -357,6 +359,7 @@ fn parse_command(
                                 "Invalid value for --context-medium-threshold".to_string()
                             })?
                     }
+                    "-z" | "--timezone" => args.timezone = Some(parser.value_for("--timezone")?),
                     "--config" => args.config = Some(PathBuf::from(parser.value_for("--config")?)),
                     "--debug" => args.debug = true,
                     flag => return Err(format!("Unknown statusline option '{flag}'")),
@@ -2358,6 +2361,8 @@ mod tests {
             "ccusage",
             "statusline",
             "--no-cache",
+            "--timezone",
+            "Asia/Tokyo",
             "--visual-burn-rate",
             "emoji-text",
             "--cost-source",
@@ -2368,6 +2373,7 @@ mod tests {
         };
         assert!(args.offline);
         assert!(args.no_cache);
+        assert_eq!(args.timezone.as_deref(), Some("Asia/Tokyo"));
         assert_eq!(args.visual_burn_rate, VisualBurnRate::EmojiText);
         assert_eq!(args.cost_source, CostSource::Both);
     }

rust/crates/ccusage/src/commands/mod.rs

@@ -18,14 +18,13 @@ use crate::{
     },
     color,
     fast::FxHashMap,
-    filter_and_sort_summaries, filter_blocks_by_date, format_compact_utc_date, format_currency,
-    format_number, format_remaining_time, format_rfc3339_millis, group_project_output,
-    identify_session_blocks, load_daily_summaries, load_entries, print_active_block_detail,
-    print_blocks_table, print_json_or_jq, print_usage_table, session_summary_json, sort_blocks,
-    sort_summaries, summarize_by_key, summarize_summaries_by_bucket, summary_json,
-    total_usage_tokens, totals_json, utc_now, wants_json, BucketKind, Color, Context, Result,
-    SessionAccumulator, TimestampMs, DEFAULT_RECENT_DAYS, DEFAULT_SESSION_DURATION_HOURS,
-    MILLIS_PER_DAY, MILLIS_PER_MINUTE,
+    filter_and_sort_summaries, filter_blocks_by_date, format_currency, format_date, format_number,
+    format_remaining_time, format_rfc3339_millis, group_project_output, identify_session_blocks,
+    load_daily_summaries, load_entries, print_active_block_detail, print_blocks_table,
+    print_json_or_jq, print_usage_table, session_summary_json, sort_blocks, sort_summaries,
+    summarize_by_key, summarize_summaries_by_bucket, summary_json, total_usage_tokens, totals_json,
+    utc_now, wants_json, BucketKind, Color, Context, Result, SessionAccumulator, TimestampMs,
+    DEFAULT_RECENT_DAYS, DEFAULT_SESSION_DURATION_HOURS, MILLIS_PER_DAY, MILLIS_PER_MINUTE,
 };
 
 pub(crate) fn run_daily(args: DailyArgs) -> Result<()> {
@@ -412,13 +411,7 @@ fn render_statusline(
         None
     };
 
-    let today = format_compact_utc_date(utc_now());
-    let today_shared = SharedArgs {
-        since: Some(today.clone()),
-        until: Some(today),
-        offline: shared.offline,
-        ..SharedArgs::default()
-    };
+    let today_shared = statusline_today_shared(args, shared, utc_now());
     let today_cost = load_entries(&today_shared, None)
         .map(|entries| {
             entries
@@ -516,6 +509,21 @@ fn render_statusline(
     ))
 }
 
+fn statusline_today_shared(
+    args: &StatuslineArgs,
+    shared: &SharedArgs,
+    now: TimestampMs,
+) -> SharedArgs {
+    let today = format_date(now, args.timezone.as_deref()).replace('-', "");
+    SharedArgs {
+        since: Some(today.clone()),
+        until: Some(today),
+        offline: shared.offline,
+        timezone: args.timezone.clone(),
+        ..SharedArgs::default()
+    }
+}
+
 fn calculate_session_cost(session_id: &str, shared: &SharedArgs) -> Result<f64> {
     Ok(load_entries(shared, None)?
         .into_iter()
@@ -846,6 +854,25 @@ mod tests {
         assert!(format_statusline_context(120_000, 200_000, &args, &shared).contains("60%"));
     }
 
+    #[test]
+    fn builds_statusline_today_filter_from_timezone() {
+        let args = StatuslineArgs {
+            timezone: Some("Asia/Tokyo".to_string()),
+            ..StatuslineArgs::default()
+        };
+        let shared = SharedArgs {
+            offline: true,
+            ..SharedArgs::default()
+        };
+        let now = TimestampMs::from_millis(1_779_380_820_000);
+
+        let today_shared = statusline_today_shared(&args, &shared, now);
+
+        assert_eq!(today_shared.since.as_deref(), Some("20260522"));
+        assert_eq!(today_shared.until.as_deref(), Some("20260522"));
+        assert_eq!(today_shared.timezone.as_deref(), Some("Asia/Tokyo"));
+    }
+
     #[test]
     fn reuses_statusline_cache_while_fresh_and_transcript_unchanged() {
         let cache = StatuslineCache {

rust/crates/ccusage/src/config.rs

@@ -341,6 +341,9 @@ pub(crate) fn apply_config_to_statusline_args(args: &mut StatuslineArgs, config:
         {
             args.context_medium_threshold = threshold;
         }
+        if let Some(timezone) = options.timezone {
+            args.timezone = Some(timezone);
+        }
         if let Some(debug) = options.debug {
             args.debug = debug;
         }
@@ -570,6 +573,7 @@ mod tests {
                         "refreshInterval": 3,
                         "contextLowThreshold": 45,
                         "contextMediumThreshold": 75,
+                        "timezone": "Asia/Tokyo",
                         "debug": true
                     }
                 }
@@ -605,6 +609,7 @@ mod tests {
                         "refreshInterval": 3,
                         "contextLowThreshold": 45,
                         "contextMediumThreshold": 75,
+                        "timezone": "Asia/Tokyo",
                         "debug": true
                     }
                 }
@@ -625,6 +630,7 @@ mod tests {
         assert_eq!(statusline.refresh_interval, 3);
         assert_eq!(statusline.context_low_threshold, 45);
         assert_eq!(statusline.context_medium_threshold, 75);
+        assert_eq!(statusline.timezone.as_deref(), Some("Asia/Tokyo"));
         assert!(statusline.debug);
     }
 

rust/crates/ccusage/src/config_schema.rs

@@ -428,6 +428,8 @@ pub(crate) struct StatuslineSpecificOptions {
     pub(crate) context_low_threshold: Option<u64>,
     /// Percentage threshold for medium context warning.
     pub(crate) context_medium_threshold: Option<u64>,
+    /// Timezone for date grouping (IANA).
+    pub(crate) timezone: Option<String>,
     /// Show statusline debug information.
     pub(crate) debug: Option<bool>,
 }
@@ -577,6 +579,7 @@ impl StatuslineSpecificOptions {
             refresh_interval: u64_option(map, "refreshInterval"),
             context_low_threshold: u64_option(map, "contextLowThreshold"),
             context_medium_threshold: u64_option(map, "contextMediumThreshold"),
+            timezone: string_option(map, "timezone"),
             debug: bool_option(map, "debug"),
         }
     }
@@ -970,6 +973,7 @@ mod tests {
                 "noOffline",
                 "offline",
                 "refreshInterval",
+                "timezone",
                 "visualBurnRate",
             ],
         );

rust/crates/ccusage/src/date_utils.rs

@@ -242,11 +242,6 @@ pub(crate) fn format_utc_date(timestamp: TimestampMs) -> String {
     format_date_parts(parts.year, parts.month, parts.day)
 }
 
-pub(crate) fn format_compact_utc_date(timestamp: TimestampMs) -> String {
-    let parts = timestamp.utc_parts();
-    format!("{:04}{:02}{:02}", parts.year, parts.month, parts.day)
-}
-
 pub(crate) fn format_naive_date(date: IsoDate) -> String {
     format_date_parts(date.year, date.month, date.day)
 }

rust/crates/ccusage/src/snapshots/ccusage__cli__tests__statusline_help.snap

@@ -1,5 +1,6 @@
 ---
 source: crates/ccusage/src/cli.rs
+assertion_line: 2062
 expression: "help_text_for_args(&[\"ccusage\".to_string(), \"statusline\".to_string()])"
 ---
 Display compact status line for Claude Code hooks with hybrid time+file caching (Beta)
@@ -17,6 +18,7 @@ OPTIONS:
   --refresh-interval [refresh-interval]                 Refresh interval in seconds for cache expiry (default: 1)
   --context-low-threshold [context-low-threshold]       Context usage percentage below which status is shown in green (0-100) (default: 50)
   --context-medium-threshold [context-medium-threshold] Context usage percentage below which status is shown in yellow (0-100) (default: 80)
+  -z, --timezone <timezone>                             Timezone for date grouping (IANA)
   --config <config>                                     Path to configuration file (default: auto-discovery)
   -d, --debug                                           Show pricing mismatch information for debugging (default: false)
   -h, --help                                            Display this help message

rust/crates/ccusage/src/snapshots/ccusage__config_schema__tests__snapshots_schema_agent_specific_option_edges.snap

@@ -1,5 +1,6 @@
 ---
 source: crates/ccusage/src/config_schema.rs
+assertion_line: 1257
 expression: "json!({\n    \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n    definition_properties(&schema, \"ccusage-config\"),\n    \"rootAdditionalProperties\":\n    schema[\"definitions\"][\"ccusage-config\"][\"additionalProperties\"],\n    \"defaults\": schema_node(&schema, &[\"defaults\"]), \"rootDaily\":\n    schema_node(&schema, &[\"commands\", \"daily\"]), \"claudeStatusline\":\n    schema_node(&schema, &[\"claude\", \"commands\", \"statusline\"]),\n    \"codexDefaults\": schema_node(&schema, &[\"codex\", \"defaults\"]),\n    \"opencodeWeekly\":\n    schema_node(&schema, &[\"opencode\", \"commands\", \"weekly\"]), \"piDefaults\":\n    schema_node(&schema, &[\"pi\", \"defaults\"]), \"openclawDefaults\":\n    schema_node(&schema, &[\"openclaw\", \"defaults\"]),\n})"
 ---
 {
@@ -72,6 +73,11 @@ expression: "json!({\n    \"rootRef\": schema[\"$ref\"], \"rootProperties\":\n
         "minimum": 0.0,
         "type": "integer"
       },
+      "timezone": {
+        "description": "Timezone for date grouping (IANA).",
+        "markdownDescription": "Timezone for date grouping (IANA).",
+        "type": "string"
+      },
       "visualBurnRate": {
         "default": "off",
         "description": "Visual burn-rate display mode.",