claude-statusline

🇬🇧 English · 🇷🇺 Русский

Smart status line for Claude Code — model, cost, context, usage limits, VPS health — all at a glance while you code. Pure bash + jq, no Node.js. Featured on Habr (9.3K reads) — describes the design and the auto-focus VPS feature.

Above: live capture of a 100-hour Opus session — 8320 lines of code written, $40 of API cost saved by the Max subscription, RAM/disk health of three VPS at a glance. From the Habr article.

What every segment tells you

Architecture

The design is one decision: decouple slow SSH polling from instant statusline rendering through a /tmp cache. The statusline runs on every Claude Code prompt — it cannot afford to block on a 5-second SSH timeout.

Installation

Open Claude Code (claude in your terminal) and say:

Clone https://github.com/CreatmanCEO/claude-statusline and install via install.sh

Or run directly:

git clone https://github.com/CreatmanCEO/claude-statusline.git ~/claude-statusline && bash ~/claude-statusline/install.sh

Restart Claude Code. The status line appears automatically.

Windows: Run from inside Claude Code, not from PowerShell/cmd directly (.sh files need bash). See Troubleshooting below.

Install options

bash ~/claude-statusline/install.sh            # basic — model, cost, context, lines, duration, git
bash ~/claude-statusline/install.sh --vps      # + VPS monitoring
bash ~/claude-statusline/install.sh --ru       # Russian labels (стр, контекст, мин)
bash ~/claude-statusline/install.sh --tmux     # tmux integration (Prefix+y popup)
bash ~/claude-statusline/install.sh --minimal  # just model + context
bash ~/claude-statusline/install.sh --uninstall

VPS Monitoring

For developers working with remote servers via Bash SSH or MCP SSH — see VPS health without switching context.

Step 1 — Add servers

Tell Claude Code:

Open ~/.claude/statusline.conf and add:

SHOW_VPS=remote
VPS_SERVERS=(
  "prod|1.2.3.4|22|root|~/.ssh/my_key"
  "staging|5.6.7.8|22|root|~/.ssh/my_key"
)

Step 2 — Start the poller

Run ~/claude-statusline/vps-poller.sh start

The poller runs in background, polling servers every 30 s via SSH. Logs to /tmp/vps-poller.log.

Step 3 — Auto-focus active server

The statusline automatically detects which VPS you are working on by parsing the Claude Code transcript for ssh / scp / sftp commands and matching IPs against your VPS_SERVERS. Active VPS gets the ▶ marker with expanded RAM/Disk metrics:

main●  ▶ new●(R:58% D:68%)  sec●

This works with both Bash SSH (ssh [email protected]) and MCP SSH (when MCP servers reuse the same IPs). For MCP-only setups where IPs are not visible in the transcript, add an explicit mapping:

VPS_FOCUS=auto
VPS_MCP_MAP=(
  "prod|my-mcp-prod"
  "staging|my-mcp-staging"
)

Status glyphs: 🟢 ● OK · 🟠 ◉ WARN (>80%) · 🔴 ✗ DOWN · 🟣 ↻ BOOT · ⚪ ▽ STALE (cache > 120 s)

Usage Limits (H/W)

H:82% 3h12m shows remaining 5-hour quota; W:94% shows weekly quota. For Max / Pro / Team subscribers. Color-coded: green > 50%, yellow 20–50%, red < 20%.

Reads OAuth token from ~/.claude/.credentials.json after claude login. Cached for 2 minutes.

Inspired by @AndyShaman/claude-statusline — thanks for documenting the OAuth API. If you only need quota tracking without VPS monitoring, his version is leaner.

Configuration

All settings in ~/.claude/statusline.conf. Changes apply on the next Claude Code response — no restart needed.

Full list with defaults — see statusline.conf.

Useful Claude Code commands

• /cost — session cost and tokens
• /context — detailed context window breakdown
• /compact — compress context (when status line turns red)
• /model sonnet — switch model

Platforms

Troubleshooting

Status line disappeared after install (Windows)

.sh files do not execute from cmd / PowerShell. Tell Claude Code:

In ~/.claude/settings.json set statusLine.command to: bash /c/Users/YOUR_NAME/.claude/statusline.sh

H/W limits not showing

1. Run claude login if not authenticated
2. Check that ~/.claude/.credentials.json exists
3. If not — limits are silently skipped, the rest of the statusline keeps working

VPS shows DOWN but the server is fine

• SSH timeout (5 s by default) too aggressive on slow networks → raise VPS_SSH_TIMEOUT
• SSH key not loaded → ssh-add ~/.ssh/my_key
• Firewall / ufw blocking outbound from your machine → check /tmp/vps-poller.log

Auto-focus picks the wrong VPS

• Transcript parser only scans the last 20 KB. After many tool calls, the relevant ssh invocation can scroll out → manually pin via VPS_FOCUS=<server-name> until the next session
• For MCP-only SSH where IPs are hidden, configure VPS_MCP_MAP

Limitations

This is a personal-tool, not a managed service. Honest constraints:

• Transcript parsing is heuristic. The auto-focus reads the last 20 KB of the Claude Code transcript JSONL. In long sessions with heavy MCP traffic, the relevant ssh invocation can scroll out of that window. Workaround: pin manually via VPS_FOCUS=<server-name>.
• OS credential storage assumption. Usage limits are read from ~/.claude/.credentials.json. If Anthropic changes the credential storage format, limits will silently fail to render until the script is updated.
• Bash + jq required. The script will not run on systems without bash (4+) and jq. PowerShell / fish / dash are not supported. WSL is fine.
• SSH timeout is global. A single slow VPS does not slow down the statusline (poller is async), but a uniformly slow network can cause all VPS to flicker DOWN/UP. Raise VPS_SSH_TIMEOUT in this case.
• No metric history. Statusline only shows current snapshot. For trend graphs use Grafana, Netdata, or Prometheus — this tool answers "is anything on fire right now", not "how was load yesterday".
• Windows tmux integration is unsupported. tmux on Windows is fragile in general; the --tmux flag is Linux/macOS-only.
• Daemon is best-effort. vps-poller.sh start runs as a detached process — it does not register a systemd unit. If the host reboots, restart the poller manually (or wrap it in your own systemctl --user unit).

Related

• Claude Code Anti-Regression Setup — sister repo, same author. Complementary purpose: this statusline tells you where context is now; the anti-regression setup keeps Claude from corrupting it.
• ai-context-hierarchy — sister repo. Three-level context system that pairs naturally with the auto-focus VPS feature here (Level 0 lists your servers, statusline tells you which one is hot).
• @AndyShaman/claude-statusline — original inspiration for the H/W limits feature; leaner if you only need quota tracking.
• awesome-claude-code — curated skills, hooks, agents.

Companion article

• Habr (RU) — Как я собрал statusline для Claude Code с мониторингом VPS за одну сессию — 9.3K reads. Covers the cache decoupling, auto-focus heuristic, and cost-calculation logic.

Contributing

PRs welcome — see CONTRIBUTING.md. Current priorities: per-distribution package targets (apt, brew, dnf), additional language locales, alternative VPS metric backends (Netdata API, Prometheus push, MCP system_* tools), Fish/Zsh shells.

Author

Nick Podolyak — Python developer and digital architect at CREATMAN

• GitHub: @CreatmanCEO
• Habr: creatman
• dev.to: @creatman

License

MIT · Nick Podolyak