@hasna/statusline 0.0.7 → 0.0.9

package/README.md

@@ -5,7 +5,7 @@ on and off — machine name, project + branch, model, context remaining, session
 and more — rendered as one or more rows in your agent's status bar.
 
 ```
-apple03 · statusline (main) · 12h · 1.2k · fable 5 [1m] · 90% left · $0.04
+apple03 · statusline (main) · 12h · 1.2k · fable 5 [1m] · 90% left · 95% cached · $0.04
 ```
 
 Built with [Bun](https://bun.sh) + TypeScript. The CLI renderer is dependency-light; the optional MCP server uses the Model Context Protocol SDK. Apache-2.0.
@@ -22,7 +22,7 @@ That's it — Claude Code picks it up on the next status refresh (no restart nee
 ## Segments
 
 `statusline list` shows a compact, enabled-first summary of your segments (use
-`statusline list --all` for every row). The table below is the full catalog — all 26
+`statusline list --all` for every row). The table below is the full catalog — all 31
 segment ids from `src/segments/index.ts`.
 
 `renderLine` walks your configured segment order, renders each one, and **drops**
@@ -36,7 +36,9 @@ anything that returns `null` or throws. A failed segment never breaks the host U
 | `git-branch` | off | Current Git branch | `git branch --show-current` in `cwd` | outside git or detached | `main` |
 | `commit-age` | on | Time since last commit (compact) | `git log -1` epoch vs now | no commits / not a repo | `12h` |
 | `loc` | on | Lines of code tracked by Git (compact) | `git ls-files` + `wc -l` in repo root | outside git or zero lines | `1.2k` |
-| `current-dir` | off | Current working directory (basename) | `StatusContext.cwd` | never (always renders basename) | `open-statusline` |
+| `disk-free` | off | Free space on the volume holding the working directory | one `fs.statfsSync` syscall on `StatusContext.cwd` — no subprocess, no polling, no cache | the volume cannot be read (missing cwd, unsupported filesystem) | `disk 24.1G` · `disk 8G low` |
+| `current-dir` | off | Current working directory (basename) | `StatusContext.cwd` | never (always renders basename) | `statusline` |
+| `cwd` | off | Current working directory (full path) | `StatusContext.cwd`, home directory abbreviated to `~`, head elided past 40 chars | no cwd in the payload | `~/work/statusline` |
 | `model` | off | Current model name (no context tag) | `StatusContext.model.id` via friendly formatter | no model id | `fable 5` |
 | `model-context` | on | Model name with context-size tag | same formatter, keeps `[tag]` suffix | no model id | `fable 5 [1m]` |
 | `model-with-reasoning` | off | Model name with its reasoning effort | lowercased `model.display_name` (or friendly id) + `effort.level`; falls back to `thinking.enabled` when on | no model | `fable (xhigh)` |
@@ -45,14 +47,15 @@ anything that returns `null` or throws. A failed segment never breaks the host U
 | `auth-email` | off | Account email this session is logged in as | the agent's own login record for this config dir, else the registry | no login recorded | `dev@example.com` |
 | `five-hour-limit` | off | Percentage of the 5-hour rate limit used | `rate_limits.five_hour.used_percentage` | host reports no limit data | `5h:42%` |
 | `seven-day-limit` | off | Percentage of the 7-day rate limit used | `rate_limits.seven_day.used_percentage` | host reports no limit data | `7d:12%` |
