[Phase 5.2] Cost analytics page: total spend and time range

[frankbria]

Goal

Create a /costs page (or Costs section in Settings) that surfaces total AI spend from the existing token_usage DB table.

Background

Token usage is already recorded per task. It is not surfaced anywhere in the web UI. Users need to know what they are spending.

Scope

• New route /costs linked from sidebar
• Summary cards: total spend in the selected period, total tasks run, average cost per task
• Time range selector: Last 7 days / 30 days / 90 days (default 30)
• Spend-over-time chart: daily bar chart using Recharts or similar already used in the codebase
• Backend: add GET /api/v2/costs/summary?days=30 that aggregates token_usage rows into daily buckets with cost calculated from model pricing table (hardcode sensible defaults per model, allow override via env)

Out of scope

• Per-task or per-agent breakdown (separate issue)
• Budget alerts

Acceptance criteria

• /costs renders with summary cards and chart
• Time range selector updates the chart
• Empty state shown when no data
• npm test and npm run build pass

[coderabbitai]

🔗 Related PRs

#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#225 - feat(api): add token usage timeseries endpoint for metrics charting [merged]
#442 - feat(metrics): token and cost tracking per task (#314) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• The backend is FastAPI with v2 routers under codeframe/ui/routers/, registered in file:codeframe/ui/server.py. The token_usage table is fully defined in file:codeframe/persistence/schema_manager.py and queried via file:codeframe/persistence/repositories/token_repository.py. MetricsTracker in file:codeframe/lib/metrics_tracker.py already has get_workspace_costs() and get_token_usage_timeseries() methods.
• The frontend is Next.js 15 (App Router) with swr for data fetching, axios for HTTP, Tailwind + Radix UI for components, and @hugeicons/react for icons. Recharts is not installed — no charting library exists in file:web-ui/package.json. The date-fns library is available.
• Sidebar nav items are defined in the NAV_ITEMS array in file:web-ui/src/components/layout/AppSidebar.tsx. Pages follow the pattern in file:web-ui/src/app/page.tsx using useSWR + workspacePath from localStorage.

Approach

Since Recharts is not installed, the bar chart will be implemented using a pure SVG/CSS approach (no new dependency needed), consistent with the project's zero-extra-dependency philosophy. The backend endpoint follows the v2 router pattern. The frontend page mirrors the workspace page pattern with useSWR, summary cards using existing Card components, and a time-range selector using native <select> or Radix Select.

---

Implementation Steps

1. Backend — Add get_costs_summary to TokenRepository

In file:codeframe/persistence/repositories/token_repository.py, add a new method get_costs_summary(days: int) that:

• Computes start_date as now() - timedelta(days=days) in UTC.
• Runs a single SQL query against token_usage grouping by DATE(timestamp) to produce daily buckets.
• Returns a dict with:
  • total_spend_usd: float
  • total_tasks: int (distinct task_id count, excluding NULLs)
  • avg_cost_per_task: float
  • daily: list[{date: str, cost_usd: float}] — one entry per calendar day in the range (fill zeros for days with no data).

Use the existing get_workspace_token_usage pattern for the DB connection and cursor access.

---

2. Backend — New v2 Router costs_v2.py

Create file:codeframe/ui/routers/costs_v2.py following the pattern of file:codeframe/ui/routers/events_v2.py:

