# Context Usage Meter

Context Usage Meter [#context-usage-meter]

The **Context Usage Meter** is a token / context-window budget meter for local generation: a bar breaking down input / output / reasoning / cache token usage against the model's context-window limit (a hard local GGUF/LiteRT KV-cache constraint), warning as it approaches the limit. Feed it the `usage` from a generate result — or `useChat`'s per-turn `usage` / cumulative `totalUsage` (`{ inputTokens, outputTokens, totalTokens, durationMs }`). It is **local-only — there is no cost field**, and it complements the Storage Meter (disk) with a token-budget gauge. For a composable hovercard layout, use the lower-level `Context` / `ContextTrigger` / `ContextContent` / `ContextInputUsage` / `ContextOutputUsage` parts.

Preview [#preview]

```tsx
'use client';

import {
  Context,
  ContextContent,
  ContextInputUsage,
  ContextOutputUsage,
  ContextTrigger,
  ContextUsageMeter,
} from '@/components/context-usage-meter';

/**
 * Demo for ContextUsageMeter and its compound parts. Shows a near-limit warning
 * meter and the composable Context/Trigger/Content breakdown. No cost field —
 * local models have no billing.
 */
export default function ContextUsageMeterDemo() {
  const usage = {
    inputTokens: 5800,
    outputTokens: 900,
    reasoningTokens: 400,
    cachedTokens: 2048,
  };

  return (
    <div className="flex flex-col gap-5">
      <ContextUsageMeter {...usage} contextWindow={8192} />
      <Context usage={usage} contextWindow={8192}>
        <ContextTrigger />
        <ContextContent>
          <ContextInputUsage />
          <ContextOutputUsage />
        </ContextContent>
      </Context>
    </div>
  );
}
```

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/local-first/context-usage-meter
```

Data source & dependencies [#data-source--dependencies]

**Data source:** renders the `usage` shape you pass — works with any backend. Recommended producer: `useChat`'s `usage` (last turn) / `totalUsage` (cumulative), or a `useGenerateText` result's `usage`, from `@localmode/react` (on-device, optional).

* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `context-usage-meter.tsx` — `ContextUsageMeter` + `Context` / `ContextTrigger` / `ContextContent` / `ContextInputUsage` / `ContextOutputUsage`
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ContextUsageMeter**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `contextWindow` | `number` | — | **Required.** The model's context-window limit in tokens. |
| `warnThreshold` | `number` | `0.85` | Fraction (0–1) at which the meter warns. |
| `inputTokens` | `number` | — | Prompt / input tokens. |
| `outputTokens` | `number` | — | Generated / output tokens. |
| `reasoningTokens` | `number` | — | Reasoning ("thinking") tokens, if the model emits them. |
| `cachedTokens` | `number` | — | Tokens served from the prompt cache. |

**Context**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `usage` | `object` | — | **Required.** Token usage breakdown (e.g. from a generate result's `usage`). |
| `contextWindow` | `number` | — | **Required.** The model's context-window limit in tokens. |
| `warnThreshold` | `number` | `0.85` | Fraction (0–1) at which the meter warns. |
| `children` | `ReactNode` | — | **Required.** Compound children (`ContextTrigger`, `ContextContent`, …). |

Examples [#examples]

Simple meter [#simple-meter]

```tsx
<ContextUsageMeter inputTokens={1200} outputTokens={300} contextWindow={8192} />
```

Wired to `useChat` usage [#wired-to-usechat-usage]

```tsx
import { useChat } from '@localmode/react';
import { ContextUsageMeter } from '@/components/context-usage-meter';

export function ChatBudget({ model }) {
  const { totalUsage } = useChat({ model });
  return (
    <ContextUsageMeter
      inputTokens={totalUsage.inputTokens}
      outputTokens={totalUsage.outputTokens}
      contextWindow={8192}
    />
  );
}
```

`useChat` exposes `usage` (the last completed turn) and `totalUsage` (a running sum across the conversation) — use `totalUsage` for a context-budget gauge and `usage` for a per-turn readout.

Composable parts [#composable-parts]

```tsx
<Context usage={result.usage} contextWindow={8192}>
  <ContextTrigger />
  <ContextContent>
    <ContextInputUsage />
    <ContextOutputUsage />
  </ContextContent>
</Context>
```

Customization [#customization]

The warn state (amber) triggers past `warnThreshold` (default `0.85`). There is deliberately **no cost field** — local inference has no per-token billing. Styled entirely with shadcn/ui CSS-variable utilities so it inherits your theme — because you own the copied file, every class and threshold is yours to change.