feat(tui): add profile view toggle to Hourly tab

[christian-taillon]

Summary

Adds a profile view toggle to the Hourly tab in Tokscale TUI, allowing users to switch between a detailed table view and an aggregated profile view showing usage patterns by time-of-day and day-of-week. Also includes several enhancements to the hourly report feature.

Changes

Core Feature: Profile View Toggle

• Add HourlyViewMode enum (Table/Profile) with 'v' key to toggle views
• Profile view displays:
  • Time-of-day breakdown (Morning/Daytime/Evening/Night)
  • Weekday breakdown (Mon-Sun)
  • Peak hour insight with tokens and cost
  • Visual bar charts scaled to terminal width

Profile View Enhancements

• Dynamic bar widths that fill available horizontal space (20-80 chars)
• Responsive layout adapts to terminal width
• Period definitions:
  • Morning: 05:00-11:59
  • Daytime: 12:00-16:59
  • Evening: 17:00-21:59
  • Night: 22:00-04:59

Additional Hourly Report Improvements

• Add Turn and Message count columns to hourly/daily views
• Add Cost/1M column to models report table
• Add cache hit ratio display with Cache× notation
• Fix client/model sorting determinism
• Add --kilo flag support for KiLo client

Testing

• All 367 tests pass
• Tested manually on various terminal widths
• Profile view correctly shows usage patterns
• Toggle between views works smoothly with 'v' key

How to Use

1. Navigate to the Hourly tab in TUI
2. Press 'v' to toggle between Table and Profile views
3. Profile view shows aggregated usage patterns
4. Press 'v' again to return to table view

---

Summary by cubic

Adds a profile view toggle to the TUI Hourly tab so you can switch between the table and an aggregated profile of usage by time-of-day and weekday. Also ships hour-level reporting across core, CLI, and TUI, plus cache efficiency and turn/message insights.

• New Features

  • TUI Hourly: press 'v' to switch Table/Profile; profile shows time-of-day, weekday, and peak hour with bars that scale to terminal width.
  • Hourly report end-to-end: core hour buckets, CLI hourly subcommand with filters/JSON and a Source column, and a new TUI tab.
  • Cache efficiency: show "Cache×" = cache_read / (input + cache_write) in hourly, daily, and models tables.
  • Engagement metrics: add Turn and Msgs columns; detect turn boundaries from Claude Code logs.
  • Overview chart: press 'h' to toggle between daily and hourly granularity.
  • Models table: add Cost/1M for quick efficiency comparison.

• Bug Fixes

  • Deterministic ordering for hourly clients and models.
  • Keep sort selection on the Hourly tab; only reset when switching tabs.
  • Rename "Cache%" to "Cache×" to reflect a multiplier, not a percentage.
  • CLI: add missing flags to hourly (--kilo, --crush, --home); make --light a no-op; fix report options.
  • Back-compat for cached messages: add serde default for is_turn_start.
  • Correct profile summary label to show hours (not days).

^{Written for commit 2802c9c. Summary will update on new commits.}

[vercel]

@christian-taillon is attempting to deploy a commit to the Inevitable Team on Vercel.

A member of the Team first needs to authorize it.

[cubic-dev-ai]

5 issues found across 18 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/tokscale-core/src/sessions/mod.rs">

<violation number="1" location="crates/tokscale-core/src/sessions/mod.rs:39">
P2: Adding a required field to `UnifiedMessage` breaks deserialization of previously cached data (bincode-serialized `CachedSourceStore` includes `Vec<UnifiedMessage>`). Without a default or schema bump, older cache files become unreadable after this change.</violation>
</file>

<file name="crates/tokscale-cli/src/tui/ui/hourly_profile.rs">

<violation number="1" location="crates/tokscale-cli/src/tui/ui/hourly_profile.rs:77">
P2: `hourly.len()` counts hourly buckets, but the UI labels it as days. This will overstate the day count (e.g., 48 hours shown as 48 days). Consider using unique date count or change the label to hours.</violation>
</file>

<file name="crates/tokscale-cli/src/tui/cache.rs">

<violation number="1" location="crates/tokscale-cli/src/tui/cache.rs:57">
P2: Cache schema was expanded but schema version was not bumped, allowing old cache files to be treated as fresh and suppressing reload of new hourly/count fields.</violation>
</file>

<file name="crates/tokscale-cli/src/tui/app.rs">

<violation number="1" location="crates/tokscale-cli/src/tui/app.rs:418">
P2: apply_tab_sort_defaults sets Date sorting only for the Hourly tab and never resets cost sorting when leaving it. Because the function runs on every tab switch, visiting Hourly leaves `sort_field` as Date for Models/Agents/Daily, which changes those tabs’ ordering away from the intended cost sort (the comment says “other tabs keep cost sort”).</violation>
</file>