-| `usage-session` | off | Session (5-hour) usage **remaining** for this pane's own account | this process's `CLAUDE_CONFIG_DIR` account uuid → the accounts usage cache at `~/.hasna/accounts/cache/usage/<uuid>.json` (kept warm by `@hasna/accounts`; **no cloud call**) | never omitted — shows `5h —` when usage is unknown, missing, stale, or rate-limited | `5h 87%` |
-| `usage-weekly` | off | Weekly usage **remaining** for this pane's own account (the binding limit) | same local usage cache as `usage-session` | never omitted — shows `7d —` when usage is unavailable | `7d 92%` |
+| `usage-session` | off | Session (5-hour) usage **remaining** for this pane's own account | this process's `CLAUDE_CONFIG_DIR` account uuid → the accounts usage cache at `~/.hasna/accounts/cache/usage/<uuid>.json` (kept warm by `@hasna/accounts`; **no cloud call**) | not on the Anthropic API (custom endpoint); on Anthropic, shows `5h —` when usage is unknown, missing, stale, or rate-limited | `5h 87%` |
+| `usage-weekly` | off | Weekly usage **remaining** for this pane's own account (the binding limit) | same local usage cache as `usage-session` | not on the Anthropic API (custom endpoint); on Anthropic, shows `7d —` when usage is unavailable | `7d 92%` |
 | `thread-title` | off | Thread title set with `/rename` | `session_name` | thread not renamed | `ship it` |
-| `context-used` | off | Percentage of context window used | session transcript JSONL (`contextUsage`) | transcript missing/unreadable | `10%` |
+| `context-used` | off | Percentage of context window used | session transcript JSONL (`contextUsage`) | transcript missing/unreadable | `ctx 10%` |
 | `context-remaining` | on | Percentage of context window remaining | transcript via `contextUsage` | transcript missing/unreadable | `90% left` |
 | `used-tokens` | off | Total tokens in the context window | transcript usage block (input + output) | transcript missing/unreadable | `102k tok` |
+| `cache-rate` | on | Percentage of input tokens served from cache | transcript usage block (`cache_read_input_tokens` / total input-side); Codex rollout / OpenCode DB for those providers | transcript missing/unreadable or zero input-side tokens | `87% cached` |
 | `cost` | on | Session cost in USD | `StatusContext.cost.totalCostUsd` | cost is zero or missing | `$1,234.50` |
-| `duration` | off | Session wall-clock duration | `StatusContext.cost.totalDurationMs` | duration is zero or missing | `1h30m` |
+| `duration` | off | Session wall-clock duration | `StatusContext.cost.totalDurationMs` | duration is zero or missing | `1h 30m` |
 | `lines-changed` | off | Lines added/removed this session | `cost.totalLinesAdded/Removed` | both zero | `+142/-18` |
 | `output-style` | off | Active output style | `StatusContext.outputStyle` | style is `default` or missing | `concise` |
 | `agent-version` | off | Host agent version | `StatusContext.version` | version missing | `v2.1.39` |
@@ -61,14 +64,23 @@ anything that returns `null` or throws. A failed segment never breaks the host U
 
 ### Context segments and transcripts
 
-Segments that report context usage (`context-used`, `context-remaining`, `used-tokens`)
-read the session transcript path from the provider payload. `contextUsage` scans the
-JSONL for the last assistant entry with a `usage` block and sums
-`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. Window size is
-**1,000,000** when the model id contains `[1m]`, otherwise **200,000**.
+Segments that report context usage (`context-used`, `context-remaining`, `used-tokens`,
+`cache-rate`) read the session transcript path from the provider payload.
+`contextUsage` scans the JSONL for the last assistant entry with a `usage` block and
+sums `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. Window
+size is **1,000,000** when the model id contains `[1m]`, otherwise **200,000**.
+
+`cache-rate` is `cache_read_input_tokens / (input_tokens + cache_creation_input_tokens
++ cache_read_input_tokens)` from the same last usage block, rendered as a rounded
+percentage (`87% cached`). It renders `0% cached` during the pre-warm phase of a
+session (a nonzero divisor with no cache hits yet) — the same render-zero-not-drop
+convention as `five-hour-limit` — and is omitted only when the transcript is
+missing/unreadable or the divisor is zero. For Codex and OpenCode it reads those
+providers' own usage channels instead (see Providers below).
 
 With the test fixture transcript (100k input-side tokens on a 1m window), expect
-`context-used` → `10%`, `context-remaining` → `90% left`, `used-tokens` → `102k tok`.
+`context-used` → `ctx 10%`, `context-remaining` → `90% left`, `used-tokens` → `102k tok`,
+`cache-rate` → `95% cached`.
 
 ### Which account am I? (`auth-profile`)
 
