From c1ad1a0adb5c512d69051839d9d6475f8ef8a009 Mon Sep 17 00:00:00 2001
From: Mason <masonxhuang@proton.me>
Date: Fri, 11 Sep 2026 21:01:16 +0800
Subject: [PATCH 1/3] feat: add cost/tokens toggle to share rows and breakdown
 table

Provider share rows and the model/project breakdown were cost-only, so
unpriced usage always showed $0.00 and sorted last. Both now follow a
shared cost/tokens metric: share rows rank and render by the active
metric next to the chart, and the breakdown header gets the same
toggle. Unpriced rows keep the "Unknown"/"+" cost marker in both modes.

Refs MayankBansal12/bb-plugin-usage#48

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 README.md                               |   3 +-
 app.tsx                                 | 196 ++++++++++++++++--------
 components/usage-dashboard-skeleton.tsx |  26 ++--
 3 files changed, 152 insertions(+), 73 deletions(-)

diff --git a/README.md b/README.md
index 9aaa780..4dc4787 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,8 @@ Track coding-agent token usage and estimated API cost across every machine enrol
 
 - Collect usage from Codex, Claude Code, FX, Grok Agent, OpenCode, Pi, Prime Agent, and Antigravity.
 - Separate the coding agent from the underlying model provider.
-- Group charts and cost summaries by agent or model provider.
+- Group charts and usage shares by agent or model provider.
+- Switch the chart, provider shares, and breakdown between cost and tokens, so unpriced usage stays visible.
 - Break usage down by model, project, or day.
 - Filter by machine, agent, model provider, and the last 7, 30, or 90 days.
 - Show exact, alias-matched, agent-reported, and unknown pricing in the breakdown table.
diff --git a/app.tsx b/app.tsx
index d469fad..47dc5d3 100644
--- a/app.tsx
+++ b/app.tsx
@@ -18,7 +18,7 @@ import { clampPercent, formatLimitReset, formatLimitValue, type ProviderLimitWin
 import { formatLocalMoney, localCurrency, usdToLocalRate } from "@/lib/local-currency";
 
 type Range = 7 | 30 | 90;
-type ChartMode = "cost" | "tokens";
+type MetricMode = "cost" | "tokens";
 type BreakdownMode = "model" | "project" | "day";
 type DimensionMode = "agent" | "provider";
 
@@ -195,6 +195,16 @@ function CostValue({ value, className }: { value: number; className?: string })
   );
 }
 
+// A row whose priced cost is zero but has unpriced usage shows "Unknown"; a
+// partially priced row gets a "+" marker since its share understates usage.
+function PricedCost({ cost, unknown }: { cost: number; unknown?: boolean }) {
+  return (
+    <span title={unknown ? "Some usage has no recorded cost or known catalog rate; totals exclude that usage." : undefined}>
+      {unknown && cost === 0 ? "Unknown" : <><CostValue value={cost} />{unknown ? "+" : ""}</>}
+    </span>
+  );
+}
+
 function parseDay(day: string) {
   return new Date(`${day}T00:00:00Z`);
 }
