statusline

Coral Statusline

Manage the coral HUD statusline for Claude Code.

Commands

Config directory: CONFIG_DIR = the Claude config dir reported in the SessionStart context (already resolved, absolute — it honors CLAUDE_CONFIG_DIR). Use it for every CONFIG_DIR/... path below, consistently across all steps. ~/.codex/auth.json is Codex's own directory and is NOT affected.

install

1. Check if CONFIG_DIR/hud/coral-hud.mjs already exists:
   • If exists and content matches coral-hud.mjs in this skill directory: inform user "HUD is already up to date", skip to step 6
   • If exists with different content: inform user "Updating HUD script to latest version", proceed
   • If not exists: proceed
2. Read coral-hud.mjs from this skill directory and write it to CONFIG_DIR/hud/coral-hud.mjs (create CONFIG_DIR/hud/ directory if needed)
3. Read CONFIG_DIR/settings.json (create if absent)
4. If statusLine already exists and is NOT coral's, ask the user before overwriting
5. Set statusLine to:

   {
     "statusLine": {
       "type": "command",
       "command": "node CONFIG_DIR/hud/coral-hud.mjs"
     }
   }
   

   Expand CONFIG_DIR to its absolute path (and ~ to the real home directory).
6. Check if ~/.codex/auth.json exists (Codex's own dir — the literal ~/.codex, NOT under CONFIG_DIR):
   • If yes, ask the user: "Codex login detected. Display Codex usage in statusline?"
     • yes → create CONFIG_DIR/hud/.coral-codex-enabled (empty file — the same CONFIG_DIR/hud as step 2; do not write this to ~/.claude when CONFIG_DIR differs)
     • no → delete CONFIG_DIR/hud/.coral-codex-enabled if it exists
   • If no auth.json, skip silently (do not create or delete any Codex files)
7. Confirm installation to the user

uninstall

1. Read CONFIG_DIR/settings.json
2. Remove the statusLine key
3. Delete the following files if they exist:
   • CONFIG_DIR/hud/coral-hud.mjs
   • CONFIG_DIR/hud/.coral-cache.json
   • CONFIG_DIR/hud/.coral-codex-enabled
4. Confirm removal to the user

HUD Script

The HUD script source is coral-hud.mjs in this directory. The install command reads this file and writes it to CONFIG_DIR/hud/coral-hud.mjs.

Notes

• CONFIG_DIR is the Claude config dir from the SessionStart context (see Config directory above); each config dir keeps its own HUD install and its own Codex opt-in flag
• If re-running install, overwrite the existing script (this updates the HUD to the latest version)
• Claude rate limits are fetched from api.anthropic.com/api/oauth/usage using OAuth credentials
• Enterprise/extra-usage plans have no 5h/weekly windows; instead the usage API returns extra_usage (a monthly dollar cap), shown in the limits slot as mo: <pct> ($used/$limit)
• Codex rate limits and spark limits are fetched from chatgpt.com/backend-api/wham/usage (GET, no token cost); requires Codex login (~/.codex/auth.json)
• Two-line layout: Line 1 (Claude) shows model, limits, ctx, session, and last active skill; Line 2 (Codex) shows codex model, codex limits, and spark limits
• Skill detection reads last 500KB of transcript_path JSONL (tail-read for performance), finds last Skill or proxy_Skill tool_use block
• Both fetches run in parallel
• Claude API results are cached for 180 seconds on success, 30 seconds on error. HTTP 429 responses trigger exponential backoff from 2 minutes up to 10 minutes.
• On error, the HUD preserves last-known-good rate-limit data until the error cache expires. The error indicator is shown only when no stale data exists.
• Error indicators are explicit: throttled: refreshes in Xm for HTTP 429, re-login required for explicit 401/403 auth failures, and API unavailable for other fetch/refresh failures.
• Missing or unsupported credentials stay silent; re-login required appears only for observable auth failures.
• The session slot combines spend and duration when available, for example $0.43 47m.
• Codex opt-in is controlled by CONFIG_DIR/hud/.coral-codex-enabled flag file; managed during install
• If credentials are unavailable (e.g., API key users or Codex not installed), the respective rate limit section is silently omitted