<file name="crates/tokscale-cli/src/main.rs">

<violation number="1" location="crates/tokscale-cli/src/main.rs:2083">
P2: The new Hourly subcommand defines `--light` and passes `json || light` into `run_hourly_report`, but the function ignores `_light_or_json` and the handler always runs the CLI report. This makes `--light` ineffective and prevents `tokscale hourly` from falling back to the TUI tab when available.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Cache schema was expanded but schema version was not bumped, allowing old cache files to be treated as fresh and suppressing reload of new hourly/count fields.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/tokscale-cli/src/tui/cache.rs, line 57:

<comment>Cache schema was expanded but schema version was not bumped, allowing old cache files to be treated as fresh and suppressing reload of new hourly/count fields.</comment>

<file context>
@@ -53,6 +53,8 @@ struct CachedUsageData {
     agents: Vec<CachedAgentUsage>,
     daily: Vec<CachedDailyUsage>,
+    #[serde(default)]
+    hourly: Vec<CachedHourlyUsage>,
     graph: Option<CachedGraphData>,
     total_tokens: u64,
</file context>

[christian-taillon]

Dependency Note

This PR builds on top of #359 (feat: add hourly usage report). That PR should be merged first.

I've tested #359 extensively and experienced no bugs - any issues I reported earlier were false positives. The hourly tab foundation is solid and ready to merge.

---

Testing Summary for #359:

• ✅ Hourly tab displays correctly
• ✅ Data loads and aggregates properly
• ✅ Sorting and navigation work as expected
• ✅ Cache persistence works across sessions
• ✅ No crashes or memory issues observed

[christian-taillon]

Review Outcome Summary (cubic findings)

All findings from @cubic have been assessed and addressed:

Fixed

• Cache compatibility: Added #[serde(default)] to is_turn_start field in UnifiedMessage for backward-compatible deserialization (crates/tokscale-core/src/sessions/mod.rs)
• Hourly profile label: Corrected summary label from "days" to "hours" (crates/tokscale-cli/src/tui/ui/hourly_profile.rs)
• Hourly CLI cleanup: Removed unused _light_or_json parameter and clarified --light as a no-op; also fixed pre-existing bugs: added missing crush flag and use_env_roots: true to Hourly command (crates/tokscale-cli/src/main.rs)

False Positive

• TUI JSON cache schema-version: The JSON cache uses #[serde(default)] for newly added fields, making schema evolution backward-compatible without explicit version handling.

Already Fixed

• Hourly sort persistence: Already addressed in commit c4d8ef0; no regression found.

Validation

cargo test -p tokscale-core && cargo test -p tokscale-cli

Result: 470 passed (core), 74 passed (cli)

All changes are minimal and scoped to the reported findings.

[cubic-dev-ai]

Review Outcome Summary (cubic findings)

All findings from @cubic have been assessed and addressed:

Fixed

...

@christian-taillon The fixes for cache compatibility, labels, and the CLI signature look solid and address the concerns accurately.

Regarding the TUI JSON cache versioning: I suggested versioning because #[serde(default)] only protects you during field additions. If you eventually rename a field or change a type, serde will simply silently fill the new field with a default (like 0 or false) while ignoring the old key, which can lead to confusing "empty" states in the UI until the user manually refreshes. However, for adding hourly data and the is_turn_start flag, your current approach is perfectly fine for this scope.

On sort persistence: I see the logic in apply_tab_sort_defaults now. By moving the sort reset into the tab-switching handlers and out of reset_selection, you've ensured that the user's chosen sort (e.g., sorting the Hourly tab by Cost) persists even as they scroll or interact. I likely missed that this was already being addressed in the same batch of changes.

One small detail in crates/tokscale-cli/src/main.rs: adding the missing --crush flag and setting use_env_roots: true brings the hourly command into parity with the daily and models reports, which is great for consistency.

These updates effectively resolve the issues I flagged.

For more details on how I handle memory and learnings, you can check out the Cubic documentation on learnings.

[cubic-dev-ai]

1 issue found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/tokscale-cli/src/main.rs">

<violation number="1" location="crates/tokscale-cli/src/main.rs:2359">
P1: Hourly report ignores `--home` because report options are hardcoded to `home_dir: None` and env roots.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[christian-taillon]

Good catch! The --home flag was indeed being ignored in the Hourly report. The fix has been applied in commit 2802c9c to match how Monthly handles the --home flag - accepting home_dir as a parameter, computing use_env_roots from it, and passing both to ReportOptions.

[christian-taillon]

Maintainers, I want to be clear, I built off #395 which I think is a good feature.

Happy to do a round or two of rebasing for other PRs - I do reccomend @crhan's PR be merged. Happy to do another round of conflict resolution - I do intend to use this feature long term so please let me know if you'd like changes pre-merge.