Add a cost / rate-limit / branch status line, installed by setup.sh

Brings the repo's monitoring wedge to life: a status line showing model, context
usage, 5-hour + weekly plan limits (bars + time-to-reset), git branch/changes,
session time, and free disk.

- assets/statusline/: ccstatusline config (the rich 3-line display), a no-Node
  statusline.sh alternative (bash + jq + git), and a README
- setup.sh: install ccstatusline + jq, write the ccstatusline config and the
  statusline.sh alternative, and add `statusLine` to the generated settings.json
  (all idempotent and tolerant; tests still 32/32 green)
- docs: flesh out the status-line section on the monitoring page; add it to the
  bootstrap "what it does / writes" and the home "one command does" table

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: bogdanmatasaru

assets/README.md

@@ -10,6 +10,7 @@ safe by default — no destructive actions are ever auto-approved.
 | [`hooks/`](hooks/) | Hook snippets (format-on-edit, protect-paths, notify-on-stop) | your `settings.json` `hooks` block |
 | [`settings/`](settings/) | `settings.json` examples (minimal, team) | `~/.claude/settings.json` or `.claude/settings.json` |
 | [`skills/`](skills/) | Full shareable skills (e.g. project-onboard) | `~/.claude/skills/<name>/` |
+| [`statusline/`](statusline/) | A cost / rate-limit / branch status line | `~/.claude` + `~/.config/ccstatusline/` |
 
 Each folder has its own `README.md` with install instructions.
 

assets/statusline/README.md

