Session Band

Know when Claude Code's prompt cache expires

·

source at c871c15

·

MIT license

Band above the prompt: turn number, output speed, turn and session cost, prompt cache countdown and context fill; notifies before the cache expires.

What this mod can do

  • Reviewed at commit c871c15
  • Runs programs
  • Runs Claude Code's tools, such as Bash and Edit, which still pass the session's permission check
  • Reads environment variables
3 more things it can do
  • Reads files
  • Adds the /session_data command
  • Runs on a timer
Good to know (3)
  • The macOS notifier is built once with notifier/build.sh and needs Xcode's command line tools
  • Without that helper, or off macOS, it uses Claude Code's own notification, with no title or click-through
  • Warnings come at 10 and 5 minutes left, and none fire while a turn is running
Are mods safe?

Preview

Terminal

⎿ session-band: Cache demo: 15 min left until the next answer resets it. ╭─────────────────────────────────────────────────────────────────────────────────────────────╮ [-] │ Turn 1 — $0.00 | $0.41 14:15 22% × │ ╰─────────────────────────────────────────────────────────────────────────────────────────────╯

Claude Desktop

Session Band in Claude Desktop

What it does

One band above the prompt with the turn number, output speed, turn and session cost, a prompt cache countdown and context fill. It warns you before the cache expires.

What you see
A one-row band above the prompt, framed amber then red
Works in
Terminal and Claude Desktop
Slash commands
/session_data
Uses your tokens
No
Changes files
Yes
Network access
Only through programs it runs
Reviewed commit
c871c15
Preview recorded with
Claude Code 2.1.296

How it works

  1. Restarts a 1-hour prompt cache countdown each time Claude answers
  2. Reads the last response's speed in tok/s, the turn and session cost, and context fill
  3. Draws one band above the prompt, dropping details as the window narrows
  4. Frames the band amber 20 minutes before the cache expires and red at 10

Common questions

How long does Claude Code's prompt cache last?

This mod counts down a 1-hour prompt cache from Claude's last answer, and the next answer resets it. The band turns amber with 20 minutes left and red with 10.

Can I get a notification before the prompt cache expires?

Yes. At 10 and 5 minutes left it posts a system notification saying how many minutes remain. On macOS a helper app built with notifier/build.sh gives it a title and click-through; otherwise it falls back to Claude Code's own notification, which also reaches your phone over Remote Control.

How do I preview the cache warning?

Run /session_data demo <minutes> to pretend the cache has that many minutes left. It shows the colors and the warning, and the next answer resets it.

How do I hide the band?

Click × to hide it for the rest of the session, or run /session_data to show or hide it.

More like this

Token Weather Usage in Claude Desktop

One line above the prompt: context tokens with their weather, a bar per recent prompt, your 5-hour and 7-day limits against the time elapsed, the prompt cache with its time left, the session cost with the last prompt's share in dollars and in points of the 5-hour limit, and the subagents running. Labels in English, French or Russian. After Token Weather (Anthropic, Apache-2.0) and the ideas of usage-meter (HolyGrail) and prompt-cache-control (Daniel San).

Deck in Claude Desktop

A cockpit for Claude Code: plan bars and subagent strips, context, usage limits with reset countdowns and burn rates, spend, the model route and a pet. Six bar styles, three collapsed looks. CLI and Desktop.

Flightdeck in Claude Desktop

Flightdeck: a live agent dashboard for Claude Code. Main model vitals, an on-call architect, every permission check, subagent cards and swimlanes, a turn receipt and a session log, all from real session events

╭─ CONTEXT ────────────────────────────────────────────╮ │ ████▊░░░░░░░░░░░░░░░░░ 22% of 200K · GOOD │ ├─ STATS ──────────────────────────────────────────────┤ │ ↓ 44.0K ↑ 1.4K │ $0.41 │ ⏱ 10m 12s │ +128/-34 │ ├─ REPO ───────────────────────────────────────────────┤ │ ◆ Opus 4.8 · main · 16:21 │ ╰──────────────────────────────────────────────────────╯

A boxed multi-line panel with auto-sizing borders: a context section with a gradient bar and status word, a stats section (tokens, cost, duration, lines changed), and a repo section (model, git branch with file counts, clock, vim mode), in a terracotta Claude-brand palette.

Opus 4.8 [high] ~/app main 16:20:55 | ⛁ ██░░░░░░░░ 22% | 5h ●◔○○○ 26% ↻2h7m | 7d ◔○○○○○○ 7% ↻2d1h │ $0.41 ⏱ 10m

Two-line status with a block context bar and quarter-step dot meters (◔◑◕●) for the 5-hour and weekly limits (fill shows usage, color shows whether you are ahead of or behind pace), plus model, effort, git and cost. Needs no jq.

████▊░░░░░░░░░░░░░░░░░ 22% of 200K · GOOD │ ↓ 44.0K ↑ 1.4K │ $0.41 │ ⏱ 10m 12s │ +128/-34 │ 5h 26% ↻2h06m │ 7d 7% ↻2d0h │ ◆ Opus 5.5 · main · 03:53

One-line adaptation of @kyleledbetter's Dreambase Panel: a context bar with status word, token/cost/duration/lines-changed stats, and model + git branch + clock, all on a single line in a terracotta Claude-brand palette.

Opus 4.8 │ main │ app │ ▓▓░░░░░░░░ 44k/200k │ $0.41

Catppuccin Frappé-themed status line with model, git branch and dirty flag, folder, a block context bar, and session cost.