Hide usage meter by default + stop spurious context alerts (#442)

* feat: hide usage meter by default

* fix: only alert on context threshold crossings

---------

Co-authored-by: Eric <eric@EricsMacStudio.lan>

Author: outsourc-e

src/components/usage-meter/usage-meter-session.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import {
+  resolveContextAlertThreshold,
+  resolveUsageMeterSessionKey,
+  shouldShowUsageMeterContextAlert,
+} from './usage-meter-session'
+
+describe('usage meter session targeting', () => {
+  it('uses the active chat session from the route pathname', () => {
+    expect(resolveUsageMeterSessionKey('/chat/main')).toBe('main')
+    expect(resolveUsageMeterSessionKey('/chat/new')).toBe('new')
+    expect(resolveUsageMeterSessionKey('/chat/session-123')).toBe('session-123')
+  })
+
+  it('decodes route params for chat sessions', () => {
+    expect(resolveUsageMeterSessionKey('/chat/local%2Fmirror')).toBe('local/mirror')
+  })
+
+  it('falls back to main outside chat routes', () => {
+    expect(resolveUsageMeterSessionKey('/settings')).toBe('main')
+    expect(resolveUsageMeterSessionKey('/dashboard')).toBe('main')
+  })
+
+  it('only allows context alerts when the usage meter is visible on chat routes', () => {
+    expect(
+      shouldShowUsageMeterContextAlert({ pathname: '/chat/main', visible: true }),
+    ).toBe(true)
+    expect(
+      shouldShowUsageMeterContextAlert({ pathname: '/chat/main', visible: false }),
+    ).toBe(false)
+    expect(
+      shouldShowUsageMeterContextAlert({ pathname: '/settings', visible: true }),
+    ).toBe(false)
+  })
+
+  it('does not alert on the first high reading without crossing a threshold', () => {
+    expect(
+      resolveContextAlertThreshold({
+        previous: null,
+        current: 85,
+        thresholds: [50, 75, 90],
+        sent: {},
+      }),
+    ).toBeNull()
+  })
+
+  it('alerts with the highest newly crossed threshold', () => {
+    expect(
+      resolveContextAlertThreshold({
+        previous: 40,
+        current: 85,
+        thresholds: [50, 75, 90],
+        sent: {},
+      }),
+    ).toBe(75)
+  })
+
+  it('skips thresholds already sent today', () => {
+    expect(
+      resolveContextAlertThreshold({
+        previous: 70,
+        current: 92,
+        thresholds: [50, 75, 90],
+        sent: { 75: true },
+      }),
+    ).toBe(90)
+  })
+})

src/components/usage-meter/usage-meter-session.ts

@@ -0,0 +1,42 @@
+export function resolveUsageMeterSessionKey(pathname: string): string {
+  if (!pathname.startsWith('/chat/')) return 'main'
+  const raw = pathname.slice('/chat/'.length).split('/')[0] || 'main'
+  try {
+    return decodeURIComponent(raw) || 'main'
+  } catch {
+    return raw || 'main'
+  }
+}
+
+export function shouldShowUsageMeterContextAlert({
+  pathname,
+  visible,
+}: {
+  pathname: string
+  visible: boolean
+}): boolean {
+  return visible && pathname.startsWith('/chat/')
+}
+
+export function resolveContextAlertThreshold({
+  previous,
+  current,
+  thresholds,
+  sent,
+}: {
+  previous: number | null
+  current: number
+  thresholds: Array<number>
+  sent: Record<number, boolean>
+}): number | null {
+  if (!Number.isFinite(current)) return null
+  if (previous === null || !Number.isFinite(previous)) return null
+  if (current <= previous) return null
+
+  const crossed = thresholds.filter(
+    (threshold) => previous < threshold && current >= threshold && !sent[threshold],
+  )
+
+  if (crossed.length === 0) return null
+  return crossed[crossed.length - 1] ?? null
+}

src/components/usage-meter/usage-meter.tsx

@@ -1,8 +1,14 @@
 'use client'
 
+import { useRouterState } from '@tanstack/react-router'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { UsageDetailsModal } from './usage-details-modal'
 import { ContextAlertModal } from './context-alert-modal'
+import {
+  resolveContextAlertThreshold,
+  resolveUsageMeterSessionKey,
+  shouldShowUsageMeterContextAlert,
+} from './usage-meter-session'
 import { DialogContent, DialogRoot } from '@/components/ui/dialog'
 import {
   MenuContent,
@@ -434,7 +440,16 @@ type AgentActivity = {
   totalAgentCost: number
 }
 
-export function UsageMeter() {
+export function UsageMeter({ visible = true }: { visible?: boolean }) {
+  const pathname = useRouterState({ select: (state) => state.location.pathname })
+  const statusSessionKey = useMemo(
+    () => resolveUsageMeterSessionKey(pathname),
+    [pathname],
+  )
+  const contextAlertsEnabled = useMemo(
+    () => shouldShowUsageMeterContextAlert({ pathname, visible }),
+    [pathname, visible],
+  )
   const [usage, setUsage] = useState<UsageSummary>(() =>
     parseSessionStatus(null),
   )
@@ -458,10 +473,14 @@ export function UsageMeter() {
     threshold: number
   }>({ open: false, threshold: 0 })
   const alertStateRef = useRef(getAlertState())
+  const previousContextPercentRef = useRef<number | null>(null)
 
   const refresh = useCallback(async () => {
     try {
-      const res = await fetch('/api/session-status')
+      const query = statusSessionKey
+        ? `?sessionKey=${encodeURIComponent(statusSessionKey)}`
+        : ''
+      const res = await fetch(`/api/session-status${query}`)
       if (!res.ok) {
         const data = await res.json().catch(() => null)
         throw new Error(
@@ -478,7 +497,7 @@ export function UsageMeter() {
       setError(errorMessage)
       toast('Failed to fetch usage data', { type: 'error' })
     }
-  }, [])
+  }, [statusSessionKey])
 
   const refreshProviders = useCallback(async () => {
     try {
@@ -546,28 +565,43 @@ export function UsageMeter() {
   }, [refreshAgentActivity])
 
   useEffect(() => {
+    if (!contextAlertsEnabled && contextAlert.open) {
+      setContextAlert({ open: false, threshold: 0 })
+    }
+  }, [contextAlert.open, contextAlertsEnabled])
+
+  useEffect(() => {
+    if (!contextAlertsEnabled) {
+      previousContextPercentRef.current = usage.contextPercent
+      return
+    }
     if (typeof window === 'undefined') return
     const current = usage.contextPercent
     if (!Number.isFinite(current)) return
+    const previous = previousContextPercentRef.current
+    previousContextPercentRef.current = current
     const state = alertStateRef.current
     if (state.date !== getTodayKey()) {
       state.date = getTodayKey()
       state.sent = {}
     }
-    const eligible = THRESHOLDS.filter((threshold) => current >= threshold)
-    if (eligible.length === 0) return
-    for (const threshold of eligible) {
-      if (state.sent[threshold]) continue
-      state.sent[threshold] = true
-      saveAlertState(state)
-      // Show in-app modal instead of browser notification
-      setContextAlert({ open: true, threshold })
-      break // Only show one alert at a time
-    }
-  }, [usage.contextPercent])
+    const threshold = resolveContextAlertThreshold({
+      previous,
+      current,
+      thresholds: THRESHOLDS,
+      sent: state.sent,
+    })
+    if (!threshold) return
+    state.sent[threshold] = true
+    saveAlertState(state)
+    // Show in-app modal instead of browser notification
+    setContextAlert({ open: true, threshold })
+  }, [contextAlertsEnabled, usage.contextPercent])
 
   useEffect(() => {
     function handleOpenUsageFromSearch() {
+      void refresh()
+      void refreshProviders()
       setOpen(true)
     }
 
@@ -581,7 +615,7 @@ export function UsageMeter() {
         handleOpenUsageFromSearch,
       )
     }
-  }, [])
+  }, [refresh, refreshProviders])
 
   // Find the preferred provider for the status bar display
   const [preferredProvider, setPreferredProvider] = useState<string | null>(
@@ -839,39 +873,41 @@ export function UsageMeter() {
 
   return (
     <>
-      <MenuRoot>
-        <MenuTrigger
-          className={cn(
-            "absolute bottom-2 right-2",
-            'ml-auto rounded-full border px-3 py-1 text-xs font-medium',
-            'flex items-center gap-3 transition hover:bg-primary-100 cursor-pointer',
-            alertTone,
-          )}
-          data-tour="usage-meter"
-        >
-          <span className="text-[9px] uppercase tracking-widest text-primary-500 opacity-75">
-            {STATS_VIEW_LABELS[statsView].split(' ')[0]}
-          </span>
-          <span className="text-primary-300">|</span>
-          {renderPillContent()}
-        </MenuTrigger>
-        <MenuContent align="end" className="min-w-[180px]">
-          {(['session', 'provider', 'cost', 'agents'] as const).map((view) => (
-            <MenuItem
-              key={view}
-              onClick={() => handleStatsViewChange(view)}
-              className={cn(
-                statsView === view && 'bg-amber-100 text-amber-800',
-              )}
-            >
-              <span className="flex-1">{STATS_VIEW_LABELS[view]}</span>
-              {statsView === view && <span className="text-amber-600">✓</span>}
-            </MenuItem>
-          ))}
-          <div className="my-1 h-px bg-primary-100" />
-          <MenuItem onClick={() => setOpen(true)}>View Details…</MenuItem>
-        </MenuContent>
-      </MenuRoot>
+      {visible ? (
+        <MenuRoot>
+          <MenuTrigger
+            className={cn(
+              "absolute bottom-2 right-2",
+              'ml-auto rounded-full border px-3 py-1 text-xs font-medium',
+              'flex items-center gap-3 transition hover:bg-primary-100 cursor-pointer',
+              alertTone,
+            )}
+            data-tour="usage-meter"
+          >
+            <span className="text-[9px] uppercase tracking-widest text-primary-500 opacity-75">
+              {STATS_VIEW_LABELS[statsView].split(' ')[0]}
+            </span>
+            <span className="text-primary-300">|</span>
+            {renderPillContent()}
+          </MenuTrigger>
+          <MenuContent align="end" className="min-w-[180px]">
+            {(['session', 'provider', 'cost', 'agents'] as const).map((view) => (
+              <MenuItem
+                key={view}
+                onClick={() => handleStatsViewChange(view)}
+                className={cn(
+                  statsView === view && 'bg-amber-100 text-amber-800',
+                )}
+              >
+                <span className="flex-1">{STATS_VIEW_LABELS[view]}</span>
+                {statsView === view && <span className="text-amber-600">✓</span>}
+              </MenuItem>
+            ))}
+            <div className="my-1 h-px bg-primary-100" />
+            <MenuItem onClick={() => setOpen(true)}>View Details…</MenuItem>
+          </MenuContent>
+        </MenuRoot>
+      ) : null}
 
       <DialogRoot open={open} onOpenChange={setOpen}>
         <DialogContent className="w-[min(720px,94vw)]">

src/hooks/use-settings.ts

@@ -11,6 +11,7 @@ export type StudioSettings = {
   claudeToken: string
   theme: SettingsThemeMode
   accentColor: AccentColor
+  showUsageMeter: boolean
   editorFontSize: number
   editorWordWrap: boolean
   editorMinimap: boolean
@@ -35,6 +36,7 @@ export const defaultStudioSettings: StudioSettings = {
   claudeToken: '',
   theme: 'system',
   accentColor: 'blue',
+  showUsageMeter: false,
   editorFontSize: 13,
   editorWordWrap: true,
   editorMinimap: false,

src/routes/__root.tsx

@@ -18,7 +18,7 @@ import { Toaster } from '@/components/ui/toast'
 import { OnboardingTour } from '@/components/onboarding/onboarding-tour'
 import { KeyboardShortcutsModal } from '@/components/keyboard-shortcuts-modal'
 import { UpdateCenterNotifier } from '@/components/update-center-notifier'
-import { initializeSettingsAppearance } from '@/hooks/use-settings'
+import { initializeSettingsAppearance, useSettings } from '@/hooks/use-settings'
 import { useApplyChatWidth } from '@/hooks/use-chat-settings'
 import {
   ClaudeOnboarding,
@@ -251,6 +251,7 @@ export async function registerAppServiceWorker({
 }
 
 function RootLayout() {
+  const { settings } = useSettings()
   const pathname = useRouterState({ select: (state) => state.location.pathname })
   const isHermesWorldLandingRoute =
     pathname === '/hermes-world' ||
@@ -369,10 +370,8 @@ function RootLayout() {
             </ErrorBoundary>
           </WorkspaceShell>
           {!isHermesWorldLandingRoute ? <SearchModal /> : null}
-          {/* UsageMeter must be mounted at root so the OPEN_USAGE event from
-              the search modal's Usage tile has a listener. See #258.
-              But public launch surfaces like HermesWorld should not show app usage chrome. */}
-          {!isGameSurfaceRoute ? <UsageMeter /> : null}
+          {/* Keep UsageMeter mounted so search-modal OPEN_USAGE still works even when the pill is hidden by default. */}
+          {!isGameSurfaceRoute ? <UsageMeter visible={settings.showUsageMeter} /> : null}
           {!isHermesWorldLandingRoute ? <KeyboardShortcutsModal /> : null}
           {!isHermesWorldLandingRoute ? <UpdateCenterNotifier /> : null}
           {rootSurfaceState.showPostOnboardingOverlays && !isGameSurfaceRoute ? (

src/routes/settings/index.tsx

@@ -875,6 +875,18 @@ function ChatDisplaySection() {
             aria-label="Expand sidebar on hover"
           />
         </SettingsRow>
+        <SettingsRow
+          label="Show usage meter"
+          description="Show the floating usage/provider pill in chat. Off by default to keep the composer clean."
+        >
+          <Switch
+            checked={settings.showUsageMeter}
+            onCheckedChange={(checked) =>
+              updateSettings({ showUsageMeter: checked })
+            }
+            aria-label="Show usage meter"
+          />
+        </SettingsRow>
       </SettingsSection>
       {/* Mobile Navigation removed — not relevant for Hermes Workspace */}
     </>