@@ -370,7 +380,7 @@ function UsageChart({
   records: UsageRecord[];
   providers: Array<{ id: string; name: string }>;
   range: Range;
-  mode: ChartMode;
+  mode: MetricMode;
   groupBy: DimensionMode;
   compactView?: boolean;
 }) {
@@ -597,14 +607,17 @@ function UsageChart({
   );
 }
 
-function ProviderCostRow({
+function ProviderShareRow({
   item,
+  mode,
   total,
 }: {
-  item: { id: string; name: string; cost: number; tokens: number };
+  item: { id: string; name: string; cost: number; tokens: number; unknown?: boolean };
+  mode: MetricMode;
   total: number;
 }) {
-  const share = total > 0 ? (item.cost / total) * 100 : 0;
+  const value = mode === "cost" ? item.cost : item.tokens;
+  const share = total > 0 ? (value / total) * 100 : 0;
   return (
     <div className="min-w-0">
       <div className="flex items-center justify-between gap-4 text-sm">
@@ -612,19 +625,29 @@ function ProviderCostRow({
           <ProviderLogo id={item.id} name={item.name} size="md" />
           <span className="truncate">{item.name}</span>
         </span>
-        <span className="shrink-0 tabular-nums"><CostValue value={item.cost} /></span>
+        <span className="shrink-0 tabular-nums">
+          {mode === "cost"
+            ? <PricedCost cost={item.cost} unknown={item.unknown} />
+            : <>{compact(item.tokens)}<span className="font-normal text-muted-foreground"> tokens</span></>}
+        </span>
       </div>
       <div className="mt-2 h-1.5 overflow-hidden rounded-full bg-muted">
         <div
           className="h-full rounded-full transition-[width] duration-500 ease-out motion-reduce:transition-none"
           style={{
             width: `${share}%`,
-            minWidth: item.cost > 0 ? 3 : 0,
+            minWidth: value > 0 ? 3 : 0,
             backgroundColor: providerColor(item.id),
           }}
         />
       </div>
-      <div className="mt-2 text-xs text-muted-foreground">{percentage(item.cost, total)} of cost · {compact(item.tokens)} tokens</div>
+      <div className="mt-2 text-xs text-muted-foreground">
+        {mode === "cost"
+          ? <>{percentage(item.cost, total)} of cost · {compact(item.tokens)} tokens</>
+          : item.unknown && item.cost === 0
+            ? <>{percentage(item.tokens, total)} of tokens · <span title="Some usage has no recorded cost or known catalog rate; totals exclude that usage.">cost unknown</span></>
+            : <>{percentage(item.tokens, total)} of tokens · {money(item.cost)}{item.unknown ? "+" : ""}</>}
+      </div>
     </div>
   );
 }
@@ -648,16 +671,18 @@ function ChartLegend({ providers }: { providers: Array<{ id: string; name: strin
 
 const CARD_CLASSES = "rounded-xl border border-border/70 bg-muted/[0.08]";
 
-// A project row names its highest-cost agent and folds the rest into `+N`,
-// which lists them with their own cost on hover or focus.
+// A project row names its dominant agent by the active metric and folds the
+// rest into `+N`, which lists them with their own value on hover or focus.
 function AgentCell({
   agentId,
   agent,
   others,
+  mode,
 }: {
   agentId: string;
   agent: string;
-  others?: Array<{ id: string; name: string; cost: number }>;
+  others?: Array<{ id: string; name: string; cost: number; tokens: number }>;
+  mode: MetricMode;
 }) {
   return (
     <span className="inline-flex min-w-0 items-center gap-2 text-muted-foreground">
@@ -684,7 +709,7 @@ function AgentCell({
                       <ProviderLogo id={item.id} name={item.name} size="sm" />
                       <span className="truncate">{item.name}</span>
                     </span>
-                    <span className="shrink-0 tabular-nums">{money(item.cost)}</span>
+                    <span className="shrink-0 tabular-nums">{mode === "cost" ? money(item.cost) : `${compact(item.tokens)} tokens`}</span>
                   </div>
                 ))}
               </div>
@@ -943,7 +968,7 @@ function UsageDashboard() {
   const providerLimitsRequestId = useRef(0);
   const { range, machine, showUsageLimits } = useUsageToolbar();
   const [chartGroup, setChartGroup] = useState<DimensionMode>("agent");
-  const [chartMode, setChartMode] = useState<ChartMode>("tokens");
+  const [metricMode, setMetricMode] = useState<MetricMode>("tokens");
   const [breakdownMode, setBreakdownMode] = useState<BreakdownMode>("model");
   const [mobileSection, setMobileSection] = useState<"chart" | "breakdown">("chart");
   const [breakdownPage, setBreakdownPage] = useState(1);
@@ -1093,8 +1118,15 @@ function UsageDashboard() {
     cost: number; tokens: number; unknown?: boolean;
     // Only project rows fold several agents into one badge; the folded ones are
     // listed here so the `+N` suffix can name them on hover.
-    otherAgents?: Array<{ id: string; name: string; cost: number }>;
+    otherAgents?: Array<{ id: string; name: string; cost: number; tokens: number }>;
   };
+  // Rows rank by the active metric, falling back to the other one so a $0
+  // unpriced row still sorts by its token volume (and vice versa).
+  const byMetric = useCallback(
+    (a: { cost: number; tokens: number }, b: { cost: number; tokens: number }) =>
+      metricMode === "cost" ? b.cost - a.cost || b.tokens - a.tokens : b.tokens - a.tokens || b.cost - a.cost,
+    [metricMode],
+  );
   const modelBreakdown = useMemo(() => {
     const map = new Map<string, BreakdownRow>();
     for (const row of rows) {
@@ -1105,31 +1137,33 @@ function UsageDashboard() {
       current.tokens += row.processedTokens;
       map.set(key, current);
     }
-    return [...map.values()].sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
-  }, [rows]);
+    return [...map.values()].sort(byMetric);
+  }, [rows, byMetric]);
 
   // Projects can be worked on from several agents and providers, so a row keeps
-  // the dominant one by cost for its badge instead of claiming a single owner.
+  // the dominant one by the active metric for its badge instead of claiming a
+  // single owner.
   const projectBreakdown = useMemo(() => {
-    const map = new Map<string, BreakdownRow & { byAgent: Map<string, { name: string; cost: number }> }>();
+    const map = new Map<string, BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number }> }>();
     for (const row of rows) {
-      const current: BreakdownRow & { byAgent: Map<string, { name: string; cost: number }> } = map.get(row.project) ?? {
+      const current: BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number }> } = map.get(row.project) ?? {
         key: row.project, label: row.project, agent: row.agentName, agentId: row.agentId,
         provider: row.modelProviderName, providerId: row.modelProviderId, cost: 0, tokens: 0,
-        byAgent: new Map<string, { name: string; cost: number }>(),
+        byAgent: new Map<string, { name: string; cost: number; tokens: number }>(),
       };
       current.unknown = current.unknown || row.pricingStatus === "unknown";
       current.cost += row.costUsd;
       current.tokens += row.processedTokens;
-      const agent = current.byAgent.get(row.agentId) ?? { name: row.agentName, cost: 0 };
+      const agent = current.byAgent.get(row.agentId) ?? { name: row.agentName, cost: 0, tokens: 0 };
       agent.cost += row.costUsd;
+      agent.tokens += row.processedTokens;
       current.byAgent.set(row.agentId, agent);
       map.set(row.project, current);
     }
     return [...map.values()].map((item) => {
       const ranked = [...item.byAgent.entries()]
-        .map(([id, value]) => ({ id, name: value.name, cost: value.cost }))
-        .sort((a, b) => b.cost - a.cost);
+        .map(([id, value]) => ({ id, name: value.name, cost: value.cost, tokens: value.tokens }))
+        .sort(byMetric);
       const [dominant, ...others] = ranked;
       return {
         ...item,
@@ -1137,8 +1171,8 @@ function UsageDashboard() {
         agent: dominant?.name ?? item.agent,
         otherAgents: others,
       };
-    }).sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
-  }, [rows]);
+    }).sort(byMetric);
+  }, [rows, byMetric]);
 
   const dayBreakdown = useMemo(() => {
     const map = new Map<string, BreakdownRow>();
@@ -1154,7 +1188,7 @@ function UsageDashboard() {
 
   const days = useMemo(() => rangeDays(range), [range]);
 
-  useEffect(() => setBreakdownPage(1), [breakdownMode, machine, range]);
+  useEffect(() => setBreakdownPage(1), [breakdownMode, metricMode, machine, range]);
 
   useEffect(() => {
     const element = mainRef.current;
@@ -1198,14 +1232,20 @@ function UsageDashboard() {
   const activeModelProviders = data.modelProviders.filter((item) => usedProviderIds.has(item.id));
   const activeProviders = chartGroup === "agent" ? activeAgents : activeModelProviders;
   // A single dimension control (next to the chart) drives both the chart and
-  // the cost rows so the agent/provider tabs never repeat.
-  const costDimension = chartGroup;
-  const costDimensions = costDimension === "agent" ? activeAgents : activeModelProviders;
-  const providerTotals = costDimensions.map((item) => ({
-    ...item,
-    cost: rows.filter((row) => (costDimension === "agent" ? row.agentId : row.modelProviderId) === item.id).reduce((sum, row) => sum + row.costUsd, 0),
-    tokens: rows.filter((row) => (costDimension === "agent" ? row.agentId : row.modelProviderId) === item.id).reduce((sum, row) => sum + row.processedTokens, 0),
-  })).sort((a, b) => b.cost - a.cost || b.tokens - a.tokens);
+  // the share rows so the agent/provider tabs never repeat; the shared
+  // cost/tokens metric sets their sort order and primary value the same way.
+  const shareDimension = chartGroup;
+  const shareDimensions = shareDimension === "agent" ? activeAgents : activeModelProviders;
+  const providerTotals = shareDimensions.map((item) => {
+    const dimensionRows = rows.filter((row) => (shareDimension === "agent" ? row.agentId : row.modelProviderId) === item.id);
+    return {
+      ...item,
+      cost: dimensionRows.reduce((sum, row) => sum + row.costUsd, 0),
+      tokens: dimensionRows.reduce((sum, row) => sum + row.processedTokens, 0),
+      unknown: dimensionRows.some((row) => row.pricingStatus === "unknown"),
+    };
+  }).sort(byMetric);
+  const metricTotal = metricMode === "cost" ? totals.cost : totals.processed;
   const visibleMachines = data.machines.filter((item) => machine === "all" || item.id === machine);
   const visibleSources = data.sources.filter((source) => machine === "all" || source.machineId === machine);
   const sourceIssueMessage = getSourceIssueMessage(visibleMachines, visibleSources);
@@ -1331,7 +1371,7 @@ function UsageDashboard() {
                 {!stackedView && (
                   <div className="mt-7 min-h-0 flex-1 space-y-6 overflow-y-auto pr-3">
                     {providerTotals.map((item) => (
-                      <ProviderCostRow key={item.id} item={item} total={totals.cost} />
+                      <ProviderShareRow key={item.id} item={item} mode={metricMode} total={metricTotal} />
                     ))}
                   </div>
                 )}
@@ -1339,16 +1379,16 @@ function UsageDashboard() {
                 {stackedView && (
                   <div className="mt-5 min-w-0 border-t border-border/60 pt-4">
                     <div className="flex flex-wrap items-center gap-x-2 gap-y-2">
-                      <h2 className="mr-auto text-sm font-semibold">Daily {chartMode === "cost" ? "cost" : "tokens"}</h2>
+                      <h2 className="mr-auto text-sm font-semibold">Daily {metricMode === "cost" ? "cost" : "tokens"}</h2>
                       <ToggleGroup
-                        value={chartMode}
-                        onChange={setChartMode}
+                        value={metricMode}
+                        onChange={setMetricMode}
                         label="Chart value"
                         options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
                       />
                     </div>
                     <div className="mt-3">
-                      <UsageChart records={rows} providers={activeProviders} range={range} mode={chartMode} groupBy={chartGroup} compactView={compactView} />
+                      <UsageChart records={rows} providers={activeProviders} range={range} mode={metricMode} groupBy={chartGroup} compactView={compactView} />
                     </div>
                     <div className="mt-2">
                       <ChartLegend providers={activeProviders} />
@@ -1361,7 +1401,7 @@ function UsageDashboard() {
               {!stackedView && (
                 <div className="flex min-w-0 flex-col">
                   <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
-                    <h2 className="mr-auto text-sm font-semibold">Daily {chartMode === "cost" ? "cost" : "tokens"}</h2>
+                    <h2 className="mr-auto text-sm font-semibold">Daily {metricMode === "cost" ? "cost" : "tokens"}</h2>
                     <div className="flex flex-wrap items-center gap-2">
                       <ToggleGroup
                         value={chartGroup}
@@ -1370,15 +1410,15 @@ function UsageDashboard() {
                         options={[{ value: "agent", label: "Agents" }, { value: "provider", label: "Providers" }]}
                       />
                       <ToggleGroup
-                        value={chartMode}
-                        onChange={setChartMode}
+                        value={metricMode}
+                        onChange={setMetricMode}
                         label="Chart value"
                         options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
                       />
                     </div>
                   </div>
                   <div className="mt-4">
-                    <UsageChart records={rows} providers={activeProviders} range={range} mode={chartMode} groupBy={chartGroup} />
+                    <UsageChart records={rows} providers={activeProviders} range={range} mode={metricMode} groupBy={chartGroup} />
                   </div>
                   <div className="mt-2">
                     <ChartLegend providers={activeProviders} />
@@ -1392,7 +1432,7 @@ function UsageDashboard() {
                   <div className={`overflow-hidden ${CARD_CLASSES}`}>
                     {providerTotals.map((item) => (
                       <div key={item.id} className="border-t border-border/60 px-4 py-3.5 first:border-t-0">
-                        <ProviderCostRow item={item} total={totals.cost} />
+                        <ProviderShareRow item={item} mode={metricMode} total={metricTotal} />
                       </div>
                     ))}
                   </div>
@@ -1419,14 +1459,22 @@ function UsageDashboard() {
 
             {(!stackedView || mobileSection === "breakdown") && (
             <section>
-              <div className="flex items-center justify-between gap-4">
+              <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
                 <h2 className="text-sm font-semibold">Breakdown</h2>
-                <ToggleGroup
-                  value={breakdownMode}
-                  onChange={setBreakdownMode}
-                  label="Breakdown grouping"
-                  options={[{ value: "model", label: "Model" }, { value: "project", label: "Project" }, { value: "day", label: "Day" }]}
-                />
+                <div className="flex flex-wrap items-center gap-2">
+                  <ToggleGroup
+                    value={breakdownMode}
+                    onChange={setBreakdownMode}
+                    label="Breakdown grouping"
+                    options={[{ value: "model", label: "Model" }, { value: "project", label: "Project" }, { value: "day", label: "Day" }]}
+                  />
+                  <ToggleGroup
+                    value={metricMode}
+                    onChange={setMetricMode}
+                    label="Breakdown value"
+                    options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
+                  />
+                </div>
               </div>
 
               {compactView ? (
@@ -1440,7 +1488,11 @@ function UsageDashboard() {
                           )}
                           <span className="truncate">{row.label}</span>
                         </span>
-                        <span className="shrink-0 text-sm font-medium tabular-nums"><span title={row.unknown ? "Some usage has no recorded cost or known catalog rate; totals exclude that usage." : undefined}>{row.unknown && row.cost === 0 ? "Unknown" : <><CostValue value={row.cost} />{row.unknown ? "+" : ""}</>}</span></span>
+                        <span className="shrink-0 text-sm font-medium tabular-nums">
+                          {metricMode === "cost"
+                            ? <PricedCost cost={row.cost} unknown={row.unknown} />
+                            : <>{compact(row.tokens)}<span className="font-normal text-muted-foreground"> tokens</span></>}
+                        </span>
                       </div>
                       <div className="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1.5">
                         {breakdownMode !== "day" && (
@@ -1450,7 +1502,7 @@ function UsageDashboard() {
                             {row.otherAgents && row.otherAgents.length > 0 && (
                               <span
                                 className="shrink-0 tabular-nums text-foreground/70"
-                                title={row.otherAgents.map((item) => `${item.name} ${money(item.cost)}`).join(" · ")}
+                                title={row.otherAgents.map((item) => `${item.name} ${metricMode === "cost" ? money(item.cost) : `${compact(item.tokens)} tokens`}`).join(" · ")}
                               >
                                 +{row.otherAgents.length}
                               </span>
@@ -1458,10 +1510,22 @@ function UsageDashboard() {
                           </RowBadge>
                         )}
                         <RowBadge>
-                          <span className="tabular-nums text-foreground/80">{compact(row.tokens)}</span>
-                          <span>tokens</span>
+                          {metricMode === "cost" ? (
+                            <>
+                              <span className="tabular-nums text-foreground/80">{compact(row.tokens)}</span>
+                              <span>tokens</span>
+                            </>
+                          ) : row.unknown && row.cost === 0 ? (
+                            <span title="Some usage has no recorded cost or known catalog rate; totals exclude that usage.">Unknown cost</span>
+                          ) : (
+                            <span className="tabular-nums text-foreground/80">{money(row.cost)}{row.unknown ? "+" : ""}</span>
+                          )}
                         </RowBadge>
-                        <span className="ml-auto shrink-0 text-[11px] tabular-nums text-muted-foreground">{row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`}</span>
+                        <span className="ml-auto shrink-0 text-[11px] tabular-nums text-muted-foreground">
+                          {metricMode === "cost"
+                            ? row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`
+                            : percentage(row.tokens, totals.processed)}
+                        </span>
                       </div>
                     </div>
                   ))}
@@ -1477,9 +1541,9 @@ function UsageDashboard() {
                         {breakdownMode !== "day" && (
                           <th className="px-4 py-2.5 text-left font-medium">Agent</th>
                         )}
-                        <th className="px-4 py-2.5 text-right font-medium">Cost</th>
+                        <th className="px-4 py-2.5 text-right font-medium">{metricMode === "cost" ? "Cost" : "Tokens"}</th>
                         <th className="px-4 py-2.5 text-right font-medium">Share</th>
-                        <th className="px-4 py-2.5 text-right font-medium">Tokens</th>
+                        <th className="px-4 py-2.5 text-right font-medium">{metricMode === "cost" ? "Tokens" : "Cost"}</th>
                       </tr>
                     </thead>
                     <tbody>
@@ -1497,12 +1561,20 @@ function UsageDashboard() {
                           </td>
                           {breakdownMode !== "day" && (
                             <td className="px-4 py-3">
-                              <AgentCell agentId={row.agentId} agent={row.agent} others={row.otherAgents} />
+                              <AgentCell agentId={row.agentId} agent={row.agent} others={row.otherAgents} mode={metricMode} />
                             </td>
                           )}
-                          <td className="px-4 py-3 text-right tabular-nums"><span title={row.unknown ? "Some usage has no recorded cost or known catalog rate; totals exclude that usage." : undefined}>{row.unknown && row.cost === 0 ? "Unknown" : <><CostValue value={row.cost} />{row.unknown ? "+" : ""}</>}</span></td>
-                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">{row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`}</td>
-                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">{compact(row.tokens)}</td>
+                          <td className="px-4 py-3 text-right tabular-nums">
+                            {metricMode === "cost" ? <PricedCost cost={row.cost} unknown={row.unknown} /> : compact(row.tokens)}
+                          </td>
+                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">
+                            {metricMode === "cost"
+                              ? row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`
+                              : percentage(row.tokens, totals.processed)}
+                          </td>
+                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">
+                            {metricMode === "cost" ? compact(row.tokens) : <PricedCost cost={row.cost} unknown={row.unknown} />}
+                          </td>
                         </tr>
                       ))}
                     </tbody>
diff --git a/components/usage-dashboard-skeleton.tsx b/components/usage-dashboard-skeleton.tsx
index a5fc9bb..fe16903 100644
--- a/components/usage-dashboard-skeleton.tsx
+++ b/components/usage-dashboard-skeleton.tsx
@@ -331,18 +331,24 @@ export function UsageDashboardSkeleton() {
           </div>
         </section>
 
-        {/* breakdown: real heading, real toggle, real column headers */}
+        {/* breakdown: real heading, real toggles, real column headers */}
         <section>
-          <div className="flex items-center justify-between gap-4">
+          <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
             <Label className="text-sm font-semibold">Breakdown</Label>
-            <ToggleGroupPreview
-              value="model"
-              options={[
-                { value: "model", label: "Model" },
-                { value: "project", label: "Project" },
-                { value: "day", label: "Day" },
-              ]}
-            />
+            <div className="flex flex-wrap items-center gap-2">
+              <ToggleGroupPreview
+                value="model"
+                options={[
+                  { value: "model", label: "Model" },
+                  { value: "project", label: "Project" },
+                  { value: "day", label: "Day" },
+                ]}
+              />
+              <ToggleGroupPreview
+                value="cost"
+                options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
+              />
+            </div>
           </div>
 
           <div className={`mt-3 overflow-hidden ${CARD_CLASSES}`}>

From f4db28deece6fc87cc3bc946bd30330083c753bf Mon Sep 17 00:00:00 2001
From: mayank <mayankbansal125@gmail.com>
Date: Thu, 17 Sep 2026 18:16:16 +0000
Subject: [PATCH 2/3] feat: sort usage breakdown by token and cost headers

---
 README.md                               |   3 +-
 app.tsx                                 | 255 +++++++++++++-----------
 components/usage-dashboard-skeleton.tsx | 141 ++++++-------
 lib/usage-sort.test.ts                  |  38 ++++
 lib/usage-sort.ts                       |  25 +++
 5 files changed, 271 insertions(+), 191 deletions(-)
 create mode 100644 lib/usage-sort.test.ts
 create mode 100644 lib/usage-sort.ts

diff --git a/README.md b/README.md
index 4dc4787..ced6463 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,8 @@ Track coding-agent token usage and estimated API cost across every machine enrol
 - Collect usage from Codex, Claude Code, FX, Grok Agent, OpenCode, Pi, Prime Agent, and Antigravity.
 - Separate the coding agent from the underlying model provider.
 - Group charts and usage shares by agent or model provider.
-- Switch the chart, provider shares, and breakdown between cost and tokens, so unpriced usage stays visible.
+- Switch the chart and provider shares between cost and tokens.
+- Sort breakdowns by tokens or cost using column headers, with each metric’s share shown beneath its value. Unknown costs stay visible without a misleading percentage.
 - Break usage down by model, project, or day.
 - Filter by machine, agent, model provider, and the last 7, 30, or 90 days.
 - Show exact, alias-matched, agent-reported, and unknown pricing in the breakdown table.
diff --git a/app.tsx b/app.tsx
index 47dc5d3..3981e7a 100644
--- a/app.tsx
+++ b/app.tsx
@@ -11,6 +11,7 @@ import { useMediaQuery } from "@/components/ui/hooks/use-media-query";
 import { ProviderLimitsSkeleton, UsageDashboardSkeleton } from "@/components/usage-dashboard-skeleton";
 import { ProviderLogo, BRAND_COLORS, modelLogoId } from "@/components/provider-logo";
 import { paginateItems } from "@/lib/pagination";
+import { compareUsage, nextUsageSort, type MetricMode, type UsageSort } from "@/lib/usage-sort";
 import type { UsageSyncSnapshot } from "@/lib/sync-coordinator";
 import { isUsageSyncInProgress, shouldPollUsage, shouldShowInitialUsageLoading, usageRefreshError } from "@/lib/usage-sync-state";
 import { getEmptyUsageView, getSourceIssueMessage } from "@/lib/usage-view-state";
@@ -18,7 +19,6 @@ import { clampPercent, formatLimitReset, formatLimitValue, type ProviderLimitWin
 import { formatLocalMoney, localCurrency, usdToLocalRate } from "@/lib/local-currency";
 
 type Range = 7 | 30 | 90;
-type MetricMode = "cost" | "tokens";
 type BreakdownMode = "model" | "project" | "day";
 type DimensionMode = "agent" | "provider";
 
@@ -205,6 +205,51 @@ function PricedCost({ cost, unknown }: { cost: number; unknown?: boolean }) {
   );
 }
 
+function UsageSortButton({ metric, sort, onSort }: {
+  metric: MetricMode;
+  sort: UsageSort;
+  onSort: (metric: MetricMode) => void;
+}) {
+  const active = sort.metric === metric;
+  const next = nextUsageSort(sort, metric);
+  return (
+    <button
+      type="button"
+      onClick={() => onSort(metric)}
+      aria-label={`Sort by ${metric}, ${next.direction}`}
+      title={`Sort ${next.direction === "descending" ? "highest" : "lowest"} first`}
+      className={`inline-flex min-h-8 items-center justify-end gap-1.5 rounded px-1 text-xs font-medium outline-none transition-colors duration-150 hover:bg-muted/50 hover:text-foreground focus-visible:ring-1 focus-visible:ring-ring active:scale-[0.97] [@media(pointer:coarse)]:min-h-11 ${active ? "text-foreground" : "text-muted-foreground"}`}
+    >
+      {metric === "tokens" ? "Tokens" : "Cost"}
+      <Icon name={active ? sort.direction === "descending" ? "ArrowDown" : "ArrowUp" : "ArrowUpDown"} className="size-3.5" aria-hidden="true" />
+      {active && <span className="sr-only">Sorted {sort.direction}</span>}
+    </button>
+  );
+}
+
+function BreakdownValue({ metric, row, totals }: {
+  metric: MetricMode;
+  row: { cost: number; tokens: number; unknown?: boolean };
+  totals: { cost: number; processed: number; unknownTokens: number };
+}) {
+  const unknownCost = row.unknown && row.cost === 0;
+  return (
+    <div className="whitespace-nowrap tabular-nums">
+      <div className="text-sm font-medium">
+        {metric === "tokens" ? compact(row.tokens) : <PricedCost cost={row.cost} unknown={row.unknown} />}
+      </div>
+      {(metric === "tokens" || !unknownCost) && (
+        <div
+          className="mt-0.5 text-[11px] font-normal text-muted-foreground"
+          title={metric === "cost" && totals.unknownTokens > 0 ? "Share of priced cost; usage with unknown pricing is excluded." : undefined}
+        >
+          {metric === "tokens" ? `${percentage(row.tokens, totals.processed)} of tokens` : `${percentage(row.cost, totals.cost)} of cost`}
+        </div>
+      )}
+    </div>
+  );
+}
+
 function parseDay(day: string) {
   return new Date(`${day}T00:00:00Z`);
 }
@@ -646,7 +691,7 @@ function ProviderShareRow({
           ? <>{percentage(item.cost, total)} of cost · {compact(item.tokens)} tokens</>
           : item.unknown && item.cost === 0
             ? <>{percentage(item.tokens, total)} of tokens · <span title="Some usage has no recorded cost or known catalog rate; totals exclude that usage.">cost unknown</span></>
-            : <>{percentage(item.tokens, total)} of tokens · {money(item.cost)}{item.unknown ? "+" : ""}</>}
+            : <>{percentage(item.tokens, total)} of tokens · <PricedCost cost={item.cost} unknown={item.unknown} /></>}
       </div>
     </div>
   );
@@ -681,7 +726,7 @@ function AgentCell({
 }: {
   agentId: string;
   agent: string;
-  others?: Array<{ id: string; name: string; cost: number; tokens: number }>;
+  others?: Array<{ id: string; name: string; cost: number; tokens: number; unknown?: boolean }>;
   mode: MetricMode;
 }) {
   return (
@@ -709,7 +754,7 @@ function AgentCell({
                       <ProviderLogo id={item.id} name={item.name} size="sm" />
                       <span className="truncate">{item.name}</span>
                     </span>
-                    <span className="shrink-0 tabular-nums">{mode === "cost" ? money(item.cost) : `${compact(item.tokens)} tokens`}</span>
+                    <span className="shrink-0 tabular-nums">{mode === "cost" ? <PricedCost cost={item.cost} unknown={item.unknown} /> : `${compact(item.tokens)} tokens`}</span>
                   </div>
                 ))}
               </div>
@@ -721,14 +766,6 @@ function AgentCell({
   );
 }
 
-function RowBadge({ children }: { children: ReactNode }) {
-  return (
-    <span className="inline-flex min-w-0 max-w-full items-center gap-1.5 rounded-md border border-border/50 bg-muted/40 px-1.5 py-1 text-[11px] leading-none text-muted-foreground">
-      {children}
-    </span>
-  );
-}
-
 function ProviderLimits({
   limits,
   contentWidth,
@@ -968,7 +1005,8 @@ function UsageDashboard() {
   const providerLimitsRequestId = useRef(0);
   const { range, machine, showUsageLimits } = useUsageToolbar();
   const [chartGroup, setChartGroup] = useState<DimensionMode>("agent");
-  const [metricMode, setMetricMode] = useState<MetricMode>("tokens");
+  const [chartMode, setChartMode] = useState<MetricMode>("tokens");
+  const [breakdownSort, setBreakdownSort] = useState<UsageSort>({ metric: "tokens", direction: "descending" });
   const [breakdownMode, setBreakdownMode] = useState<BreakdownMode>("model");
   const [mobileSection, setMobileSection] = useState<"chart" | "breakdown">("chart");
   const [breakdownPage, setBreakdownPage] = useState(1);
@@ -1118,15 +1156,23 @@ function UsageDashboard() {
     cost: number; tokens: number; unknown?: boolean;
     // Only project rows fold several agents into one badge; the folded ones are
     // listed here so the `+N` suffix can name them on hover.
-    otherAgents?: Array<{ id: string; name: string; cost: number; tokens: number }>;
+    otherAgents?: Array<{ id: string; name: string; cost: number; tokens: number; unknown?: boolean }>;
   };
-  // Rows rank by the active metric, falling back to the other one so a $0
-  // unpriced row still sorts by its token volume (and vice versa).
-  const byMetric = useCallback(
+  // Chart share rows follow the chart metric; table sorting is independent.
+  const byChartMetric = useCallback(
     (a: { cost: number; tokens: number }, b: { cost: number; tokens: number }) =>
-      metricMode === "cost" ? b.cost - a.cost || b.tokens - a.tokens : b.tokens - a.tokens || b.cost - a.cost,
-    [metricMode],
+      chartMode === "cost" ? b.cost - a.cost || b.tokens - a.tokens : b.tokens - a.tokens || b.cost - a.cost,
+    [chartMode],
+  );
+  const byBreakdownMetric = useCallback(
+    (a: { cost: number; tokens: number; unknown?: boolean }, b: { cost: number; tokens: number; unknown?: boolean }) =>
+      compareUsage(a, b, { metric: breakdownSort.metric, direction: "descending" }),
+    [breakdownSort.metric],
   );
+  const sortBreakdown = (metric: MetricMode) => {
+    setBreakdownSort((current) => nextUsageSort(current, metric));
+    setBreakdownPage(1);
+  };
   const modelBreakdown = useMemo(() => {
     const map = new Map<string, BreakdownRow>();
     for (const row of rows) {
@@ -1137,33 +1183,34 @@ function UsageDashboard() {
       current.tokens += row.processedTokens;
       map.set(key, current);
     }
-    return [...map.values()].sort(byMetric);
-  }, [rows, byMetric]);
+    return [...map.values()];
+  }, [rows]);
 
   // Projects can be worked on from several agents and providers, so a row keeps
   // the dominant one by the active metric for its badge instead of claiming a
   // single owner.
   const projectBreakdown = useMemo(() => {
-    const map = new Map<string, BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number }> }>();
+    const map = new Map<string, BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number; unknown?: boolean }> }>();
     for (const row of rows) {
-      const current: BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number }> } = map.get(row.project) ?? {
+      const current: BreakdownRow & { byAgent: Map<string, { name: string; cost: number; tokens: number; unknown?: boolean }> } = map.get(row.project) ?? {
         key: row.project, label: row.project, agent: row.agentName, agentId: row.agentId,
         provider: row.modelProviderName, providerId: row.modelProviderId, cost: 0, tokens: 0,
-        byAgent: new Map<string, { name: string; cost: number; tokens: number }>(),
+        byAgent: new Map<string, { name: string; cost: number; tokens: number; unknown?: boolean }>(),
       };
       current.unknown = current.unknown || row.pricingStatus === "unknown";
       current.cost += row.costUsd;
       current.tokens += row.processedTokens;
-      const agent = current.byAgent.get(row.agentId) ?? { name: row.agentName, cost: 0, tokens: 0 };
+      const agent = current.byAgent.get(row.agentId) ?? { name: row.agentName, cost: 0, tokens: 0, unknown: false };
       agent.cost += row.costUsd;
       agent.tokens += row.processedTokens;
+      agent.unknown = agent.unknown || row.pricingStatus === "unknown";
       current.byAgent.set(row.agentId, agent);
       map.set(row.project, current);
     }
     return [...map.values()].map((item) => {
       const ranked = [...item.byAgent.entries()]
-        .map(([id, value]) => ({ id, name: value.name, cost: value.cost, tokens: value.tokens }))
-        .sort(byMetric);
+        .map(([id, value]) => ({ id, ...value }))
+        .sort(byBreakdownMetric);
       const [dominant, ...others] = ranked;
       return {
         ...item,
@@ -1171,8 +1218,8 @@ function UsageDashboard() {
         agent: dominant?.name ?? item.agent,
         otherAgents: others,
       };
-    }).sort(byMetric);
-  }, [rows, byMetric]);
+    });
+  }, [rows, byBreakdownMetric]);
 
   const dayBreakdown = useMemo(() => {
     const map = new Map<string, BreakdownRow>();
@@ -1188,7 +1235,7 @@ function UsageDashboard() {
 
   const days = useMemo(() => rangeDays(range), [range]);
 
-  useEffect(() => setBreakdownPage(1), [breakdownMode, metricMode, machine, range]);
+  useEffect(() => setBreakdownPage(1), [breakdownMode, machine, range]);
 
   useEffect(() => {
     const element = mainRef.current;
@@ -1244,8 +1291,8 @@ function UsageDashboard() {
       tokens: dimensionRows.reduce((sum, row) => sum + row.processedTokens, 0),
       unknown: dimensionRows.some((row) => row.pricingStatus === "unknown"),
     };
-  }).sort(byMetric);
-  const metricTotal = metricMode === "cost" ? totals.cost : totals.processed;
+  }).sort(byChartMetric);
+  const metricTotal = chartMode === "cost" ? totals.cost : totals.processed;
   const visibleMachines = data.machines.filter((item) => machine === "all" || item.id === machine);
   const visibleSources = data.sources.filter((source) => machine === "all" || source.machineId === machine);
   const sourceIssueMessage = getSourceIssueMessage(visibleMachines, visibleSources);
@@ -1264,9 +1311,10 @@ function UsageDashboard() {
     sources: visibleSources,
     hasRecordsOutsideView: data.records.some((record) => machine === "all" || record.machineId === machine),
   });
-  const breakdown = breakdownMode === "model" ? modelBreakdown
+  const breakdownRows = breakdownMode === "model" ? modelBreakdown
     : breakdownMode === "project" ? projectBreakdown
     : dayBreakdown;
+  const breakdown = [...breakdownRows].sort((a, b) => compareUsage(a, b, breakdownSort));
   const paginatedBreakdown = paginateItems(breakdown, breakdownPage, BREAKDOWN_PAGE_SIZE);
   const activeDays = new Set(rows.map((row) => row.day)).size;
   const visibleProviderLimits = providerLimits.filter((limit) =>
@@ -1371,7 +1419,7 @@ function UsageDashboard() {
                 {!stackedView && (
                   <div className="mt-7 min-h-0 flex-1 space-y-6 overflow-y-auto pr-3">
                     {providerTotals.map((item) => (
-                      <ProviderShareRow key={item.id} item={item} mode={metricMode} total={metricTotal} />
+                      <ProviderShareRow key={item.id} item={item} mode={chartMode} total={metricTotal} />
                     ))}
                   </div>
                 )}
@@ -1379,16 +1427,16 @@ function UsageDashboard() {
                 {stackedView && (
                   <div className="mt-5 min-w-0 border-t border-border/60 pt-4">
                     <div className="flex flex-wrap items-center gap-x-2 gap-y-2">
-                      <h2 className="mr-auto text-sm font-semibold">Daily {metricMode === "cost" ? "cost" : "tokens"}</h2>
+                      <h2 className="mr-auto text-sm font-semibold">Daily {chartMode === "cost" ? "cost" : "tokens"}</h2>
                       <ToggleGroup
-                        value={metricMode}
-                        onChange={setMetricMode}
+                        value={chartMode}
+                        onChange={setChartMode}
                         label="Chart value"
                         options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
                       />
                     </div>
                     <div className="mt-3">
-                      <UsageChart records={rows} providers={activeProviders} range={range} mode={metricMode} groupBy={chartGroup} compactView={compactView} />
+                      <UsageChart records={rows} providers={activeProviders} range={range} mode={chartMode} groupBy={chartGroup} compactView={compactView} />
                     </div>
                     <div className="mt-2">
                       <ChartLegend providers={activeProviders} />
@@ -1401,7 +1449,7 @@ function UsageDashboard() {
               {!stackedView && (
                 <div className="flex min-w-0 flex-col">
                   <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
-                    <h2 className="mr-auto text-sm font-semibold">Daily {metricMode === "cost" ? "cost" : "tokens"}</h2>
+                    <h2 className="mr-auto text-sm font-semibold">Daily {chartMode === "cost" ? "cost" : "tokens"}</h2>
                     <div className="flex flex-wrap items-center gap-2">
                       <ToggleGroup
                         value={chartGroup}
@@ -1410,15 +1458,15 @@ function UsageDashboard() {
                         options={[{ value: "agent", label: "Agents" }, { value: "provider", label: "Providers" }]}
                       />
                       <ToggleGroup
-                        value={metricMode}
-                        onChange={setMetricMode}
+                        value={chartMode}
+                        onChange={setChartMode}
                         label="Chart value"
                         options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
                       />
                     </div>
                   </div>
                   <div className="mt-4">
-                    <UsageChart records={rows} providers={activeProviders} range={range} mode={metricMode} groupBy={chartGroup} />
+                    <UsageChart records={rows} providers={activeProviders} range={range} mode={chartMode} groupBy={chartGroup} />
                   </div>
                   <div className="mt-2">
                     <ChartLegend providers={activeProviders} />
@@ -1432,7 +1480,7 @@ function UsageDashboard() {
                   <div className={`overflow-hidden ${CARD_CLASSES}`}>
                     {providerTotals.map((item) => (
                       <div key={item.id} className="border-t border-border/60 px-4 py-3.5 first:border-t-0">
-                        <ProviderShareRow item={item} mode={metricMode} total={metricTotal} />
+                        <ProviderShareRow item={item} mode={chartMode} total={metricTotal} />
                       </div>
                     ))}
                   </div>
@@ -1461,89 +1509,59 @@ function UsageDashboard() {
             <section>
               <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
                 <h2 className="text-sm font-semibold">Breakdown</h2>
-                <div className="flex flex-wrap items-center gap-2">
-                  <ToggleGroup
-                    value={breakdownMode}
-                    onChange={setBreakdownMode}
-                    label="Breakdown grouping"
-                    options={[{ value: "model", label: "Model" }, { value: "project", label: "Project" }, { value: "day", label: "Day" }]}
-                  />
-                  <ToggleGroup
-                    value={metricMode}
-                    onChange={setMetricMode}
-                    label="Breakdown value"
-                    options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
-                  />
-                </div>
+                <ToggleGroup
+                  value={breakdownMode}
+                  onChange={setBreakdownMode}
+                  label="Breakdown grouping"
+                  options={[{ value: "model", label: "Model" }, { value: "project", label: "Project" }, { value: "day", label: "Day" }]}
+                />
               </div>
 
               {compactView ? (
                 <div className={`mt-3 overflow-hidden ${CARD_CLASSES}`}>
+                  <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/20 px-3.5 py-1 text-xs text-muted-foreground">
+                    <span>Sort by</span>
+                    <div className="flex items-center gap-3" role="group" aria-label="Breakdown sorting">
+                      <UsageSortButton metric="tokens" sort={breakdownSort} onSort={sortBreakdown} />
+                      <UsageSortButton metric="cost" sort={breakdownSort} onSort={sortBreakdown} />
+                    </div>
+                  </div>
                   {paginatedBreakdown.items.map((row) => (
-                    <div key={row.key} className="border-t border-border/60 px-3.5 py-3 first:border-t-0">
-                      <div className="flex items-baseline justify-between gap-3">
-                        <span className="flex min-w-0 items-center gap-2 text-sm font-medium">
-                          {breakdownMode === "model" && (
-                            <ProviderLogo id={modelLogoId(row.label)} size="sm" />
-                          )}
-                          <span className="truncate">{row.label}</span>
-                        </span>
-                        <span className="shrink-0 text-sm font-medium tabular-nums">
-                          {metricMode === "cost"
-                            ? <PricedCost cost={row.cost} unknown={row.unknown} />
-                            : <>{compact(row.tokens)}<span className="font-normal text-muted-foreground"> tokens</span></>}
-                        </span>
+                    <div key={row.key} className="border-b border-border/60 px-3.5 py-3 last:border-b-0">
+                      <div className="flex min-w-0 items-center gap-2 text-sm font-medium">
+                        {breakdownMode === "model" && <ProviderLogo id={modelLogoId(row.label)} size="sm" />}
+                        <span className="truncate" title={row.label}>{row.label}</span>
                       </div>
-                      <div className="mt-2 flex flex-wrap items-center gap-x-2 gap-y-1.5">
-                        {breakdownMode !== "day" && (
-                          <RowBadge>
-                            <ProviderLogo id={row.agentId} name={row.agent} size="sm" />
-                            <span className="max-w-[110px] truncate">{row.agent}</span>
-                            {row.otherAgents && row.otherAgents.length > 0 && (
-                              <span
-                                className="shrink-0 tabular-nums text-foreground/70"
-                                title={row.otherAgents.map((item) => `${item.name} ${metricMode === "cost" ? money(item.cost) : `${compact(item.tokens)} tokens`}`).join(" · ")}
-                              >
-                                +{row.otherAgents.length}
-                              </span>
-                            )}
-                          </RowBadge>
-                        )}
-                        <RowBadge>
-                          {metricMode === "cost" ? (
-                            <>
-                              <span className="tabular-nums text-foreground/80">{compact(row.tokens)}</span>
-                              <span>tokens</span>
-                            </>
-                          ) : row.unknown && row.cost === 0 ? (
-                            <span title="Some usage has no recorded cost or known catalog rate; totals exclude that usage.">Unknown cost</span>
-                          ) : (
-                            <span className="tabular-nums text-foreground/80">{money(row.cost)}{row.unknown ? "+" : ""}</span>
-                          )}
-                        </RowBadge>
-                        <span className="ml-auto shrink-0 text-[11px] tabular-nums text-muted-foreground">
-                          {metricMode === "cost"
-                            ? row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`
-                            : percentage(row.tokens, totals.processed)}
-                        </span>
+                      {breakdownMode !== "day" && (
+                        <div className="mt-1.5 text-xs">
+                          <AgentCell agentId={row.agentId} agent={row.agent} others={row.otherAgents} mode={breakdownSort.metric} />
+                        </div>
+                      )}
+                      <div className="mt-3 grid grid-cols-2 gap-4">
+                        <BreakdownValue metric="tokens" row={row} totals={totals} />
+                        <div className="text-right">
+                          <BreakdownValue metric="cost" row={row} totals={totals} />
+                        </div>
                       </div>
                     </div>
                   ))}
                 </div>
               ) : (
                 <div className={`mt-3 overflow-x-auto ${CARD_CLASSES}`}>
-                  <table className="w-full border-collapse text-sm" style={{ minWidth: breakdownMode === "day" ? 520 : 640 }}>
+                  <table className="w-full border-collapse text-sm" aria-label="Usage breakdown" style={{ minWidth: breakdownMode === "day" ? 440 : 600 }}>
                     <thead>
                       <tr className="border-b border-border bg-muted/20 text-xs text-muted-foreground">
-                        <th className="px-4 py-2.5 text-left font-medium">
+                        <th scope="col" className="px-4 py-2.5 text-left font-medium">
                           {breakdownMode === "model" ? "Model" : breakdownMode === "project" ? "Project" : "Day"}
                         </th>
                         {breakdownMode !== "day" && (
-                          <th className="px-4 py-2.5 text-left font-medium">Agent</th>
+                          <th scope="col" className="px-4 py-2.5 text-left font-medium">Agent</th>
                         )}
-                        <th className="px-4 py-2.5 text-right font-medium">{metricMode === "cost" ? "Cost" : "Tokens"}</th>
-                        <th className="px-4 py-2.5 text-right font-medium">Share</th>
-                        <th className="px-4 py-2.5 text-right font-medium">{metricMode === "cost" ? "Tokens" : "Cost"}</th>
+                        {(["tokens", "cost"] as const).map((metric) => (
+                          <th key={metric} scope="col" aria-sort={breakdownSort.metric === metric ? breakdownSort.direction : undefined} className="px-3 py-1 text-right font-medium">
+                            <UsageSortButton metric={metric} sort={breakdownSort} onSort={sortBreakdown} />
+                          </th>
+                        ))}
                       </tr>
                     </thead>
                     <tbody>
@@ -1561,26 +1579,21 @@ function UsageDashboard() {
                           </td>
                           {breakdownMode !== "day" && (
                             <td className="px-4 py-3">
-                              <AgentCell agentId={row.agentId} agent={row.agent} others={row.otherAgents} mode={metricMode} />
+                              <AgentCell agentId={row.agentId} agent={row.agent} others={row.otherAgents} mode={breakdownSort.metric} />
                             </td>
                           )}
-                          <td className="px-4 py-3 text-right tabular-nums">
-                            {metricMode === "cost" ? <PricedCost cost={row.cost} unknown={row.unknown} /> : compact(row.tokens)}
-                          </td>
-                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">
-                            {metricMode === "cost"
-                              ? row.unknown && row.cost === 0 ? "—" : `${row.unknown ? "+" : ""}${percentage(row.cost, totals.cost)}`
-                              : percentage(row.tokens, totals.processed)}
+                          <td className="px-4 py-3 align-top text-right">
+                            <BreakdownValue metric="tokens" row={row} totals={totals} />
                           </td>
-                          <td className="px-4 py-3 text-right tabular-nums text-muted-foreground">
-                            {metricMode === "cost" ? compact(row.tokens) : <PricedCost cost={row.cost} unknown={row.unknown} />}
+                          <td className="px-4 py-3 align-top text-right">
+                            <BreakdownValue metric="cost" row={row} totals={totals} />
                           </td>
                         </tr>
                       ))}
                     </tbody>
-                   </table>
-                 </div>
-               )}
+                  </table>
+                </div>
+              )}
 
                {breakdown.length > BREAKDOWN_PAGE_SIZE && (
                  <div className="mt-4 flex flex-wrap items-center justify-center gap-2 text-xs tabular-nums text-muted-foreground sm:justify-end">
diff --git a/components/usage-dashboard-skeleton.tsx b/components/usage-dashboard-skeleton.tsx
index fe16903..aea0b62 100644
--- a/components/usage-dashboard-skeleton.tsx
+++ b/components/usage-dashboard-skeleton.tsx
@@ -1,4 +1,5 @@
 import { useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
+import { Icon } from "@/components/ui/icon";
 import { ToggleGroupPreview } from "@/components/ui/toggle-group";
 
 // The theme exposes its colors as complete color-mix() values rather than HSL
@@ -331,86 +332,88 @@ export function UsageDashboardSkeleton() {
           </div>
         </section>
 
-        {/* breakdown: real heading, real toggles, real column headers */}
+        {/* Match the fixed metric columns and default token sort. */}
         <section>
           <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
             <Label className="text-sm font-semibold">Breakdown</Label>
-            <div className="flex flex-wrap items-center gap-2">
-              <ToggleGroupPreview
-                value="model"
-                options={[
-                  { value: "model", label: "Model" },
-                  { value: "project", label: "Project" },
-                  { value: "day", label: "Day" },
-                ]}
-              />
-              <ToggleGroupPreview
-                value="cost"
-                options={[{ value: "cost", label: "Cost" }, { value: "tokens", label: "Tokens" }]}
-              />
-            </div>
+            <ToggleGroupPreview
+              value="model"
+              options={[
+                { value: "model", label: "Model" },
+                { value: "project", label: "Project" },
+                { value: "day", label: "Day" },
+              ]}
+            />
           </div>
 
           <div className={`mt-3 overflow-hidden ${CARD_CLASSES}`}>
-            {/* wide layouts: the real table header */}
-            <table className="hidden w-full border-collapse text-sm sm:table">
-              <thead>
-                <tr className="border-b border-border bg-muted/20 text-xs text-muted-foreground">
-                  <th className="px-4 py-2.5 text-left font-medium">Model</th>
-                  <th className="px-4 py-2.5 text-left font-medium">Agent</th>
-                  <th className="px-4 py-2.5 text-right font-medium">Cost</th>
-                  <th className="px-4 py-2.5 text-right font-medium">Share</th>
-                  <th className="px-4 py-2.5 text-right font-medium">Tokens</th>
-                </tr>
-              </thead>
-              <tbody>
+            {compactView ? (
+              <div>
+                <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/20 px-3.5 py-1 text-xs text-muted-foreground">
+                  <span>Sort by</span>
+                  <div className="flex items-center gap-3" aria-hidden="true">
+                    <span className="inline-flex min-h-8 items-center gap-1.5 px-1 font-medium text-foreground [@media(pointer:coarse)]:min-h-11">Tokens <Icon name="ArrowDown" className="size-3.5" /></span>
+                    <span className="inline-flex min-h-8 items-center gap-1.5 px-1 font-medium [@media(pointer:coarse)]:min-h-11">Cost <Icon name="ArrowUpDown" className="size-3.5" /></span>
+                  </div>
+                </div>
                 {[0, 1, 2, 3, 4].map((row) => (
-                  <tr key={row} className="border-b border-border/60 last:border-0">
-                    <td className="px-4 py-3">
-                      <div className="flex items-center gap-2">
-                        <Shimmer className="size-[18px] shrink-0 rounded-[4px]" />
-                        <Shimmer className="h-3.5 w-40 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                      </div>
-                    </td>
-                    <td className="px-4 py-3">
-                      <div className="flex items-center gap-2">
-                        <Shimmer className="size-[18px] shrink-0 rounded-[4px]" />
-                        <Shimmer className="h-3.5 w-20 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                      </div>
-                    </td>
-                    <td className="px-4 py-3">
-                      <Shimmer className="ml-auto h-3.5 w-16 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                    </td>
-                    <td className="px-4 py-3">
-                      <Shimmer className="ml-auto h-3.5 w-12 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                    </td>
-                    <td className="px-4 py-3">
-                      <Shimmer className="ml-auto h-3.5 w-12 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                    </td>
-                  </tr>
-                ))}
-              </tbody>
-            </table>
-
-            {/* narrow layouts: the stacked card rows */}
-            <div className="sm:hidden">
-              {[0, 1, 2, 3, 4].map((row) => (
-                <div key={row} className="border-t border-border/60 px-3.5 py-3 first:border-t-0">
-                  <div className="flex items-center justify-between gap-3">
-                    <div className="flex min-w-0 flex-1 items-center gap-2">
+                  <div key={row} className="border-b border-border/60 px-3.5 py-3 last:border-b-0">
+                    <div className="flex items-center gap-2">
                       <Shimmer className="size-[18px] shrink-0 rounded-[4px]" />
                       <Shimmer className="h-3.5 w-full max-w-[150px] rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
                     </div>
-                    <Shimmer className="h-3.5 w-14 shrink-0 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
-                  </div>
-                  <div className="mt-2 flex items-center gap-2">
-                    <Shimmer className="h-[22px] w-24 rounded-md" />
-                    <Shimmer className="h-[22px] w-20 rounded-md" />
-                    <Shimmer className="ml-auto h-3 w-10 rounded" />
+                    <Shimmer className="mt-1.5 h-4 w-24 rounded" />
+                    <div className="mt-3 grid grid-cols-2 gap-4">
+                      {[0, 1].map((metric) => (
+                        <div key={metric} className={metric === 1 ? "justify-self-end" : ""}>
+                          <Shimmer className={`h-5 w-16 rounded ${metric === 1 ? "ml-auto" : ""}`} />
+                          <Shimmer className="mt-0.5 h-4 w-24 rounded" />
+                        </div>
+                      ))}
+                    </div>
                   </div>
-                </div>
-              ))}
-            </div>
+                ))}
+              </div>
+            ) : (
+              <table className="w-full border-collapse text-sm">
+                <thead>
+                  <tr className="border-b border-border bg-muted/20 text-xs text-muted-foreground">
+                    <th className="px-4 py-2.5 text-left font-medium">Model</th>
+                    <th className="px-4 py-2.5 text-left font-medium">Agent</th>
+                    <th className="px-3 py-1 text-right font-medium text-foreground">
+                      <span className="inline-flex min-h-8 items-center gap-1.5 px-1 [@media(pointer:coarse)]:min-h-11">Tokens <Icon name="ArrowDown" className="size-3.5" aria-hidden="true" /></span>
+                    </th>
+                    <th className="px-3 py-1 text-right font-medium">
+                      <span className="inline-flex min-h-8 items-center gap-1.5 px-1 [@media(pointer:coarse)]:min-h-11">Cost <Icon name="ArrowUpDown" className="size-3.5" aria-hidden="true" /></span>
+                    </th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {[0, 1, 2, 3, 4].map((row) => (
+                    <tr key={row} className="border-b border-border/60 last:border-0">
+                      <td className="px-4 py-3">
+                        <div className="flex items-center gap-2">
+                          <Shimmer className="size-[18px] shrink-0 rounded-[4px]" />
+                          <Shimmer className="h-3.5 w-40 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
+                        </div>
+                      </td>
+                      <td className="px-4 py-3">
+                        <div className="flex items-center gap-2">
+                          <Shimmer className="size-[18px] shrink-0 rounded-[4px]" />
+                          <Shimmer className="h-3.5 w-20 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
+                        </div>
+                      </td>
+                      {[0, 1].map((metric) => (
+                        <td key={metric} className="px-4 py-3">
+                          <Shimmer className="ml-auto h-5 w-16 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
+                          <Shimmer className="ml-auto mt-0.5 h-4 w-24 rounded" style={{ animationDelay: `${-row * 0.18}s` }} />
+                        </td>
+                      ))}
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            )}
           </div>
         </section>
       </main>
diff --git a/lib/usage-sort.test.ts b/lib/usage-sort.test.ts
new file mode 100644
index 0000000..92ea7cc
--- /dev/null
+++ b/lib/usage-sort.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { compareUsage, nextUsageSort, type UsageSort } from "./usage-sort";
+
+describe("usage sorting", () => {
+  const rows = [
+    { id: "paid", cost: 10, tokens: 100 },
+    { id: "unpriced", cost: 0, tokens: 900, unknown: true },
+    { id: "free", cost: 0, tokens: 20 },
+    { id: "partial", cost: 2, tokens: 400, unknown: true },
+  ];
+  const ranked = (sort: UsageSort) => [...rows].sort((a, b) => compareUsage(a, b, sort)).map((row) => row.id);
+
+  it("includes unpriced usage in token rankings", () => {
+    expect(ranked({ metric: "tokens", direction: "descending" })).toEqual(["unpriced", "partial", "paid", "free"]);
+    expect(ranked({ metric: "tokens", direction: "ascending" })).toEqual(["free", "paid", "partial", "unpriced"]);
+  });
+
+  it("distinguishes free from unknown cost in both directions", () => {
+    expect(ranked({ metric: "cost", direction: "ascending" })).toEqual(["free", "partial", "paid", "unpriced"]);
+    expect(ranked({ metric: "cost", direction: "descending" })).toEqual(["paid", "partial", "free", "unpriced"]);
+  });
+
+  it("keeps token volume useful when all costs are unknown", () => {
+    const unpriced = rows.map((row) => ({ ...row, cost: 0, unknown: true }));
+    for (const direction of ["ascending", "descending"] as const) {
+      expect(unpriced.sort((a, b) => compareUsage(a, b, { metric: "cost", direction })).map((row) => row.id))
+        .toEqual(["unpriced", "partial", "paid", "free"]);
+    }
+  });
+
+  it("reverses the active column and starts a new column largest first", () => {
+    const initial: UsageSort = { metric: "tokens", direction: "descending" };
+    const ascending = nextUsageSort(initial, "tokens");
+    expect(ascending).toEqual({ metric: "tokens", direction: "ascending" });
+    expect(nextUsageSort(ascending, "tokens")).toEqual(initial);
+    expect(nextUsageSort(ascending, "cost")).toEqual({ metric: "cost", direction: "descending" });
+  });
+});
diff --git a/lib/usage-sort.ts b/lib/usage-sort.ts
new file mode 100644
index 0000000..aea1c0f
--- /dev/null
+++ b/lib/usage-sort.ts
@@ -0,0 +1,25 @@
+export type MetricMode = "cost" | "tokens";
+export type UsageSort = { metric: MetricMode; direction: "ascending" | "descending" };
+type UsageValue = { cost: number; tokens: number; unknown?: boolean };
+
+export function nextUsageSort(current: UsageSort, metric: MetricMode): UsageSort {
+  return {
+    metric,
+    direction: current.metric === metric && current.direction === "descending" ? "ascending" : "descending",
+  };
+}
+
+export function compareUsage(a: UsageValue, b: UsageValue, sort: UsageSort): number {
+  // An unknown cost is not a zero-dollar cost. Keep it after known values in
+  // either direction, while still allowing its tokens to sort normally.
+  if (sort.metric === "cost") {
+    const aUnknown = Boolean(a.unknown && a.cost === 0);
+    const bUnknown = Boolean(b.unknown && b.cost === 0);
+    if (aUnknown !== bUnknown) return aUnknown ? 1 : -1;
+  }
+  const otherMetric = sort.metric === "cost" ? "tokens" : "cost";
+  const difference = a[sort.metric] - b[sort.metric];
+  // Equal primary values keep the larger secondary value first in either
+  // direction, so reversing a sort does not shuffle ties unnecessarily.
+  return (sort.direction === "ascending" ? difference : -difference) || b[otherMetric] - a[otherMetric];
+}

From 28a6143dd5133ad072c31bf4534f5f7fbf6f76aa Mon Sep 17 00:00:00 2001
From: mayank <mayankbansal125@gmail.com>
Date: Thu, 17 Sep 2026 18:23:48 +0000
Subject: [PATCH 3/3] chore: bump version to 0.3.14

---
 package-lock.json | 4 ++--
 package.json      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index bd8d5dc..ec91798 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bb-plugin-usage",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bb-plugin-usage",
-      "version": "0.3.13",
+      "version": "0.3.14",
       "dependencies": {
         "@hugeicons/core-free-icons": "^4.1.3",
         "@hugeicons/react": "^1.1.6",
diff --git a/package.json b/package.json
index e97021a..96846e8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bb-plugin-usage",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "type": "module",
   "scripts": {
     "build": "bb plugin build",