token-meter · Claude Code mod

Preview · a replayed session in a sandbox

claude · ~/work/app · token-meter

› fix the failing auth test and add an audit log call ⏺ Read(src/auth.ts) ⎿ Read 6 lines ⏺ Update(src/auth.ts) ⎿ Added 2 lines, removed 1 line ⏺ Bash(bun test) ⎿ 3 pass, 1 fail ● Done. refresh now rejects expired claims and logs an audit event. ✻ Worked for 42s · done 4:20 PM ⟨Claude Code's own drawing⟩ ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ◆ TOKENS · PROMPT 1 ↓ 97.400 in ↑ 1.480 out │ Σ TOTAL 97.400 in · 1.480 out │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Band

⟨Claude Code's own drawing⟩ ╭──────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ◆ TOKENS · PROMPT 1 ↓ 97.400 in ↑ 1.480 out │ Σ TOTAL 97.400 in · 1.480 out │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

README

Claude Code mods

Two small mods for Claude Code that put the numbers you usually have to go looking for right above the prompt.

Mod	What it shows	Updates on
`token-meter`	Input and output tokens of the last prompt, plus the running total for the session	every completed turn
`session-stats`	Active model, effort level, context-window fill, and rate-limit usage with reset times	every model step and usage measurement

Install one or both. They stack: session-stats draws its row under whatever is already above the prompt.

╭────────────────────────────────────────────────────────────────────────────────────────╮
│ ◆ TOKENS · PROMPT 12   ↓ 48.213 in   ↑ 1.904 out   │   Σ TOTAL 402.118 in · 18.733 out │
╰────────────────────────────────────────────────────────────────────────────────────────╯
╭────────────────────────────────────────────────────────────────────────────────────────╮
│ ◈ MODEL opus-5-5   ✦ EFFORT high   ▤ CONTEXT ████░░░░░░ 41% 82.000/200.000             │
│ ⏱ 5h ███░░░ 47% ↻ Mon 19.10 14:30 (2h05)   ⏱ 7d █░░░░░ 18% ↻ Thu 22.10 09:00 (2d20h)   │
╰────────────────────────────────────────────────────────────────────────────────────────╯

(Illustrative values. Context and rate-limit bars are green below 60%, yellow from 60%, red from 85%. On a narrow terminal the row wraps.)

Why

Claude Code already tracks tokens, context and limits, but you have to ask for them (/context, /usage) and they are gone once you go back to typing. When you are working with a large context or close to a rate limit, a glance at the prompt is faster than a command, and it is easier to notice when a single prompt costs far more than expected.

Requirements

Claude Code with the function hooks mod API (built against 2.1.289, tested on 2.1.303).
Works where Claude Code draws the band above the prompt: the terminal and the desktop app's local sessions.
No dependencies, no build step. The engine loads the TypeScript source directly.

The function hooks API is early access and may change between Claude Code releases. If an update breaks a mod, Claude Code skips it and keeps working. Please open an issue.

Install

At the prompt of a Claude Code terminal session:

/plugin install token-meter --marketplace Marco-Sau/claude-code-mods
/plugin install session-stats --marketplace Marco-Sau/claude-code-mods

Answer y to add the marketplace (the first time only), then choose a scope (user scope is the default and loads the mod in every session). Each mod becomes active in that session right away.

Older Claude Code versions (error: unknown option '--marketplace'): add the marketplace once, then install by name. This form works on every version:

claude plugin marketplace add Marco-Sau/claude-code-mods
claude plugin install token-meter@marcosau-mods
claude plugin install session-stats@marcosau-mods

The same works at the prompt: /plugin marketplace add Marco-Sau/claude-code-mods, then /plugin install token-meter@marcosau-mods.

From a shell, on recent versions:

claude plugin install token-meter --marketplace Marco-Sau/claude-code-mods
claude plugin install session-stats --marketplace Marco-Sau/claude-code-mods

In the desktop app, where /plugin does not run: click + next to the prompt box, then Plugins, Add marketplace with Marco-Sau/claude-code-mods, then Add plugin.

Usage

There is nothing to configure or run. Send a prompt.

token-meter

↓ in: input tokens of the last prompt, including cache reads and cache writes, which is what the model actually processed.
↑ out: output tokens of the last prompt.
PROMPT n and Σ TOTAL: the number of prompts and the summed input and output since the session started.
The band appears after the first completed turn.

session-stats