• router = APIRouter(prefix="/api/v2/costs", tags=["costs"])
• Single endpoint: GET /api/v2/costs/summary
  • Query param: days: int = Query(30, ge=7, le=90) and workspace_path (resolved via get_v2_workspace dependency).
  • Instantiate TokenRepository (or call through the workspace's DB) and call get_costs_summary(days).
  • Return a Pydantic response model CostSummaryResponse with fields: total_spend_usd, total_tasks, avg_cost_per_task, daily (list of DailyCostPoint).
  • Return an empty-state response (all zeros, empty daily list) when no data exists — do not raise 404.
• Apply @rate_limit_standard() decorator consistent with other v2 routers.

Pydantic models (define inline in the router file):

DailyCostPoint: date (str), cost_usd (float)
CostSummaryResponse: total_spend_usd, total_tasks, avg_cost_per_task, daily: list[DailyCostPoint]

---

3. Backend — Register the Router in server.py

In file:codeframe/ui/server.py:

• Import costs_v2 from codeframe.ui.routers.
• Add app.include_router(costs_v2.router) alongside the other v2 routers with a comment # /api/v2/costs.

---

4. Frontend — TypeScript Types

In file:web-ui/src/types/index.ts, add:

• DailyCostPoint: { date: string; cost_usd: number }
• CostSummaryResponse: { total_spend_usd: number; total_tasks: number; avg_cost_per_task: number; daily: DailyCostPoint[] }

---

5. Frontend — API Client Method

In file:web-ui/src/lib/api.ts, add a costsApi object:

• getSummary(workspacePath: string, days: number): Promise<CostSummaryResponse> — calls GET /api/v2/costs/summary with workspace_path and days query params using the existing api axios instance.

---

6. Frontend — Bar Chart Component

Create file:web-ui/src/components/costs/SpendBarChart.tsx:

• A 'use client' component that accepts daily: DailyCostPoint[] and days: number as props.
• Renders a pure SVG bar chart (no external library):
  • Compute bar heights proportionally from cost_usd values.
  • X-axis: abbreviated date labels (use date-fns format for MMM d).
  • Y-axis: cost labels formatted as $0.0000.
  • Tooltip on hover using a title element or a positioned div.
• Show an empty-state message ("No spend data for this period") when daily is empty or all zeros.

---

7. Frontend — Costs Page

Create file:web-ui/src/app/costs/page.tsx:

'use client'

Structure mirrors file:web-ui/src/app/page.tsx:

1. State: workspacePath from getSelectedWorkspacePath(), days (number, default 30).
2. SWR fetch: key ['/api/v2/costs/summary', workspacePath, days], fetcher calls costsApi.getSummary(workspacePath, days). refreshInterval: 60000.
3. Time range selector: A <select> (or Radix Select) with options 7 / 30 / 90 days, updates days state on change.
4. Summary cards (3-column grid using existing Card, CardHeader, CardTitle, CardContent from file:web-ui/src/components/ui/card.tsx):
   • Total Spend: $X.XXXX — icon from @hugeicons/react (e.g., MoneyBag01Icon or CreditCardIcon).
   • Tasks Run: integer count.
   • Avg Cost / Task: $X.XXXX.
5. Chart section: renders <SpendBarChart daily={data.daily} days={days} />.
6. Loading state: skeleton pulse divs (same pattern as workspace page).
7. Empty state: shown when data.daily is empty — a centered message with a muted icon.
8. No workspace guard: redirect to workspace selector if workspacePath is null (same pattern as other pages).

---

8. Frontend — Sidebar Link

In file:web-ui/src/components/layout/AppSidebar.tsx:

• Import a suitable icon from @hugeicons/react (e.g., ChartBarLineIcon or Analytics01Icon).
• Add to NAV_ITEMS:

  { href: '/costs', label: 'Costs', icon: <chosen icon>, enabled: true }
  

  Place it after 'Proof' or logically after 'Sessions'.

---

Data Flow

sequenceDiagram
    participant User
    participant CostsPage
    participant costsApi
    participant FastAPI
    participant TokenRepository

    User->>CostsPage: Navigate to /costs
    CostsPage->>costsApi: getSummary(workspacePath, days=30)
    costsApi->>FastAPI: GET /api/v2/costs/summary?workspace_path=...&days=30
    FastAPI->>TokenRepository: get_costs_summary(days=30)
    TokenRepository-->>FastAPI: {total_spend_usd, total_tasks, avg_cost_per_task, daily[]}
    FastAPI-->>costsApi: CostSummaryResponse JSON
    costsApi-->>CostsPage: CostSummaryResponse
    CostsPage->>User: Render summary cards + bar chart

    User->>CostsPage: Change time range to 7 days
    CostsPage->>costsApi: getSummary(workspacePath, days=7)
    costsApi->>FastAPI: GET /api/v2/costs/summary?workspace_path=...&days=7
    FastAPI-->>CostsPage: Updated data
    CostsPage->>User: Re-render chart with new range

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- The backend is **FastAPI** with v2 routers under `codeframe/ui/routers/`, registered in `file:codeframe/ui/server.py`. The `token_usage` table is fully defined in `file:codeframe/persistence/schema_manager.py` and queried via `file:codeframe/persistence/repositories/token_repository.py`. `MetricsTracker` in `file:codeframe/lib/metrics_tracker.py` already has `get_workspace_costs()` and `get_token_usage_timeseries()` methods.
- The frontend is **Next.js 15 (App Router)** with `swr` for data fetching, `axios` for HTTP, Tailwind + Radix UI for components, and `@hugeicons/react` for icons. **Recharts is not installed** — no charting library exists in `file:web-ui/package.json`. The `date-fns` library is available.
- Sidebar nav items are defined in the `NAV_ITEMS` array in `file:web-ui/src/components/layout/AppSidebar.tsx`. Pages follow the pattern in `file:web-ui/src/app/page.tsx` using `useSWR` + `workspacePath` from localStorage.

## Approach

Since Recharts is not installed, the bar chart will be implemented using a pure SVG/CSS approach (no new dependency needed), consistent with the project's zero-extra-dependency philosophy. The backend endpoint follows the v2 router pattern. The frontend page mirrors the workspace page pattern with `useSWR`, summary cards using existing `Card` components, and a time-range selector using native `<select>` or Radix `Select`.

---

## Implementation Steps

### 1. Backend — Add `get_costs_summary` to `TokenRepository`

In `file:codeframe/persistence/repositories/token_repository.py`, add a new method `get_costs_summary(days: int)` that:
- Computes `start_date` as `now() - timedelta(days=days)` in UTC.
- Runs a single SQL query against `token_usage` grouping by `DATE(timestamp)` to produce daily buckets.
- Returns a dict with:
  - `total_spend_usd: float`
  - `total_tasks: int` (distinct `task_id` count, excluding NULLs)
  - `avg_cost_per_task: float`
  - `daily: list[{date: str, cost_usd: float}]` — one entry per calendar day in the range (fill zeros for days with no data).

Use the existing `get_workspace_token_usage` pattern for the DB connection and cursor access.

---

### 2. Backend — New v2 Router `costs_v2.py`

Create `file:codeframe/ui/routers/costs_v2.py` following the pattern of `file:codeframe/ui/routers/events_v2.py`:

- `router = APIRouter(prefix="/api/v2/costs", tags=["costs"])`
- Single endpoint: `GET /api/v2/costs/summary`
  - Query param: `days: int = Query(30, ge=7, le=90)` and `workspace_path` (resolved via `get_v2_workspace` dependency).
  - Instantiate `TokenRepository` (or call through the workspace's DB) and call `get_costs_summary(days)`.
  - Return a Pydantic response model `CostSummaryResponse` with fields: `total_spend_usd`, `total_tasks`, `avg_cost_per_task`, `daily` (list of `DailyCostPoint`).
  - Return an empty-state response (all zeros, empty `daily` list) when no data exists — do not raise 404.
- Apply `@rate_limit_standard()` decorator consistent with other v2 routers.

**Pydantic models** (define inline in the router file):
```
DailyCostPoint: date (str), cost_usd (float)
CostSummaryResponse: total_spend_usd, total_tasks, avg_cost_per_task, daily: list[DailyCostPoint]
```

---

### 3. Backend — Register the Router in `server.py`

In `file:codeframe/ui/server.py`:
- Import `costs_v2` from `codeframe.ui.routers`.
- Add `app.include_router(costs_v2.router)` alongside the other v2 routers with a comment `# /api/v2/costs`.

---

### 4. Frontend — TypeScript Types

In `file:web-ui/src/types/index.ts`, add:
- `DailyCostPoint`: `{ date: string; cost_usd: number }`
- `CostSummaryResponse`: `{ total_spend_usd: number; total_tasks: number; avg_cost_per_task: number; daily: DailyCostPoint[] }`

---

### 5. Frontend — API Client Method

In `file:web-ui/src/lib/api.ts`, add a `costsApi` object:
- `getSummary(workspacePath: string, days: number): Promise<CostSummaryResponse>` — calls `GET /api/v2/costs/summary` with `workspace_path` and `days` query params using the existing `api` axios instance.

---

### 6. Frontend — Bar Chart Component

Create `file:web-ui/src/components/costs/SpendBarChart.tsx`:
- A `'use client'` component that accepts `daily: DailyCostPoint[]` and `days: number` as props.
- Renders a pure SVG bar chart (no external library):
  - Compute bar heights proportionally from `cost_usd` values.
  - X-axis: abbreviated date labels (use `date-fns` `format` for `MMM d`).
  - Y-axis: cost labels formatted as `$0.0000`.
  - Tooltip on hover using a `title` element or a positioned `div`.
- Show an empty-state message ("No spend data for this period") when `daily` is empty or all zeros.

---

### 7. Frontend — Costs Page

Create `file:web-ui/src/app/costs/page.tsx`:

```
'use client'
```

Structure mirrors `file:web-ui/src/app/page.tsx`:

1. **State**: `workspacePath` from `getSelectedWorkspacePath()`, `days` (number, default `30`).
2. **SWR fetch**: key `['/api/v2/costs/summary', workspacePath, days]`, fetcher calls `costsApi.getSummary(workspacePath, days)`. `refreshInterval: 60000`.
3. **Time range selector**: A `<select>` (or Radix `Select`) with options `7 / 30 / 90` days, updates `days` state on change.
4. **Summary cards** (3-column grid using existing `Card`, `CardHeader`, `CardTitle`, `CardContent` from `file:web-ui/src/components/ui/card.tsx`):
   - **Total Spend**: `$X.XXXX` — icon from `@hugeicons/react` (e.g., `MoneyBag01Icon` or `CreditCardIcon`).
   - **Tasks Run**: integer count.
   - **Avg Cost / Task**: `$X.XXXX`.
5. **Chart section**: renders `<SpendBarChart daily={data.daily} days={days} />`.
6. **Loading state**: skeleton pulse divs (same pattern as workspace page).
7. **Empty state**: shown when `data.daily` is empty — a centered message with a muted icon.
8. **No workspace guard**: redirect to workspace selector if `workspacePath` is null (same pattern as other pages).

---

### 8. Frontend — Sidebar Link

In `file:web-ui/src/components/layout/AppSidebar.tsx`:
- Import a suitable icon from `@hugeicons/react` (e.g., `ChartBarLineIcon` or `Analytics01Icon`).
- Add to `NAV_ITEMS`:
  ```
  { href: '/costs', label: 'Costs', icon: <chosen icon>, enabled: true }
  ```
  Place it after `'Proof'` or logically after `'Sessions'`.

---

### Data Flow

```mermaid
sequenceDiagram
    participant User
    participant CostsPage
    participant costsApi
    participant FastAPI
    participant TokenRepository

    User->>CostsPage: Navigate to /costs
    CostsPage->>costsApi: getSummary(workspacePath, days=30)
    costsApi->>FastAPI: GET /api/v2/costs/summary?workspace_path=...&days=30
    FastAPI->>TokenRepository: get_costs_summary(days=30)
    TokenRepository-->>FastAPI: {total_spend_usd, total_tasks, avg_cost_per_task, daily[]}
    FastAPI-->>costsApi: CostSummaryResponse JSON
    costsApi-->>CostsPage: CostSummaryResponse
    CostsPage->>User: Render summary cards + bar chart

    User->>CostsPage: Change time range to 7 days
    CostsPage->>costsApi: getSummary(workspacePath, days=7)
    costsApi->>FastAPI: GET /api/v2/costs/summary?workspace_path=...&days=7
    FastAPI-->>CostsPage: Updated data
    CostsPage->>User: Re-render chart with new range
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.