feat(web): show remaining usage limits in the sidebar footer

apps/web/src/components/settings/SettingsPanels.tsx

@@ -523,6 +523,9 @@ export function useSettingsRestore(onRestored?: () => void) {
       DEFAULT_UNIFIED_SETTINGS.sidebarProjectGroupingMode
         ? ["Project Grouping"]
         : []),
+      ...(settings.sidebarUsageLimitsEnabled !== DEFAULT_UNIFIED_SETTINGS.sidebarUsageLimitsEnabled
+        ? ["Usage limits in sidebar"]
+        : []),
       ...(settings.sidebarAutoSettleAfterDays !==
       DEFAULT_UNIFIED_SETTINGS.sidebarAutoSettleAfterDays
         ? ["Auto-settle inactive threads"]
@@ -628,6 +631,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.sidebarAutoSettleOnMerge,
       settings.sidebarProjectGroupingMode,
       settings.sidebarThreadPreviewCount,
+      settings.sidebarUsageLimitsEnabled,
       settings.showSkillsInSlashMenu,
       settings.timestampFormat,
       settings.wordWrap,
@@ -714,6 +718,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       panelAnimationDurationMs: DEFAULT_UNIFIED_SETTINGS.panelAnimationDurationMs,
       sidebarThreadPreviewCount: DEFAULT_UNIFIED_SETTINGS.sidebarThreadPreviewCount,
       sidebarProjectGroupingMode: DEFAULT_UNIFIED_SETTINGS.sidebarProjectGroupingMode,
+      sidebarUsageLimitsEnabled: DEFAULT_UNIFIED_SETTINGS.sidebarUsageLimitsEnabled,
       sidebarAutoSettleAfterDays: DEFAULT_UNIFIED_SETTINGS.sidebarAutoSettleAfterDays,
       sidebarAutoSettleOnMerge: DEFAULT_UNIFIED_SETTINGS.sidebarAutoSettleOnMerge,
       enableLegacyTokenStreaming: DEFAULT_UNIFIED_SETTINGS.enableLegacyTokenStreaming,
@@ -2111,6 +2116,19 @@ export function GeneralSettingsPanel() {
             />
           }
         />
+        <SettingsRow
+          {...searchableSetting("sidebar-usage-limits")}
+          description="Show each provider's remaining subscription quota above the sidebar footer. Select it to open Usage → Limits."
+          control={
+            <Switch
+              checked={settings.sidebarUsageLimitsEnabled}
+              onCheckedChange={(checked) =>
+                updateSettings({ sidebarUsageLimitsEnabled: Boolean(checked) })
+              }
+              aria-label="Usage limits in sidebar"
+            />
+          }
+        />
 
         {supportsAutoSettlement ? (
           <>

apps/web/src/components/settings/settingsSearch.ts

@@ -162,6 +162,12 @@ export const SETTINGS_SEARCH_ITEMS = [
     to: "/settings/general",
     searchTerms: ["combine matching repositories environments sidebar"],
   },
+  {
+    id: "sidebar-usage-limits",
+    title: "Usage limits in sidebar",
+    to: "/settings/general",
+    searchTerms: ["quota remaining rate limit codex claude footer subscription"],
+  },
   {
     id: "auto-settle-inactive-threads",
     title: "Auto-settle inactive threads",

apps/web/src/components/sidebar/SidebarChrome.tsx

@@ -33,6 +33,7 @@ import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { readPullRequestListPreferences } from "../pullRequest/pullRequestListPreferences";
 import { SidebarProviderUpdatePill } from "./SidebarProviderUpdatePill";
 import { SidebarUpdateArchitectureWarning, SidebarUpdatePill } from "./SidebarUpdatePill";
+import { SidebarUsageLimitsPill } from "./SidebarUsageLimitsPill";
 
 export const SidebarChromeHeader = memo(function SidebarChromeHeader({
   isElectron,
@@ -226,6 +227,7 @@ export const SidebarChromeFooter = memo(function SidebarChromeFooter() {
     <SidebarFooter className="p-[var(--sidebar-content-inset)]">
       <SidebarProviderUpdatePill />
       <SidebarUpdateArchitectureWarning />
+      <SidebarUsageLimitsPill />
       <SidebarUtilityMenu />
     </SidebarFooter>
   );

apps/web/src/components/sidebar/SidebarUsageLimits.logic.test.ts

@@ -0,0 +1,219 @@
+import {
+  EnvironmentId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { collectSidebarLimits, limitTone } from "./SidebarUsageLimits.logic";
+
+const now = Date.parse("2026-09-03T12:00:00.000Z");
+
+const session = {
+  id: "five_hour",
+  kind: "session",
+  label: "Session",
+  usedPercent: 40,
+  windowDurationMins: 300,
+  resetsAt: "2026-09-03T14:00:00.000Z",
+} as const;
+
+const weekly = {
+  id: "seven_day",
+  kind: "weekly",
+  label: "Weekly",
+  usedPercent: 85,
+  windowDurationMins: 10_080,
+  resetsAt: "2026-09-06T15:30:00.000Z",
+} as const;
+
+function provider(overrides: Partial<ServerProvider>): ServerProvider {
+  return {
+    instanceId: ProviderInstanceId.make("codex"),
+    driver: ProviderDriverKind.make("codex"),
+    enabled: true,
+    installed: true,
+    version: null,
+    status: "ready",
+    auth: { status: "authenticated" },
+    checkedAt: "2026-09-03T11:00:00.000Z",
+    models: [],
+    slashCommands: [],
+    skills: [],
+    ...overrides,
+  };
+}
+
+function presentations(
+  ...environments: ReadonlyArray<readonly [label: string, providers: readonly ServerProvider[]]>
+) {
+  return new Map(
+    environments.map(([label, providers], index) => [
+      EnvironmentId.make(`env-${index + 1}`),
+      { entry: { target: { label } }, serverConfig: { providers } },
+    ]),
+  );
+}
+
+describe("limitTone", () => {
+  it("steps from neutral to low to critical as the quota drains", () => {
+    expect(limitTone(100)).toBe("ok");
+    expect(limitTone(26)).toBe("ok");
+    expect(limitTone(25)).toBe("low");
+    expect(limitTone(11)).toBe("low");
+    expect(limitTone(10)).toBe("critical");
+    expect(limitTone(0)).toBe("critical");
+  });
+});
+
+describe("collectSidebarLimits", () => {
+  it("shows the tightest window per provider and keeps every window for the details", () => {
+    const [codex] = collectSidebarLimits(
+      presentations([
+        "Laptop",
+        [
+          provider({
+            usageLimits: { checkedAt: "2026-09-03T11:00:00.000Z", windows: [session, weekly] },
+          }),
+        ],
+      ]),
+      now,
+    );
+    expect(codex).toMatchObject({
+      driver: "codex",
+      accountCount: 1,
+      remainingPercent: 15,
+      tone: "low",
+    });
+    expect(codex?.windows).toEqual([
+      {
+        id: "session:five_hour",
+        label: "Session",
+        remainingPercent: 60,
+        resetsAt: Date.parse(session.resetsAt),
+      },
+      {
+        id: "weekly:seven_day",
+        label: "Weekly",
+        remainingPercent: 15,
+        resetsAt: Date.parse(weekly.resetsAt),
+      },
+    ]);
+  });
+
+  it("pools accounts across environments and reports the soonest reset", () => {
+    const views = collectSidebarLimits(
+      presentations(
+        [
+          "Laptop",
+          [
+            provider({
+              auth: { status: "authenticated", email: "a@example.com" },
+              usageLimits: {
+                checkedAt: "2026-09-03T11:00:00.000Z",
+                windows: [{ ...session, usedPercent: 90, resetsAt: "2026-09-03T13:00:00.000Z" }],
+              },
+            }),
+          ],
+        ],
+        [
+          "Desktop",
+          [
+            provider({
+              auth: { status: "authenticated", email: "b@example.com" },
+              usageLimits: {
+                checkedAt: "2026-09-03T11:00:00.000Z",
+                windows: [{ ...session, usedPercent: 10 }],
+              },
+            }),
+          ],
+        ],
+      ),
+      now,
+    );
+    expect(views).toHaveLength(1);
+    expect(views[0]).toMatchObject({ accountCount: 2, remainingPercent: 50, tone: "ok" });
+    expect(views[0]?.windows[0]?.resetsAt).toBe(Date.parse("2026-09-03T13:00:00.000Z"));
+  });
+
+  it("orders providers by driver and leaves out ones with nothing usable", () => {
+    const views = collectSidebarLimits(
+      presentations([
+        "Laptop",
+        [
+          provider({
+            usageLimits: { checkedAt: "2026-09-03T11:00:00.000Z", windows: [session] },
+          }),
+          provider({
+            instanceId: ProviderInstanceId.make("claude"),
+            driver: ProviderDriverKind.make("claudeAgent"),
+            usageLimits: {
+              checkedAt: "2026-09-03T11:00:00.000Z",
+              windows: [{ ...weekly, usedPercent: 95 }],
+            },
+          }),
+          provider({
+            instanceId: ProviderInstanceId.make("claude-api"),
+            driver: ProviderDriverKind.make("claudeAgent"),
+            usageLimits: {
+              checkedAt: "2026-09-03T11:00:00.000Z",
+              windows: [],
+              unavailable: { reason: "unsupported" },
+            },
+          }),
+          provider({
+            instanceId: ProviderInstanceId.make("cursor"),
+            driver: ProviderDriverKind.make("cursor"),
+          }),
+        ],
+      ]),
+      now,
+    );
+    expect(views.map((view) => [view.driver, view.remainingPercent, view.tone])).toEqual([
+      ["claudeAgent", 5, "critical"],
+      ["codex", 60, "ok"],
+    ]);
+  });
+
+  it("keeps a session and a monthly window apart when the provider reuses their id", () => {
+    const [codex] = collectSidebarLimits(
+      presentations(
+        [
+          "Laptop",
+          [
+            provider({
+              auth: { status: "authenticated", email: "paid@example.com" },
+              usageLimits: {
+                checkedAt: "2026-09-03T11:00:00.000Z",
+                windows: [{ ...session, id: "primary", usedPercent: 30 }],
+              },
+            }),
+          ],
+        ],
+        [
+          "Desktop",
+          [
+            provider({
+              auth: { status: "authenticated", email: "free@example.com" },
+              usageLimits: {
+                checkedAt: "2026-09-03T11:00:00.000Z",
+                windows: [{ id: "primary", kind: "monthly", label: "Monthly", usedPercent: 70 }],
+              },
+            }),
+          ],
+        ],
+      ),
+      now,
+    );
+    expect(codex?.windows.map((window) => [window.id, window.remainingPercent])).toEqual([
+      ["session:primary", 70],
+      ["monthly:primary", 30],
+    ]);
+  });
+
+  it("is empty when no provider reports limits", () => {
+    expect(collectSidebarLimits(presentations(["Laptop", [provider({})]]), now)).toEqual([]);
+    expect(collectSidebarLimits(new Map(), now)).toEqual([]);
+  });
+});

apps/web/src/components/sidebar/SidebarUsageLimits.logic.ts

@@ -0,0 +1,67 @@
+import type { ServerProvider } from "@t3tools/contracts";
+import { collectLimitAccounts, collectLimitPools } from "@t3tools/shared/usageLimits";
+
+/** Neutral until a quarter is left, then warning, then destructive at a tenth. */
+export type SidebarLimitTone = "ok" | "low" | "critical";
+
+const LOW_REMAINING_PERCENT = 25;
+const CRITICAL_REMAINING_PERCENT = 10;
+
+export interface SidebarLimitWindow {
+  /** `kind:id`, since Codex reuses `primary` for a session window on one plan and a monthly one on another. */
+  readonly id: string;
+  readonly label: string;
+  readonly remainingPercent: number;
+  /** Soonest reset across the pooled accounts, epoch millis, or null when none reports one. */
+  readonly resetsAt: number | null;
+}
+
+export interface SidebarLimitView {
+  readonly driver: ServerProvider["driver"];
+  /** Distinct accounts pooled into these numbers. */
+  readonly accountCount: number;
+  /** Quota left in the tightest window, which is what decides whether the next turn runs. */
+  readonly remainingPercent: number;
+  readonly tone: SidebarLimitTone;
+  /** Every pooled window, ordered as Usage → Limits orders them. */
+  readonly windows: readonly SidebarLimitWindow[];
+}
+
+export function limitTone(remainingPercent: number): SidebarLimitTone {
+  if (remainingPercent <= CRITICAL_REMAINING_PERCENT) return "critical";
+  if (remainingPercent <= LOW_REMAINING_PERCENT) return "low";
+  return "ok";
+}
+
+/**
+ * One entry per provider with usable limits, pooled across accounts and
+ * environments exactly as Usage → Limits pools them, reduced to the number
+ * the sidebar has room for: the share left in the most constrained window.
+ * Providers sort by driver so the pill keeps a stable reading order across
+ * sessions. `now` only feeds the pace maths the pill does not show.
+ */
+export function collectSidebarLimits(
+  presentations: Parameters<typeof collectLimitAccounts>[0],
+  now: number,
+): readonly SidebarLimitView[] {
+  const pools = collectLimitPools(collectLimitAccounts(presentations), now);
+  return pools
+    .filter((pool) => pool.windows.length > 0)
+    .map((pool) => {
+      const windows = pool.windows.map((window) => ({
+        id: `${window.kind}:${window.id}`,
+        label: window.label,
+        remainingPercent: window.remainingPercent,
+        resetsAt: window.resets[0]?.at ?? null,
+      }));
+      const remainingPercent = Math.min(...windows.map((window) => window.remainingPercent));
+      return {
+        driver: pool.driver,
+        accountCount: pool.accounts.length,
+        remainingPercent,
+        tone: limitTone(remainingPercent),
+        windows,
+      };
+    })
+    .sort((left, right) => left.driver.localeCompare(right.driver));
+}