@@ -107,7 +119,18 @@ registry knows about always wins.
 ### Colours
 
 Segments may declare a colour, applied by `renderLine` when colours are on
-(the default). The rate-limit segments escalate from yellow to red at 80%.
+(the default). Only standard 16-colour ANSI codes are used, so the palette
+works in any modern terminal on both light and dark backgrounds, and
+separators are never coloured.
+
+- the context gauges go green below 50%, yellow from 50% to 79%, and red at
+  80% and above (the same shape the rate-limit segments use);
+- the rate-limit segments escalate from yellow to red at 80%;
+- `cwd` uses a calm blue accent and elides the head of long paths;
+- `disk-free` stays dim while the volume has headroom, turns yellow below 20%
+  free and red below 10%, and appends a `low` marker so the warning survives
+  `NO_COLOR`;
+- model, cost and duration render dim, so they never compete with a warning.
 
 ```bash
 statusline colors off      # or set "colors": false in the config
@@ -121,7 +144,7 @@ statusline colors off      # or set "colors": false in the config
 enabled segments first, capped rows, and hints for the detail paths:
 
 ```
-Segments: 7 enabled / 26 total (showing 12 of 26)
+Segments: 8 enabled / 30 total (showing 12 of 30)
 state  default  id
 on     yes      machine
 on     yes      project
@@ -129,6 +152,7 @@ on     yes      commit-age
 on     yes      loc
 on     yes      model-context
 on     yes      context-remaining
+on     yes      cache-rate
 on     yes      cost
 off    no       project-name
 off    no       git-branch
