# usage-bar: context and usage limits above the Claude Code prompt

> Canonical: https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/
> Author: MohammadMD1383 (https://github.com/MohammadMD1383) · Updated: 2026-10-04 · License: MIT

A one-line bar above the prompt: context window used/total, 5-hour and weekly limit usage with reset countdowns. Every section is optional.

- **Version** 0.2.1
- **License** MIT
- **Category** Productivity
- **Needs** Claude Code 2.1.288 or later

## On this page

1. [Install](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#install)
2. [Where the numbers come from](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#where-the-numbers-come-from)
3. [Configuration](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#configuration)
4. [Works well with](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#works-well-with)
5. [Development](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#development)
6. [License](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#license)
7. [FAQ](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-bar/#faq)

**A one-line bar above the prompt showing how much room you have left.**

```text
  ctx ━━━─── 84k/200k  ·  5h ━━──── 31% ↻ 2h14m  ·  week ━━━━━━ 93% ↻ 3d4h
╭──────────────────────────────────────────────────────────────────────────╮
│ >                                                                        │
╰──────────────────────────────────────────────────────────────────────────╯
```

| Section | What it shows |
| --- | --- |
| `ctx` | Tokens in the context window, used/total (`84k/200k`). Before the first response it shows `–/200k`. While you're viewing a subagent's transcript, this section is labelled `agent` and shows that subagent's context instead. |
| `5h` | How much of your 5-hour limit you've used, and how long until it resets. |
| `week` | How much of your weekly limit you've used, and how long until it resets. |

The labels and track are dim. A section turns **yellow** from 70% and **red** from 90%. Both thresholds can be changed.

This is a **mod**: a plugin of function hooks that draws into Claude Code's own interface. It needs Claude Code 2.1.288 or later. It runs no scripts, makes no network calls and adds nothing to Claude's context.

## Install

```text
/plugin marketplace add MohammadMD1383/claude-plugins
/plugin install usage-bar@mohammadmd-plugins
```

## Where the numbers come from

Everything comes from Claude Code itself. The mod doesn't poll or send any requests.

- **Context** updates after every model request, so it moves with each tool call during a long turn, not only when the turn ends. Claude Code only knows the size when a response finishes, so this is as live as it gets. Each subagent's context is tracked the same way. A subagent on the main model shares its window; one on another model is shown against the standard 200k window.
- **Limits** arrive with each response, and also mid-turn whenever a window moves by a whole point. They appear only on Pro and Max plans, after the first response of the session. With an API key, Bedrock or Vertex, only `ctx` is shown.
- **Reset countdowns** are relative (`42m`, `2h14m`, `3d4h`), so they're right in any time zone. They update every 30 seconds, also while you're idle.
- **Resets while idle:** when a window's reset time passes with no new response, the bar resets it on its own. The 5-hour window drops to `0%` with no countdown, because a new window only starts with your next message. The weekly window drops to `0%` and counts down to the same time next week.
- **Other sessions:** usage from Claude on other devices or sessions shows up with this session's next response, not while it's idle.
- **After `/clear` or `/resume`:** the bar stays. After `/clear` the context shows `–/200k` until the next response. The limits keep their last reading until a response brings a new one.
- **Narrow terminals:** if the line doesn't fit, the meters go first, then the countdowns.

## Configuration

Change these in `/config`, or under `pluginConfigs` in `settings.json`. Every section can be switched off.

| Option | Default | What it does |
| --- | --- | --- |
| `show_context` | `true` | Show the context-window section. |
| `show_five_hour` | `true` | Show the 5-hour limit section. |
| `show_weekly` | `true` | Show the weekly limit section. |
| `show_reset` | `true` | Show reset countdowns. |
| `show_meters` | `true` | Show the small meter beside each value. |
| `placement` | `above-prompt` | `above-prompt` gives the bar its own line above the input. `footer` appends a compact, dim version to the hint line under the input (`? for shortcuts · ctx 84k/200k · 5h 31% ↻ 2h14m`). The footer is drawn only in the terminal and always shows the main conversation's context. |
| `warn_pct` | `70` | The percentage at which a section turns yellow. |
| `critical_pct` | `90` | The percentage at which a section turns red. |

Example, to show only the limits, without meters:

```json
{
  "pluginConfigs": {
    "usage-bar@mohammadmd-plugins": {
      "options": { "show_context": false, "show_meters": false }
    }
  }
}
```

To hide the bar for a moment, collapse the band with `ctrl+x ctrl+a`.

## Works well with

[usage-guard](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-guard/). usage-bar shows you the numbers. usage-guard makes Claude act on them by conserving budget and writing a hand-off before the limit.

## Development

```bash
claude plugin validate .
claude plugin test .          # formatting, sections, widths, colors, footer, per-step and subagent context, idle resets, /clear
claude --plugin-dir .         # try it locally; edits hot-reload
```

Layout:

- `hooks/register.tsx` holds the hooks. `session.start` (and `classic.SessionStart` after a `/clear` or `/resume`, which fire no `session.start`) seeds the figures, `session.measure` stores them, `turn.step` refreshes the context after each model request (per subagent too), a 30-second clock redraws the countdowns, and `ui.render` draws the `AbovePrompt` band (or the `PromptHint` tail).
- `hooks/format.ts` holds the pure formatting and fitting logic.
- `types/index.d.ts` is the session-state contract.

## License

MIT

## FAQ

### How do I see my Claude Code usage limits in the terminal?

Install usage-bar. It shows how much of the 5-hour and weekly limits you have used, with reset countdowns, in one line above the prompt. The numbers appear after the first response of a session on Pro and Max plans.

### How do I see how full the Claude Code context window is?

usage-bar's ctx section shows tokens used out of the window size, for example 84k/200k, and updates after every model request, including for subagents.

### Does usage-bar replace my status line?

No. It draws its own band above the prompt (or in the footer hint line), so your status line stays as it is.

### Why don't the 5-hour and weekly sections show up?

They need a Pro or Max plan and appear after the first response of the session. With an API key, Bedrock or Vertex there are no plan limits, so only the context section is shown.

## Related

- [usage-guardUsage-limit awareness: know your limits, then checkpoint and hand off before claude.ai limits cut Claude off.](https://mohammadmd1383.github.io/claude-plugins/plugins/usage-guard/)
- [progress-barA progress bar above the prompt: Claude fills it in through a tool, and any script or command reports its…](https://mohammadmd1383.github.io/claude-plugins/plugins/progress-bar/)
- [Claude Code usage limitsHow Claude Code usage limits work on Pro and Max: the rolling 5-hour window, weekly and Opus/Sonnet limits…](https://mohammadmd1383.github.io/claude-plugins/guides/claude-code-usage-limits/)
- [Source codeusage-bar on GitHub: code, tests and README.](https://github.com/MohammadMD1383/claude-plugins/tree/main/plugins/usage-bar)
