agentleFS
okanerturanokanerturan/claude-statusblocks/AGENTS.md

claude-statusblocks

AGENTS.md1 starsChanged 8 months agoMITView on GitHub

Claude-statusblocks is an opinionated, block-based status line for Claude Code. It reads JSON session data from stdin (piped by Claude Code's statusLine.command setting) and renders multi-block terminal output with ANSI colors, box-drawing characters, and adaptive row wrapping. Data flow: Claude Code pipes JSON (StatusLineData) to stdin → src/index.ts parses it, loads config, detects terminal width → src/layout.ts renders segments into boxified blocks with flexbox-like row wrapping → stdout. Terminal width detection (src/index.ts): Claude Code doesn't pass terminal width to status…

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. okturan/claude-statusblocks★ 1100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All ANSI color handling goes through src/colors.ts — use color(), c.* constants, visibleLength(), padRight(), and truncate() for ANSI-aware …

    line 46

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Claude-statusblocks is an opinionated, block-based status line for Claude Code. It reads JSON session data from stdin (piped by Claude Code's statusLine.command setting) and renders multi-block terminal output with ANSI colors, box-drawing characters, and adaptive row wrapping.

Commands

  • npm run build — compile TypeScript (tsc) to dist/ (prebuild wipes dist/ first so deleted sources can't linger as stale artifacts and get published/installed)
  • npm run dev — watch mode (tsc --watch)
  • npm run preview — render mock data at multiple widths (node dist/cli.js preview)
  • claude-statusblocks init — writes statusLine config into ~/.claude/settings.json
  • claude-statusblocks preview — renders at 120/80/50 column widths with mock data
  • npm test — run vitest test suite (co-located .test.ts files)

Architecture

Data flow: Claude Code pipes JSON (StatusLineData) to stdin → src/index.ts parses it, loads config, detects terminal width → src/layout.ts renders segments into boxified blocks with flexbox-like row wrapping → stdout.

Terminal width detection (src/index.ts): Claude Code doesn't pass terminal width to status line commands (known issue #22115). Detection cascade: process.stderr.columns → COLUMNS env var → per-session file cache → (non-Windows only) walk parent process tree via ps to find TTY, then stty size on that TTY → tput cols → fallback 120. The spawn-based result is cached (15s TTL, keyed by session_id) via src/cache.ts so repeated renders don't each pay two subprocess spawns. On Windows the Unix commands are skipped entirely. The detected width has a 44-char reserve subtracted for Claude Code's Ink notification panel on the right side.

Cross-process caching (src/cache.ts): every render is a fresh node process, so module-level caches don't survive between renders. Short-TTL JSON files in a per-user tmp dir ($TMPDIR/claude-statusblocks-<uid>/) do. Used by width detection and the git segment. All cache operations are best-effort; values loaded from cache are re-validated/sanitized before use.

Segments (src/segments/) are the core rendering units. Each implements the Segment interface (id, priority, enabled(), render()). Available segments:

  • context (priority 10) — context window usage bar with token counts
  • usage (priority 15) — rate limit utilization: remote usage limits when the background-fetched cache is warm, falling back to the rate_limits field in statusline JSON (requires Claude Code ≥2.1.80). Model-scoped weekly buckets (e.g. Fable) count only while the session's model matches (highlighted). Both weekly buckets gate a Fable session (a user was locked out by the all-models reset while Fable sat at 3%), so neither figure may ever be hidden — but the card stays TWO lines (user's explicit preference; three rows were rejected). Limits sharing a reset window are paired onto one line: the one closer to its cap leads (bar, percent, label), the other trails as a dim label pct annotation, e.g. 100% · ↻ 20h · 7d · Fable 3%. A session briefly running past 100% of the all-models bucket is Claude Code's usage-limit grace zone, not evidence the buckets are independent. The 5h row draws only when the server or stdin rate_limits.five_hour reports one (Max 20x gets five_hour: null and no session limit, so its card is the weekly line alone; a placeholder 5h row and a weekly pace row were both tried and rejected).
  • promo (priority 20) — rate promotion status with peak/off-peak countdown
  • model (priority 30) — model name, tilde-shortened directory, effort, duration, version. Effort (src/effort.ts) prefers the payload's effort.level (sent by recent Claude Code; it is the post-override truth, including ultracode which forces xhigh and ignores modelSettings, and /effort ultracode which the transcript parser maps to xhigh). Transcript/env/settings heuristics are only the fallback for older Claude Code.
  • git (priority 40) — branch name, staged/modified counts, lines added/removed

Layout (src/layout.ts): Uses exhaustive bin-packing to assign blocks to rows optimally. Blocks can be freely reordered across rows (not order-preserving) — within each row, blocks keep their original segment order. Rows are sorted by width ascending (pyramid: narrowest on top, widest on bottom). Row 1 gets 5 extra chars of right margin for Claude Code's notification panel. The algorithm tries all possible assignments (at most ~4400 for 5 blocks) and picks: fewest rows first, then smallest widest row. Within each row, shorter boxes are height-padded with blank bordered rows (required because Claude Code's Ink renderer strips leading whitespace, breaking alignment when boxes have different heights). Priority numbers are only used as a last resort for dropping segments that don't fit even alone.

Campaigns (src/campaigns/) track Anthropic promotional rate periods. data.ts holds campaign definitions (dates, peak hours, multipliers). engine.ts evaluates current time against campaigns using Intl.DateTimeFormat with formatToParts for precise timezone-aware peak detection. Returns state (active-boosted, active-normal, weekend, upcoming) with countdown and progress.

Usage data (src/remote-usage.ts, src/remote-usage-fetch.ts, src/credentials.ts): two tiers. Preferred: remote usage limits from the undocumented OAuth usage endpoint (api.anthropic.com/api/oauth/usage) — the same source as claude.ai's Usage page and Claude Code's /usage screen. This is the only source that carries model-scoped weekly limits (e.g. a separate Fable bucket); the statusline JSON does not include them. normalizeLimits() accepts ONLY the raw server shape and is kind-guarded: known generic kinds (session→5h, weekly_all→7d via the shared KIND_LABELS) can never be relabeled or flipped scoped by future server fields; model scopes keep a full-name lowercase match key (and server id when populated) separate from the 12-char display label; surface scopes are marked but never rendered (the statusline is not that surface). Cache reads go through a separate validateLimits() for the normalized shape — the two shapes are never sniffed apart by field presence. Cached limits are served for up to an hour (DISPLAY_TTL): stale remote data beats the stdin fallback, which is equally stale and lacks the Fable bucket and any lapsed 5h window — a 5-minute TTL made idle renders collapse to a misleading one-line card. Windows whose reset has passed render as 0%. The render path NEVER touches the network and reads the cache file at most once per process (memoized; resetRemoteUsageMemo() is the test hook). maybeRefreshRemoteUsage() (called from index.ts after output, and only when the usage segment is in the active segment list) spawns a detached child running remote-usage-fetch.js, throttled by an atomic O_EXCL marker (acquireMarker in src/cache.ts) so concurrent renders can't double-spawn. The child resolves the OAuth token from $CLAUDE_CONFIG_DIR/.credentials.json (or ~/.claude), then the macOS Keychain via security; every failure is silent. Fallback: the rate_limits field (5-hour and 7-day buckets, clamped) from the statusline JSON (Claude Code ≥2.1.80) — also used whenever the model-scope filter leaves nothing visible, so valid 5h/7d data is never discarded, and enabled() mirrors render() so a width-0 usage box can never be drawn. Kill switches are equivalent: "remoteUsage": false in config is bridged onto CLAUDE_STATUSBLOCKS_NO_REMOTE at process start, and both stop refreshes AND cache reads (tests set the env var for subprocess runs; preview sets it internally so mock data can't be replaced by the user's real cache). writeCache is atomic (temp file + rename) since the remote-usage file has an independent writer and per-render readers. CLAUDE_STATUSBLOCKS_CACHE_DIR overrides the cache dir so tests never touch (or read!) the developer's real cache.

Config (src/config.ts) loads segment order from ~/.claude-statusblocks.json, with CLAUDE_STATUSBLOCKS_SEGMENTS as an environment override.

CLI (src/cli.ts) handles subcommands (init, update, preview, help). When no TTY is detected (piped input), delegates to src/index.ts. The init command copies dist files to ~/.claude/statusblocks/ and sets the statusLine command to node "<home>/.claude/statusblocks/index.js" for fast direct invocation (bypasses npx overhead), plus refreshInterval: 30 — Claude Code only re-renders on events otherwise, so an idle card would sit on pre-refresh numbers. update adds refreshInterval to our own installs when absent and never overrides a user-set value. The command string MUST stay quoted with forward slashes — it has to parse identically in sh, Git Bash, cmd, and PowerShell (Windows homes contain backslashes and often spaces). init creates ~/.claude/settings.json if missing but aborts on unparseable JSON. The update command refreshes the installed files and migrates any stale command form (old npx invocation or pre-0.5 unquoted paths). Installs go through installFiles(): copy dist (excluding *.test.*, mirroring the npm tarball), sweep files the incoming version no longer ships (copy-then-sweep, never clean-then-copy — a concurrent render must not see an empty dir; leftover mixed-version files are live ESM code and how imports break), then stamp the installed version into .version. update (but NOT init, which is an explicit "install THIS version") has a downgrade guard: it refuses when the .version stamp is strictly newer than the running package, unless --force is passed. This matters because update is the automated path — postinstall.cjs delegates to it, and the daily auto-update runs it — and a stale npx cache once served an old package that clobbered a newer local install. Version comparison lives in src/version.ts (isValidVersion is also the injection gate for shell interpolation).

Key Patterns

  • All ANSI color handling goes through src/colors.ts — use color(), c.* constants, visibleLength(), padRight(), and truncate() for ANSI-aware string operations.
  • Segments return raw lines (no box chrome); boxing is applied by layout.ts.
  • Box titles are rendered in the top border: ╭─ title ──────╮.
  • The Block type's width is the visible (ANSI-stripped) width, not byte length.
  • The git segment caches results for 5 seconds via the cross-process file cache in src/cache.ts (a module-level cache alone would never hit — each render is a new process). Detached HEAD renders as @<short-sha>.
  • The daily background self-update (maybeAutoUpdate in src/index.ts) spawns the installed update-check.js detached, which resolves the registry's latest version over HTTPS and runs npx -y claude-statusblocks@<exact-version> update only when it's strictly newer than the .version stamp. Never spawn npx pkg@latest directly: npx serves stale cached resolutions of latest, which once downgraded a newer local install. The registry response is validated with isValidVersion before shell interpolation. Disabled by CLAUDE_STATUSBLOCKS_NO_UPDATE=1 — tests set this so runs never mutate the developer's real ~/.claude/statusblocks/.
  • Code must stay Windows-safe: no Unix-only subprocesses outside process.platform !== 'win32' guards, no unquoted paths in generated commands, and all detached spawns go through spawnDetached() in src/spawn.ts (sole owner of the detached/windowsHide/unref contract). CI runs the suite on ubuntu/macos/windows.
  • ESM-only ("type": "module" in package.json) — all local imports use .js extensions. Do NOT use require() — it will crash silently in production.
  • Claude Code's Ink renderer uses wrap="truncate" (hardcoded). Lines exceeding available width get truncated with …. Design all output to fit within termWidth - 44 chars.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.