{"slug": "claude-code-statusline-set-it-up-show-your-limits-keep-the-history", "title": "Claude Code statusline: set it up, show your limits, keep the history", "summary": "Claude Code's statusline, a configurable terminal row documented by Anthropic as of November 2026, runs a user-supplied script that receives JSON on standard input and prints model, context percentage, session cost, git branch and, for claude.ai Pro, Max and Ultra subscribers, five-hour and seven-day rate-limit usage. The statusline is set up via the /statusline command or a statusLine entry in ~/.claude/settings.json, runs locally at no API token cost, and batches updates over 300 milliseconds; the community tool ccstatusline (free, MIT licensed, run via npx -y ccstatusline@latest) builds the configuration through a widget menu. Because the statusline disappears when the terminal closes and Claude Code deletes local session files after 30 days by default, the open-source desktop app UsageAtlas is offered to retain limit history and alerts.", "body_md": "The Claude Code statusline is a row at the bottom of the terminal that runs a script you pick and shows whatever that script prints: model, context use, session cost, git branch, and on a Pro, Max or Ultra plan your five-hour and weekly limits. Set it up with the `/statusline` command or a `statusLine` entry in your settings, or let ccstatusline build it for you, then add UsageAtlas if you also want those limits with history and alerts after the terminal closes.\n\nThis guide follows [Anthropic's status line documentation](https://code.claude.com/docs/en/statusline) as of November 2026.\n\n## How the status line works\n\nClaude Code sends your script a block of JSON on standard input and displays what comes back on standard output. The script runs on your machine and costs no API tokens. It fires when a session starts, after each new assistant message, after `/compact`, when the permission mode changes, and when a limit window reaches its reset time. Updates are batched over 300 milliseconds, so a burst of changes runs the script once.\n\nOutput can span several lines, use ANSI colors, and include clickable links in terminals that support them. Keep it short. The row shares space with system notifications, and narrow windows cut it off.\n\n## Set it up in one command\n\nThe quickest route is to describe what you want:\n\n```\n/statusline show model, context percentage and my weekly limit\n```\n\nClaude Code writes a script into `~/.claude/` and points your settings at it. Run `/statusline` with no description to copy the look of your shell prompt, and `/statusline delete` to remove it.\n\n## Or configure it by hand\n\nAdd this to `~/.claude/settings.json`, or to a project's settings file:\n\n```\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"~/.claude/statusline.sh\",\n    \"padding\": 0\n  }\n}\n```\n\nA minimal Bash script for macOS or Linux, using `jq`:\n\n``` bash\n#!/bin/bash\ninput=$(cat)\nMODEL=$(echo \"$input\" | jq -r '.model.display_name')\nCTX=$(echo \"$input\" | jq -r '.context_window.used_percentage // 0')\nWEEK=$(echo \"$input\" | jq -r '.rate_limits.seven_day.used_percentage // empty')\necho \"$MODEL | ctx ${CTX}% ${WEEK:+| week ${WEEK}%}\"\n```\n\nMake it executable with `chmod +x`. On Windows, Claude Code runs the command through Git Bash when it is installed and PowerShell otherwise; write the path with forward slashes, because Git Bash swallows backslashes and the row stays blank.\n\n## What your script can read\n\n| Field | What it holds | \n|---|---|\n| `model.display_name` | The model in use | \n| `context_window.used_percentage` | How full the context window is | \n| `cost.total_cost_usd` | Session cost estimated at list price | \n| `rate_limits.five_hour` and`seven_day` | Percent used and reset time, epoch seconds | \n| `workspace` ,`pr` ,`worktree` | Folder, repository, open pull request | \n\nTwo catches on the limit fields. They appear only for claude.ai Pro, Max and Ultra subscribers, or behind a gateway with a spend limit, and only after the first API response of the session. Write scripts that print nothing when they are missing. The cost field is an estimate and can differ from your bill.\n\n## Skip the script with ccstatusline\n\nIf you would rather choose widgets than write Bash, [ccstatusline](https://github.com/sirmalloc/ccstatusline) is one of two community projects Anthropic's docs name. Run `npx -y ccstatusline@latest`, pick widgets in its terminal menu, and it writes the `statusLine` entry for you. It covers the five-hour block, weekly usage, reset timers, cost, context and git, with Powerline themes. It is free and MIT licensed.\n\n## Where the status line stops\n\nA status line lives inside one Claude Code window. Close the terminal and the numbers go with it. It shows nothing about Codex or Cursor, and Claude Code deletes local session files after 30 days by default, so last month's pattern is gone too.\n\nThat is the gap [UsageAtlas](https://usageatlas.com) fills. It is a free, open-source desktop app for Windows, macOS and Linux that keeps your Claude Code five-hour and weekly windows, reset times, tokens and estimated cost in one place, with daily history and a desktop alert when a window runs low. It reads the credentials and local logs already on your machine, needs no account for local tracking, and never reads prompts or responses. Its [comparison of ccstatusline and a usage dashboard](https://usageatlas.com/guides/ccstatusline-vs-usage-dashboard) explains why many people run both: they work side by side without conflicting.\n\nIf you only use Claude Code and look at the limit while typing, a status line alone is enough.", "url": "https://wpnews.pro/news/claude-code-statusline-set-it-up-show-your-limits-keep-the-history", "canonical_source": "https://usageatlas.com/guides/other/claude-code-statusline-setup-and-limits", "published_at": "2026-11-04 06:14:46+00:00", "updated_at": "2026-11-04 13:27:44.314094+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-products"], "entities": ["Claude Code", "Anthropic", "ccstatusline", "UsageAtlas", "Git Bash", "PowerShell"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-code-statusline-set-it-up-show-your-limits-keep-the-history", "markdown": "https://wpnews.pro/news/claude-code-statusline-set-it-up-show-your-limits-keep-the-history.md", "text": "https://wpnews.pro/news/claude-code-statusline-set-it-up-show-your-limits-keep-the-history.txt", "jsonld": "https://wpnews.pro/news/claude-code-statusline-set-it-up-show-your-limits-keep-the-history.jsonld"}}