MODEL: the model that answered the last step, without the claude- prefix.
EFFORT: the effort level of the last step, or default when none was set.
CONTEXT: how full the context window is, as a bar, a percentage, and tokens used over window size.
⏱ 5h / ⏱ 7d: rate-limit windows that Claude Code reports, with percent used and when each resets (local time and time left). These appear only when Claude Code reports rate limits for your account.

Both bands step aside while a survey is shown above the prompt.

What the mods can access

Both mods are a single TypeScript module each, which you can read in full in token-meter/hooks/register.tsx and session-stats/hooks/register.tsx.

	token-meter	session-stats
Events it listens to	`turn.complete`	`turn.step`, `session.measure`
What it draws	`AbovePrompt` band	`AbovePrompt` band
Engine calls	session state, UI elements	session state, UI elements, clock
Files, shell, network, other tools	none	none
Data kept	counters for the current session only	last model, effort, context and limits for the current session only

Mod code runs in Claude Code's sandboxed hooks environment, with no Node, filesystem or network access of its own. claude plugin validate reports exactly the hooks and calls listed above.

Update and uninstall

claude plugin update token-meter@marcosau-mods
claude plugin update session-stats@marcosau-mods

claude plugin uninstall token-meter@marcosau-mods
claude plugin uninstall session-stats@marcosau-mods

Updates apply after a restart (or /reload-plugins).

Known limitations

Main conversation only. Subagent turns are excluded from token-meter and do not change the model shown in session-stats.
Per session. Totals reset when a new session starts. They are not stored across sessions.
Input includes cache. ↓ in counts cache reads and cache writes together with fresh input. It reflects context size per prompt, not billed cost.
Number format. Thousands are separated with a dot (48.213), the European convention.
Rate limits depend on your account. They show only when Claude Code reports them; sessions that report none (for example some API-key setups) show no limit rows.
Early-access API. See Requirements.

Development

Each mod is a folder with .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx, a state contract in types/index.d.ts, and tests in tests/.

claude plugin validate ./token-meter      # manifest, hooks and state contract
claude plugin test ./token-meter          # runs tests/*.test.tsx against the engine
claude --plugin-dir ./token-meter         # try a local copy in one session

The tests cover the terminal and desktop surfaces.

License

Source 2 files

hooks/register.tsx 70 lines

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import type { Count } from '../types'
5
6const last = atom({ plugin: 'token-meter', key: 'last' } as const, null)
7const total = atom({ plugin: 'token-meter', key: 'total' } as const, { input: 0, output: 0, prompts: 0 })
8
9const fmt = (n: number) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, '.')
10
11export const register: Register = on => {
12  on('turn.complete', async ($, e, next) => {
13    const u = e.usage
14
15    if (u && !e.agentId) {
16      const turn: Count = {
17        input: u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens,
18        output: u.output_tokens,
19      }
20      await update($, last, () => turn)
21      await update($, total, t => ({ input: t.input + turn.input, output: t.output + turn.output, prompts: t.prompts + 1 }))
22    }
23
24    return next(e)
25  })
26
27  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
28    const below = await next(e)
29    const turn = await read($, last)
30
31    if (e.props.hasSurvey || turn === null) {
32      return below
33    }
34
35    const sum = await read($, total)
36    const { Box, Text } = $.ui.resolve(e)
37
38    const mine = (
39      <Box borderStyle="round" borderColor="magenta" paddingX={1} gap={2}>
40        <Text color="magenta" bold>
41          ◆ TOKENS · PROMPT {sum.prompts}
42        </Text>
43        <Text>
44          <Text color="cyan" bold>↓ {fmt(turn.input)}</Text>
45          <Text dimColor> in   </Text>
46          <Text color="green" bold>↑ {fmt(turn.output)}</Text>
47          <Text dimColor> out</Text>
48        </Text>
49        <Text dimColor>│</Text>
50        <Text>
51          <Text color="yellow" bold>Σ TOTAL </Text>
52          <Text color="cyan">{fmt(sum.input)}</Text>
53          <Text dimColor> in · </Text>
54          <Text color="green">{fmt(sum.output)}</Text>
55          <Text dimColor> out</Text>
56        </Text>
57      </Box>
58    )
59
60    return below ? (
61      <Box flexDirection="column">
62        {below}
63        {mine}
64      </Box>
65    ) : (
66      mine
67    )
68  })
69}
70

types/index.d.ts 8 lines

1export type Count = { input: number; output: number }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'token-meter': { last: Count | null; total: Count & { prompts: number } }
6  }
7}
8