Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat: chart monthly subscription dollars alongside token usage

Adam Eivy00854841e884
diff --git a/client/src/components/usage/MonthlyUsageCard.jsx b/client/src/components/usage/MonthlyUsageCard.jsx
new file mode 100644
index 0000000000..70094ab414
--- /dev/null
+++ b/client/src/components/usage/MonthlyUsageCard.jsx
@@ -0,0 +1,57 @@
+import { ComposedChart, Bar, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from 'recharts';
+import { Link } from 'react-router';
+import { formatCount, formatCompactCount, formatMonthYear, formatUsd } from '../../utils/formatters';
+
+const spendColor = 'rgb(var(--port-chart-2))';
+const tokenColor = 'rgb(var(--port-chart-3))';
+const monthLabel = (month) => formatMonthYear(`${month}-01`);
+const compactUsd = (value) => formatUsd(value, { compact: true });
+
+export default function MonthlyUsageCard({ history = [], savings }) {
+ const configured = savings?.configured === true;
+ const points = history.map((point) => ({
+ ...point,
+ spend: configured ? savings.totals.monthlyCost : null,
+ }));
+
+ return (
+ <section className="min-w-0 bg-port-card border border-port-border rounded-xl p-3 sm:p-4 space-y-3" aria-label="Monthly spend and tokens">
+ <h3 className="text-sm font-medium text-gray-400">Monthly subscription spend &amp; tokens</h3>
+ <p className="text-xs text-gray-500">
+ Last 12 calendar months, independent of the report filter. Bars show the full monthly subscription budget at your current prices, not historical invoices or API charges. Only plans with configured prices are included.
+ {' '}The line shows this machine&rsquo;s recorded input, output and cache tokens; counts may include estimates. The current and first recorded months may have partial token history.
+ </p>
+ {!configured && <p className="text-sm text-gray-400"><Link to="/models/subscriptions" className="text-port-accent underline">Set subscription prices</Link> to show dollar spend. Missing prices are not treated as zero.</p>}
+ <div className="flex flex-wrap gap-x-5 gap-y-1 text-xs text-gray-400">
+ <span style={{ color: spendColor }}>■ Subscription budget (USD, left axis)</span>
+ <span style={{ color: tokenColor }}>━ Tokens (right axis)</span>
+ </div>
+ {points.length === 0 ? <p className="text-sm text-gray-500">No monthly usage recorded yet.</p> : <>
+ <div className="h-64 min-w-0" role="img" aria-label="Monthly subscription budget bars with token trend; exact values in the table below">
+ <ResponsiveContainer width="100%" height="100%">
+ <ComposedChart data={points} margin={{ top: 8, right: 0, bottom: 0, left: 0 }}>
+ <CartesianGrid stroke="rgb(var(--port-border))" strokeDasharray="3 3" />
+ <XAxis dataKey="month" tickFormatter={monthLabel} minTickGap={30} tick={{ fontSize: 10 }} />
+ <YAxis yAxisId="spend" tickFormatter={compactUsd} width={55} tick={{ fontSize: 10 }} domain={[0, 'auto']} />
+ <YAxis yAxisId="tokens" orientation="right" tickFormatter={formatCompactCount} width={50} tick={{ fontSize: 10 }} domain={[0, 'auto']} />
+ <Tooltip labelFormatter={monthLabel} formatter={(value, name) => [name === 'Subscription budget' ? formatUsd(value) : formatCount(value), name]} contentStyle={{ background: 'rgb(var(--port-card))', borderColor: 'rgb(var(--port-border))' }} />
+ <Bar yAxisId="spend" dataKey="spend" name="Subscription budget" fill={spendColor} maxBarSize={36} isAnimationActive={false} />
+ <Line yAxisId="tokens" dataKey="tokens" name="Tokens" stroke={tokenColor} strokeWidth={2} dot={{ r: 3 }} isAnimationActive={false} />
+ </ComposedChart>
+ </ResponsiveContainer>
+ </div>
+ <details className="text-xs text-gray-400">
+ <summary className="cursor-pointer py-2">Monthly values</summary>
+ <table className="w-full text-left tabular-nums">
+ <thead><tr><th className="py-2">Month</th><th>Budget (USD)</th><th>Tokens</th></tr></thead>
+ <tbody>{points.map((point) => <tr key={point.month}>
+ <th className="py-2 font-normal">{monthLabel(point.month)}{point.partial ? ' (partial)' : ''}</th>
+ <td>{configured ? formatUsd(point.spend) : 'Not configured'}</td>
+ <td>{formatCount(point.tokens)}</td>
+ </tr>)}</tbody>
+ </table>
+ </details>
+ </>}
+ </section>
+ );
+}
diff --git a/client/src/components/usage/MonthlyUsageCard.test.jsx b/client/src/components/usage/MonthlyUsageCard.test.jsx
new file mode 100644
index 0000000000..a9b5ad86cb
--- /dev/null
+++ b/client/src/components/usage/MonthlyUsageCard.test.jsx
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import MonthlyUsageCard from './MonthlyUsageCard';
+
+const history = [
+ { month: '2026-09', tokens: 1250000, partial: false },
+ { month: '2026-10', tokens: 0, partial: true },
+];
+
+describe('monthly usage', () => {
+ it('labels configured dollar budgets honestly and exposes exact token totals without hover', () => {
+ render(<MemoryRouter><MonthlyUsageCard history={history} savings={{ configured: true, totals: { monthlyCost: 220 } }} /></MemoryRouter>);
+ expect(screen.getByText(/not historical invoices/)).toBeInTheDocument();
+ const rows = within(screen.getByRole('table')).getAllByRole('row');
+ expect(rows[1]).toHaveTextContent('September 2026$220.001,250,000');
+ expect(rows[2]).toHaveTextContent('October 2026 (partial)$220.000');
+ expect(screen.getByRole('img')).toHaveAccessibleName(/token trend/);
+ });
+
+ it('keeps missing prices distinct from zero while retaining the token series', () => {
+ render(<MemoryRouter><MonthlyUsageCard history={history} savings={{ configured: false }} /></MemoryRouter>);
+ expect(screen.getByRole('link', { name: 'Set subscription prices' })).toHaveAttribute('href', '/models/subscriptions');
+ expect(screen.getAllByText('Not configured')).toHaveLength(2);
+ expect(screen.getByText('1,250,000')).toBeInTheDocument();
+ expect(screen.queryByText('$0.00')).not.toBeInTheDocument();
+ });
+});
diff --git a/client/src/pages/UsagePage.jsx b/client/src/pages/UsagePage.jsx
index b271681b93..c077db12fc 100644
--- a/client/src/pages/UsagePage.jsx
+++ b/client/src/pages/UsagePage.jsx
@@ -12,6 +12,7 @@ import { useQuotaUpdates } from '../hooks/useQuotaUpdates';
import SubscriptionSavingsCard from '../components/usage/SubscriptionSavingsCard';
import ClaudeCodeModelTokensCard from '../components/usage/ClaudeCodeModelTokensCard';
import FleetUsageCard from '../components/usage/FleetUsageCard';
+import MonthlyUsageCard from '../components/usage/MonthlyUsageCard';
import RollingCostCard from '../components/usage/RollingCostCard';
import FreeTierUsageCard from '../components/usage/FreeTierUsageCard';
import ProviderQuotaBody from '../components/usage/ProviderQuotaBody';
@@ -658,6 +659,7 @@ function InternalUsageMetrics() {
<h2 className="text-lg font-semibold text-white">PortOS AI Usage</h2>
{/* Trailing 30 days across every instance — independent of the range below. */}
<RollingCostCard />
+ <MonthlyUsageCard history={usage.monthlyHistory} savings={usage.subscriptionSavings} />
{reportControls}
<div className="bg-port-card border border-port-border rounded-xl p-3 sm:p-4 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3">
diff --git a/server/services/usage.js b/server/services/usage.js
index eb543dea65..d6d79d9dfc 100644
--- a/server/services/usage.js
+++ b/server/services/usage.js
@@ -1132,6 +1132,30 @@ export function buildUsageReport(dailyActivity, { from = null, to = null, provid
};
}
+/** Calendar-month ledger totals, independent of the report filter. */
+function monthlyUsageHistory(providers) {
+ const today = new Date().toISOString().slice(0, 10);
+ const firstDay = getFirstActivityDay();
+ if (!firstDay) return [];
+ const now = new Date(`${today}T00:00:00Z`);
+ return Array.from({ length: 12 }, (_, index) => {
+ const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - 11 + index, 1));
+ const month = start.toISOString().slice(0, 7);
+ const end = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth() + 1, 0)).toISOString().slice(0, 10);
+ if (end < firstDay) return null;
+ const { totals } = buildUsageReport(usageData.dailyActivity, {
+ from: `${month}-01`, to: end < today ? end : today,
+ monthlyActivity: usageData.monthlyActivity, providers,
+ });
+ return {
+ month,
+ tokens: totals.tokensIn + totals.tokensOut + totals.cacheReadTokens + totals.cacheWriteTokens,
+ source: totals.source,
+ partial: today < end || firstDay > `${month}-01`,
+ };
+ }).filter(Boolean);
+}
+
/**
* Get usage summary. Optional `range` selects the cost-report window:
* `{ from, to }` as inclusive YYYY-MM-DD strings (null = unbounded), plus the
@@ -1155,6 +1179,7 @@ export function getUsageSummary({ from = null, to = null, providers = [] } = {})
}
return {
...empty,
+ monthlyHistory: [],
last7Days,
estimatedCost: 0,
topProviders: [],
@@ -1223,6 +1248,7 @@ export function getUsageSummary({ from = null, to = null, providers = [] } = {})
.sort((a, b) => b.sessions - a.sessions)
.slice(0, 5),
report,
+ monthlyHistory: monthlyUsageHistory(providers),
// Free-tier counterpart of the paid cost report: the report rows already
// free-classified (local inference, Zen quota), plus the observed limit
// blocks with ledger volume since each — the estimated-quota signal for
diff --git a/server/services/usage.test.js b/server/services/usage.test.js
index 5051f5fec6..11aad13a31 100644
--- a/server/services/usage.test.js
+++ b/server/services/usage.test.js
@@ -75,6 +75,20 @@ describe('usage.js — summary', () => {
vi.useRealTimers();
});
+ it('reports calendar months independently of the filter, preserving rollups and cache tokens', async () => {
+ readJSONFile.mockResolvedValueOnce(makeUsage({
+ '2025-06-01': { byProvider: { example: { tokensIn: 10, tokensOut: 20, cacheReadTokens: 30, cacheWriteTokens: 40, source: 'measured' } } },
+ '2025-06-10': { tokens: 5 },
+ }, { monthlyActivity: { '2025-04': { tokensIn: 100, tokens: 200 } } }));
+ await loadUsage();
+ const history = getUsageSummary({ from: '2025-06-10', to: '2025-06-11' }).monthlyHistory;
+ expect(history).toEqual([
+ { month: '2025-04', tokens: 300, source: 'estimate', partial: false },
+ { month: '2025-05', tokens: 0, source: 'estimate', partial: false },
+ { month: '2025-06', tokens: 105, source: 'mixed', partial: true },
+ ]);
+ });
+
describe('summary structure', () => {
it('returns all expected fields with correct types', async () => {
readJSONFile.mockResolvedValueOnce(makeUsage({}, {