@@ -0,0 +1,57 @@
+# Status line
+
+A status line at the bottom of Claude Code that shows, at a glance: the **model**,
+**context usage**, your **5-hour and weekly plan limits** (with bars + time-to-reset),
+the **git branch + changes**, **session time**, and **free disk**.
+
+This is the repo's monitoring wedge made real — you always see how much of your plan
+you've burned and when it resets, without running `/usage`.
+
+```text
+🤖 Opus 4.8   🧠 [███░░░░] 48%
+🟢 5h [███░░░░] 32% ⟳ 3h 3m    📅 7d [███░░░░] 31% ⟳ 4d 10h
+🌿 main +19 -8   ⏱ 4h 27m   💾 19.9G/48.0G
+```
+
+## Two ways to get it
+
+### Option A — `ccstatusline` (recommended, what `setup.sh` installs)
+
+[`ccstatusline`](https://github.com/sirmalloc/ccstatusline) is a configurable,
+multi-line status line for Claude Code (the 3-line display above). `setup.sh` installs
+it and writes this config for you. To do it by hand:
+
+```bash
+npm install -g ccstatusline
+mkdir -p ~/.config/ccstatusline
+cp ccstatusline-settings.json ~/.config/ccstatusline/settings.json
+```
+
+Then point Claude Code at it in `~/.claude/settings.json`:
+
+```json
+{ "statusLine": { "type": "command", "command": "ccstatusline", "padding": 0 } }
+```
+
+Tweak the widgets interactively by running `ccstatusline` in a terminal.
+
+### Option B — self-contained `statusline.sh` (no Node, just bash + jq + git)
+
+A single script with no dependencies beyond `jq` and `git`. Lighter, fully yours, but
+a single line and fewer widgets.
+
+```bash
+cp statusline.sh ~/.claude/statusline.sh && chmod +x ~/.claude/statusline.sh
+```
+
+```json
+{ "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" } }
+```
+
+## Notes
+
+- The **5-hour / weekly** segments rely on your Claude Code version exposing
+  `rate_limits` in the status payload. If yours doesn't, those segments are omitted
+  (the model + context + branch still show).
+- See [Monitor cost & rate limits](../../docs/environment/monitoring-cost-ratelimits.md)
+  for the full picture, including `/usage` and `/context`.

assets/statusline/ccstatusline-settings.json

@@ -0,0 +1,47 @@
+{
+  "version": 3,
+  "lines": [
+    [
+      { "id": "l1a", "type": "custom-text", "customText": "🤖 ", "color": "cyan" },
+      { "id": "l1b", "type": "model", "rawValue": true, "color": "cyan", "bold": true },
+      { "id": "l1c", "type": "custom-text", "customText": "   🧠 ", "color": "white" },
+      { "id": "l1d", "type": "context-bar", "rawValue": true, "color": "white" }
+    ],
+    [
+      { "id": "l2a", "type": "custom-text", "customText": "🟢 5h ", "color": "green" },
+      { "id": "l2b", "type": "session-usage", "rawValue": true, "color": "green", "metadata": { "display": "progress-short" } },
+      { "id": "l2c", "type": "custom-text", "customText": " ⟳ ", "color": "brightBlack" },
+      { "id": "l2d", "type": "reset-timer", "rawValue": true, "color": "brightBlack" },
+      { "id": "l2e", "type": "custom-text", "customText": "    📅 7d ", "color": "blue" },
+      { "id": "l2f", "type": "weekly-usage", "rawValue": true, "color": "blue", "metadata": { "display": "progress-short" } },
+      { "id": "l2g", "type": "custom-text", "customText": " ⟳ ", "color": "brightBlack" },
+      { "id": "l2h", "type": "weekly-reset-timer", "rawValue": true, "color": "brightBlack" }
+    ],
+    [
+      { "id": "l3a", "type": "custom-text", "customText": "🌿 ", "color": "magenta" },
+      { "id": "l3b", "type": "git-branch", "rawValue": true, "color": "magenta" },
+      { "id": "l3c", "type": "custom-text", "customText": "  ", "color": "yellow" },
+      { "id": "l3d", "type": "git-changes", "color": "yellow" },
+      { "id": "l3e", "type": "custom-text", "customText": "   ⏱ ", "color": "brightBlack" },
+      { "id": "l3f", "type": "session-clock", "rawValue": true, "color": "brightBlack" },
+      { "id": "l3g", "type": "custom-text", "customText": "   💾 ", "color": "brightBlack" },
+      { "id": "l3h", "type": "free-memory", "rawValue": true, "color": "brightBlack" }
+    ]
+  ],
+  "flexMode": "full-minus-40",
+  "compactThreshold": 60,
+  "colorLevel": 2,
+  "inheritSeparatorColors": false,
+  "globalBold": false,
+  "gitCacheTtlSeconds": 5,
+  "minimalistMode": false,
+  "powerline": {
+    "enabled": false,
+    "separators": [""],
+    "separatorInvertBackground": [false],
+    "startCaps": [],
+    "endCaps": [],
+    "autoAlign": false,
+    "continueThemeAcrossLines": false
+  }
+}

assets/statusline/statusline.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Self-contained Claude Code status line — model, context %, your Max-plan limits
+# (5-hour window + weekly) with time-to-reset, and the git branch.
+#
+# Needs: bash + jq + git. Lighter than ccstatusline (no Node). The rate-limit
+# fields depend on your Claude Code version exposing them in the status payload;
+# if it doesn't, those segments are simply omitted.
+#
+# Enable: copy to ~/.claude/statusline.sh, then set in ~/.claude/settings.json:
+#   "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
+
+input=$(cat)
+field() { printf '%s' "$input" | jq -r "$1" 2>/dev/null; }
+
+model=$(field '.model.display_name // "?"')
+ctx=$(field '.context_window.used_percentage // 0' | cut -d. -f1)
+h5_pct=$(field '.rate_limits.five_hour.used_percentage // empty')
+h5_reset=$(field '.rate_limits.five_hour.resets_at // empty')
+w_pct=$(field '.rate_limits.seven_day.used_percentage // empty')
+w_reset=$(field '.rate_limits.seven_day.resets_at // empty')
+cwd=$(field '.workspace.current_dir // .cwd // empty')
+
+now=$(date +%s)
+
+fmt_left() {  # seconds -> "2h 13m" / "3d 4h"
+  local secs=$1
+  [ -z "$secs" ] && { printf '?'; return; }
+  (( secs < 0 )) && secs=0
+  local d=$(( secs / 86400 )) h=$(( (secs % 86400) / 3600 )) m=$(( (secs % 3600) / 60 ))
+  if   (( d > 0 )); then printf '%dd %dh' "$d" "$h"
+  elif (( h > 0 )); then printf '%dh %dm' "$h" "$m"
+  else printf '%dm' "$m"; fi
+}
+
+bar() {  # 0-100% -> a 10-segment bar
+  local pct=${1%.*}; [ -z "$pct" ] && pct=0
+  local filled=$(( pct / 10 )); (( filled > 10 )) && filled=10
+  local i out=""
+  for ((i=0;i<10;i++)); do (( i < filled )) && out+="█" || out+="░"; done
+  printf '%s' "$out"
+}
+
+seg="🤖 $model  🧠 ${ctx}% ctx"
+
+branch=$(git -C "${cwd:-.}" rev-parse --abbrev-ref HEAD 2>/dev/null)
+[ -n "$branch" ] && seg+="  🌿 $branch"
+
+if [ -n "$h5_pct" ]; then
+  p=${h5_pct%.*}; seg+="  ⏱️ 5h $(bar "$p") ${p}% (reset $(fmt_left $(( h5_reset - now ))))"
+fi
+if [ -n "$w_pct" ]; then
+  p=${w_pct%.*}; seg+="  📅 7d $(bar "$p") ${p}% (reset $(fmt_left $(( w_reset - now ))))"
+fi
+
+printf '%s' "$seg"

docs/environment/bootstrap-setup.md

@@ -16,11 +16,13 @@ The script runs everything from zero, in order:
 4. **JetBrains Mono** — `brew install --cask font-jetbrains-mono`.
 5. **Node.js** — the runtime for Claude Code and many projects.
 6. **GitHub CLI (`gh`)** — for pull requests and the GitHub MCP.
-7. **Claude Code** — via the official native installer (`curl -fsSL https://claude.ai/install.sh | bash`), with an npm fallback. Persists `~/.local/bin` on your PATH.
-8. **Ghostty config** — writes `~/.config/ghostty/config` (Catppuccin auto dark/light, JetBrains Mono).
-9. **Global Claude config** — writes `~/.claude/settings.json` and `~/.claude/CLAUDE.md`, but only if they don't already exist.
-10. **Shell aliases** — adds `cc`, `ccc`, `ccp` to `~/.zshrc`.
-11. **Validation** — runs `validate()` to report what's in place and what's missing.
+7. **jq** — used by the example hooks and the status line.
+8. **Claude Code** — via the official native installer (`curl -fsSL https://claude.ai/install.sh | bash`), with an npm fallback. Persists `~/.local/bin` on your PATH.
+9. **Ghostty config** — writes `~/.config/ghostty/config` (Catppuccin auto dark/light, JetBrains Mono).
+10. **Global Claude config** — writes `~/.claude/settings.json` and `~/.claude/CLAUDE.md`, but only if they don't already exist.
+11. **Status line** — installs [ccstatusline](https://github.com/sirmalloc/ccstatusline) and writes its config (model · context · 5h/weekly limits · branch · session · disk), plus a no-Node `statusline.sh` alternative. The settings.json points at it.
+12. **Shell aliases** — adds `cc`, `ccc`, `ccp` to `~/.zshrc`.
+13. **Validation** — runs `validate()` to report what's in place and what's missing.
 
 ## Flags
 
@@ -76,8 +78,10 @@ Then:
 | Path | Contents |
 | --- | --- |
 | `~/.config/ghostty/config` | Ghostty theme, font, padding, cursor settings. |
-| `~/.claude/settings.json` | Global settings with a small safe permission allowlist (only if absent). |
+| `~/.claude/settings.json` | Global settings: permission allowlist + the `statusLine` (only if absent). |
 | `~/.claude/CLAUDE.md` | Global preferences (only if absent). |
+| `~/.config/ccstatusline/settings.json` | Status-line layout (only if absent). |
+| `~/.claude/statusline.sh` | No-Node status-line alternative (only if absent). |
 | `~/.zshrc` | `brew shellenv`, `~/.local/bin` on PATH, and the `cc` / `ccc` / `ccp` aliases. |
 
 The aliases: `cc` = `claude`, `ccc` = `claude --continue` (resume the last session), `ccp` = `claude --permission-mode plan`.

docs/environment/monitoring-cost-ratelimits.md

@@ -30,10 +30,18 @@ Run `/context` to see how full the current conversation's **context window** is.
 
 ## A live status line
 
-You can surface rate-limit and context info **continuously** with a status line, configured via `statusLine` in `~/.claude/settings.json`. Instead of running `/usage` repeatedly, you get a live readout at the bottom of the prompt.
+Instead of running `/usage` repeatedly, keep a **status line** pinned to the bottom of the prompt that always shows your model, context usage, your 5-hour and weekly limits (with bars and time-to-reset), the git branch, session time, and free disk:
+
+```text
+🤖 Opus 4.8   🧠 [███░░░░] 48%
+🟢 5h [███░░░░] 32% ⟳ 3h 3m    📅 7d [███░░░░] 31% ⟳ 4d 10h
+🌿 main +19 -8   ⏱ 4h 27m   💾 19.9G/48.0G
+```
+
+The [one-command setup](./bootstrap-setup.md) installs this for you — via [ccstatusline](https://github.com/sirmalloc/ccstatusline) — and wires it into `~/.claude/settings.json`. To set it up by hand, or to use the no-Node `statusline.sh` alternative (just bash + jq + git), see the [status-line assets](https://github.com/bogdanmatasaru/claude-code-guide/tree/main/assets/statusline).
 
 > [!TIP]
-> A status line that shows remaining context and time-to-reset is the cheapest insurance against an unexpected limit mid-task.
+> A status line that shows remaining context and time-to-reset is the cheapest insurance against an unexpected limit mid-task. It's the whole point of this guide's setup — you never have to wonder how much plan you've got left.
 
 ## What to do when you hit a limit
 

docs/index.md

@@ -67,6 +67,7 @@ It runs an idempotent, re-runnable bootstrap that installs and configures everyt
 | 4 | **Node.js** + GitHub CLI |
 | 5 | **Claude Code** — the `claude` CLI |
 | 6 | **Configs** — Ghostty theme, `~/.claude` settings, shell PATH & aliases |
+| 7 | **Live status line** — model · context · 5h/weekly limits · branch · session · disk |
 
 > [!TIP]
 > Want to preview it first, changing nothing? Add `--dry-run`:

setup.sh

@@ -230,6 +230,9 @@ brew_formula node "Node.js"
 step "GitHub CLI (gh) — for PRs / the GitHub MCP"
 brew_formula gh "gh"
 
+step "jq — used by hooks and the status line"
+brew_formula jq "jq"
+
 # ─────────────────────────────────────────────────────────────────────────────
 # 4. Claude Code (official native installer, npm fallback) + persist PATH
 # ─────────────────────────────────────────────────────────────────────────────
@@ -286,6 +289,7 @@ read -r -d '' CLAUDE_SETTINGS <<'EOF' || true
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "includeCoAuthoredBy": true,
+  "statusLine": { "type": "command", "command": "ccstatusline", "padding": 0 },
   "permissions": {
     "allow": [
       "Bash(git status:*)",
@@ -320,7 +324,46 @@ else
 fi
 
 # ─────────────────────────────────────────────────────────────────────────────
-# 7. Shell aliases (optional)
+# 7. Status line — model, context, 5h/weekly limits, branch, session, disk
+# ─────────────────────────────────────────────────────────────────────────────
+step "Status line (cost / rate-limits / branch)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SL_ASSETS="$SCRIPT_DIR/assets/statusline"
+if [ -d "$SL_ASSETS" ]; then
+  # ccstatusline (the rich multi-line display the settings.json points to)
+  if command -v ccstatusline >/dev/null 2>&1; then
+    ok "ccstatusline already installed"
+  else
+    run "npm install -g ccstatusline" \
+      || warn "ccstatusline not installed (needs npm) — the status line stays blank until it is"
+  fi
+  # its config, only if you don't already have one
+  if [ -f "$HOME/.config/ccstatusline/settings.json" ]; then
+    skip "ccstatusline config exists — not overwriting"
+  elif $DRY_RUN; then
+    skip "[dry-run] write ~/.config/ccstatusline/settings.json"
+  else
+    mkdir -p "$HOME/.config/ccstatusline"
+    cp "$SL_ASSETS/ccstatusline-settings.json" "$HOME/.config/ccstatusline/settings.json"
+    ok "wrote ~/.config/ccstatusline/settings.json"
+  fi
+  # also drop the no-Node alternative (handy if you'd rather not use ccstatusline)
+  if [ -f "$HOME/.claude/statusline.sh" ]; then
+    # shellcheck disable=SC2088  # tilde is displayed text, not a path to expand
+    skip "~/.claude/statusline.sh exists — not overwriting"
+  elif $DRY_RUN; then
+    skip "[dry-run] write ~/.claude/statusline.sh"
+  else
+    cp "$SL_ASSETS/statusline.sh" "$HOME/.claude/statusline.sh"
+    chmod +x "$HOME/.claude/statusline.sh"
+    ok "wrote ~/.claude/statusline.sh (alternative)"
+  fi
+else
+  skip "status-line assets not found (run setup.sh from the repo) — skipping"
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 8. Shell aliases (optional)
 # ─────────────────────────────────────────────────────────────────────────────
 if $ADD_SHELL_ALIASES; then
   step "zsh aliases (~/.zshrc)"