LimitLine

Know how much Claude you have left.

A polished Claude Code status line that shows what you actually care about while coding — project, model, context %, and your 5‑hour usage window, at a glance. See your context, 5‑hour usage, and reset time without leaving your terminal.

website  Sonnet 5  chat 49%  5h: 24% used, resets 1h6m

• website — current project/folder (dim)
• Sonnet 5 — active model (cyan)
• chat 49% — context window used (magenta)
• 5h: 24% used, resets 1h6m — 5‑hour rate‑limit usage + reset countdown (yellow)

A percentage turns red only when it hits a critical level (≥ 90%). No icons, no blinking, no noise — one calm line of pure utility.

LimitLine renders a single line. The auto mode on (shift+tab to cycle) row you see beneath it is Claude Code's own footer, not part of LimitLine.

Install

npx limitline init

Install once. LimitLine follows Claude Code across your terminals. It configures LimitLine at Claude Code user scope (~/.claude/settings.json), so it appears whenever you launch the normal Claude Code CLI as the same user — in any compatible terminal (macOS Terminal, iTerm2, Warp, Windows Terminal, PowerShell, Linux terminals, and the integrated terminals of VS Code, Cursor, JetBrains, etc.). LimitLine is terminal-agnostic: it does not detect or integrate with specific terminals — it just configures Claude Code correctly.

To preview without changing anything:

npx limitline init --dry-run

What each metric means

| Segment | Source (Claude Code stdin JSON) | If unavailable | |---|---|---| | project | workspace.current_dir → basename (falls back to cwd) | n/a | | model | model.display_name (falls back to model.id) | n/a | | chat NN% | context_window.used_percentage | chat n/a | | 5h: NN% used | rate_limits.five_hour.used_percentage | omitted / 5h: n/a | | resets HhMm | rate_limits.five_hour.resets_at (unix seconds) | omitted |

Notes on availability (from Claude Code's own behavior):

• context_window.used_percentage is null early in a session and right after /compact until the next API call → shows chat n/a briefly.
• rate_limits appears only for Claude.ai Pro/Max subscribers, after the first API response in a session. On free plans (or before that first response) the 5h segment shows 5h: n/a.
• Percentages are shown as whole numbers. LimitLine never fabricates a value — missing data is always n/a.

Configuration behavior

LimitLine is intentionally zero‑config. Colors, thresholds, and layout are fixed. It respects two standard environment variables:

• NO_COLOR — disables all ANSI color (plain text).
• CLAUDE_CONFIG_DIR — honored when locating settings.json, same as Claude Code.

If you already use a custom status line

If you already use a custom Claude Code status line, LimitLine will not overwrite it. When limitline init finds an existing status line it makes zero changes and tells you:

LimitLine found an existing Claude Code status line. Nothing was changed.

Remove your current status line first, then run:
  limitline init

There is no --force, no merge, and no automatic replacement — this keeps the installer simple and safe. If you want LimitLine, remove your current status line from ~/.claude/settings.json first, then run limitline init.

Running init again once LimitLine is installed is idempotent — it reports that LimitLine is already installed and changes nothing.

If settings.json is not valid JSON, LimitLine refuses to touch it (it saves a backup copy and stops), so your file is never clobbered.

Uninstall

limitline uninstall

Restores the status line that was there before LimitLine (or removes LimitLine's entry if there wasn't one). Backup files are left in place. --dry-run supported.

Commands

| Command | Description | |---|---| | limitline init [--dry-run] | Install at user scope (refuses if a custom status line exists) | | limitline uninstall [--dry-run] | Remove LimitLine and restore what was there | | limitline status | Show whether LimitLine, nothing, or a custom status line is configured | | limitline doctor | Diagnostics: paths, ownership, backups, sample render | | limitline statusline | Internal — reads Claude Code JSON on stdin, prints the line |

Privacy

LimitLine is 100% local. No telemetry, no accounts, no cloud, no network calls — ever, including at render time. It reads only the JSON Claude Code hands it on stdin and (for install/uninstall) your ~/.claude/settings.json. It never reads credentials or authentication data.

Troubleshooting

• Nothing shows up: run limitline doctor to confirm it's installed and see a sample render. Restart Claude Code after installing.
• 5h: n/a: you're on a free plan, or Claude Code hasn't made its first API call this session yet. This is expected — LimitLine won't invent a number.
• chat n/a: normal briefly at session start and right after /compact.
• No colors: check NO_COLOR isn't set in your environment.
• Wrong / old status line still showing: re-render or restart Claude Code.

Limitations

• Claude Code only. It does not support any other tool or agent, by design.
• Shows in the Claude Code CLI status row only — not the Claude desktop app or claude.ai browser chat (those have no status line).
• Shows the 5‑hour window only (not the 7‑day window).
• Requires a Claude Code version that provides context_window / rate_limits in the status line payload for those segments to appear; otherwise they show n/a.
• If you already run a custom status line, LimitLine will not replace it (by design).

License

MIT — see LICENSE.

Not affiliated with Anthropic

LimitLine is an independent, unofficial utility. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.