@@ -181,7 +205,7 @@ Config lives at `~/.config/statusline/config.json` (override with `$STATUSLINE_C
 {
   "separator": " · ",
   "colors": true,
-  "segments": ["machine", "project", "commit-age", "loc", "model-context", "context-remaining", "cost"]
+  "segments": ["machine", "project", "commit-age", "loc", "model-context", "context-remaining", "cache-rate", "cost"]
 }
 ```
 
@@ -211,6 +235,14 @@ The `newline` segment starts a new row; empty rows are removed. Segments
 that need more than the payload offers (e.g. `context-remaining`) read the session
 transcript to compute it. A segment failure is never fatal — it's simply omitted.
 
+There is no long-running statusline process, so nothing polls. `disk-free` reads
+free space once per render with `fs.statfsSync` (about half a microsecond), the
+same way the host re-runs the command for each refresh; shelling out to `df`
+would fork a process every time and cost roughly a millisecond. That one reading
+is shared by the segment's text and its colour, so they cannot disagree. The
+segment adds under 2 µs to an in-process render, which is below the noise of the
+~17 ms process invocation.
+
 ## SDK
 
 The package root is a side-effect-free SDK surface:
@@ -233,7 +265,9 @@ saveConfig(next);
 Useful exports include `parseClaudeInput`, `renderLine`, `renderStatusline`, `segments`,
 `getSegment`, `listSegments`, `defaultConfig`, `loadConfig`, `saveConfig`, `configPath`,
 `previewStatusline`, `enableSegments`, `disableSegments`, `orderSegments`,
-`setSeparator`, `setColors`, `installClaude`, and the account, context, format, and Git helpers.
+`setSeparator`, `setColors`, `installClaude`, the cache-rate channel
+(`cacheRate`, `codexCacheRate`, `latestCodexSessionPath`, `opencodeCacheRate`), and the
+account, context, format, and Git helpers.
 
 ## MCP
 
@@ -306,30 +340,63 @@ on every status refresh — **no restart needed**.
 
 Every field is optional — partial or empty payloads still produce a usable context.
 
-### Codewith (not implemented)
+### Codex CLI (implemented, env-selected)
+
+Codex ships its own built-in segment picker and has no external `statusLine` command
+hook, so there is no `statusline install codex` — the renderer is invoked standalone
+with the provider selected by the environment:
+
+```bash
+STATUSLINE_PROVIDER=codex statusline render
+```
 
-`statusline install` only accepts `claude` today. Running
-`statusline install codewith` errors with *unsupported target* (`src/cli.ts`).
+`cache-rate` then reads the newest Codex session rollout
+(`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`, newest file mtime): the LAST
+`event_msg` line whose `payload.type` is `token_count`, whose
+`payload.info.total_token_usage` holds **cumulative session totals**
+(`input_tokens`, `cached_input_tokens`, `cache_write_input_tokens`, …). The rate is
+`cached_input_tokens / (input_tokens + cached_input_tokens + cache_write_input_tokens)`,
+clamped to `[0, 1]`. Exposed on the SDK as `latestCodexSessionPath()` /
+`codexCacheRate(path?)`. Caveat: the semantics of Codex's `input_tokens` relative to
+`cached_input_tokens` (uncached-only vs total) are inferred from measured samples —
+the clamp and the fixture tests lock the adapter to the documented shape.
+
+### OpenCode (implemented, env-selected)
+
+OpenCode has no statusline/footer hook in its config as of v1.3.x, so the same
+env-selector applies:
+
+```bash
+STATUSLINE_PROVIDER=opencode statusline render
+```
 
-The renderer is provider-agnostic: a future `parseCodewithInput` would map Codewith's
-status payload into `StatusContext` (`src/providers/types.ts`) and reuse the same
-segment registry. No install wiring exists yet (tracked in STA-00003).
+`cache-rate` reads `~/.local/share/opencode/opencode.db` (SQLite) with a read-only
+`Bun.sqlite` query — zero new dependencies, and a WAL lock mid-write degrades to
+omitting the segment, never a crash. It takes the newest session row's
+`tokens_cache_read / (tokens_input + tokens_cache_read + tokens_cache_write)` from the
+`session` table, falling back to `session_v2` when `session` has no populated row (both
+schemas carry the columns). SDK surface: `opencodeCacheRate({ dbPath?, sessionId? })`.
 
-### Cursor (not implemented)
+### Cursor (not implemented — no verifiable source)
 
-Same gap as Codewith — no `statusline install cursor` subcommand and no Cursor-specific
-parser. A future adapter would implement `parseCursorInput` → `StatusContext` and hook
-into Cursor's status bar the same way Claude does (tracked in STA-00004).
+No `statusline install cursor` and no adapter. Unlike Codex and OpenCode, Cursor has
+**no local per-turn token-usage record to read**: `~/.cursor/chats/*/store.db` holds
+only `blobs`/`meta` tables, and `~/.cursor/ai-tracking/ai-code-tracking.db` carries no
+per-turn usage. Token usage is only visible in Cursor's own UI/API, so per the honesty
+rule no adapter is fabricated. If Cursor later persists usage locally, an adapter slots
+in behind the same `cacheRate(ctx)` dispatch.
 
 ### Other agents
 
 | Agent | Status |
 |-------|--------|
-| OpenCode | ⏳ no statusline/footer hook in its config as of v1.3.x — the renderer is provider-agnostic (`src/providers/`), so an adapter slots in the moment one exists |
-| Codex CLI | Codex ships its own built-in segment picker; no external command hook |
+| Codex CLI | ✅ `STATUSLINE_PROVIDER=codex` — `cache-rate` from the newest session rollout |
+| OpenCode | ✅ `STATUSLINE_PROVIDER=opencode` — `cache-rate` from the sessions DB |
+| Cursor | ❌ no local per-turn token usage exists — no adapter (see above) |
+| Codewith | ⏳ no statusline/footer hook; a future `parseCodewithInput` would map its payload into `StatusContext` and reuse the registry (tracked in STA-00003) |
 
-Adding a provider means one small parser: agent payload → `StatusContext`
-(`src/providers/types.ts`). PRs welcome.
+Adding a provider means one small adapter: agent payload/source → `StatusContext`
+(`src/providers/types.ts`) or a `cacheRate(ctx)` data channel. PRs welcome.
 
 ## Development