{"id":50418767,"url":"https://github.com/developer0hye/minimal-claude-hud","last_synced_at":"2026-05-31T07:05:01.458Z","repository":{"id":361088459,"uuid":"1252929730","full_name":"developer0hye/minimal-claude-hud","owner":"developer0hye","description":"Minimal single-file Claude Code statusline: model name, context window usage, and 5h/weekly OAuth usage. Zero deps.","archived":false,"fork":false,"pushed_at":"2026-05-29T05:45:24.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T07:28:42.012Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developer0hye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T02:27:05.000Z","updated_at":"2026-05-29T05:45:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/developer0hye/minimal-claude-hud","commit_stats":null,"previous_names":["developer0hye/minimal-claude-hud"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/developer0hye/minimal-claude-hud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer0hye%2Fminimal-claude-hud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer0hye%2Fminimal-claude-hud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer0hye%2Fminimal-claude-hud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer0hye%2Fminimal-claude-hud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developer0hye","download_url":"https://codeload.github.com/developer0hye/minimal-claude-hud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developer0hye%2Fminimal-claude-hud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33722188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T07:05:00.614Z","updated_at":"2026-05-31T07:05:01.452Z","avatar_url":"https://github.com/developer0hye.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# minimal-claude-hud\n\nShows the **model name**, **context window usage**, **5-hour usage**, and **weekly usage** in the Claude Code global statusline.\n\n```\nOpus ctx:42% 5h:13%(1h15m) wk:3%(5d22h)\n```\n\n- `Opus` — the model currently in use\n- `ctx:NN%` — context window usage of the current conversation\n- `5h:NN%` / `wk:NN%` — 5-hour / weekly rate-limit usage from the OAuth usage API\n- ≥70%: yellow / ≥90%: red\n- Model name and context are read live from Claude Code's stdin JSON; 5h/wk are cached on a 1-minute cycle\n- Supports both macOS Keychain credentials and file-based credentials\n- Zero external dependencies — a single `.mjs` file\n\nDistilled from [yeachan-heo/oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode) (MIT): only the 5h/weekly display logic from `src/hud/usage-api.ts` + `src/hud/elements/limits.ts` was extracted. The model name and context usage come from the stdin JSON that Claude Code passes to the statusline script.\n\n---\n\n## Install (let Claude Code do it — recommended)\n\nSend the one line below in a Claude Code session. Claude will follow the \"Claude Code install steps\" section of this README and install it for you automatically.\n\n\u003e `Read https://github.com/developer0hye/minimal-claude-hud and follow the \"Claude Code install steps\" section of the README to install it.`\n\nWhen it finishes, restart Claude Code once (`/clear` or a new session). From the next session on, usage will appear in the statusline of every project.\n\n---\n\n## Claude Code install steps\n\nThis section lists the steps Claude Code follows. **A human can follow them directly too**, but letting Claude handle it takes care of OS differences, paths, and JSON merging for you.\n\n### Prerequisites\n- Node.js 18+ on your PATH (`node --version`)\n- Either `~/.claude/.credentials.json` exists (Windows/Linux), or the macOS Keychain has a `Claude Code-credentials` entry — this is created automatically once you have logged into Claude Code at least once.\n\n### 1. Download the script\n\nDownload this repo's `omc-limits-statusline.mjs` and save it to `~/.claude/omc-limits-statusline.mjs`.\n\n```bash\n# bash / zsh (macOS, Linux, Git Bash on Windows)\ncurl -fsSL https://raw.githubusercontent.com/developer0hye/minimal-claude-hud/main/omc-limits-statusline.mjs \\\n  -o \"$HOME/.claude/omc-limits-statusline.mjs\"\n```\n\n```powershell\n# PowerShell (Windows)\n$dest = Join-Path $env:USERPROFILE \".claude\\omc-limits-statusline.mjs\"\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/developer0hye/minimal-claude-hud/main/omc-limits-statusline.mjs\" -OutFile $dest\n```\n\n### 2. Check that the statusline works\n\nRun the script once to confirm it produces output (when the cache is empty, the first call hits the Anthropic API — about 1 second).\n\n```bash\n# bash\necho '{\"session_id\":\"test\",\"cwd\":\".\",\"model\":{\"display_name\":\"Opus\"},\"context_window\":{\"used_percentage\":42}}' | node \"$HOME/.claude/omc-limits-statusline.mjs\"\n```\n\n```powershell\n# PowerShell\n'{\"session_id\":\"test\",\"cwd\":\".\",\"model\":{\"display_name\":\"Opus\"},\"context_window\":{\"used_percentage\":42}}' | node (Join-Path $env:USERPROFILE \".claude\\omc-limits-statusline.mjs\")\n```\n\nExpected output (with ANSI escapes):\n```\n[36mOpus[0m [2mctx:[0m[32m42%[0m 5h:[32m13%[0m[2m(1h15m)[0m [2mwk:[0m[32m3%[0m[2m(5d22h)[0m\n```\n\nIf the output is empty:\n- Credentials could not be read → log into Claude Code once, then retry.\n- The API returned 429 → it retries automatically after 1 minute, showing the cached stale value in the meantime.\n\n### 3. Register `statusLine` in `~/.claude/settings.json` (merge)\n\n**Do not overwrite** your existing settings.json — preserve the existing keys and only add/replace the `statusLine` entry. Claude follows this JSON merge rule:\n\n- If `~/.claude/settings.json` does not exist, create it.\n- If it exists, parse it as JSON and set only this key:\n  ```jsonc\n  {\n    \"statusLine\": {\n      \"type\": \"command\",\n      \"command\": \"node \\\"\u003cHOME\u003e/.claude/omc-limits-statusline.mjs\\\"\",\n      \"padding\": 0\n    }\n  }\n  ```\n  Replace `\u003cHOME\u003e` with the absolute path to your home directory for your OS:\n  - Windows: `C:/Users/\u003cUSERNAME\u003e` (forward slashes), or expand `%USERPROFILE%` directly\n  - macOS / Linux: the value of `$HOME` (e.g. `/Users/yourname` or `/home/yourname`)\n- Leave all other keys (`enabledPlugins`, `effortLevel`, `autoUpdatesChannel`, `skipDangerousModePermissionPrompt`, hooks, permissions, etc.) **untouched.**\n\nA safe merge with Node (Claude can run this as-is):\n\n```bash\nnode -e '\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst os = require(\"os\");\nconst settingsPath = path.join(os.homedir(), \".claude\", \"settings.json\");\nconst scriptPath = path.join(os.homedir(), \".claude\", \"omc-limits-statusline.mjs\").replace(/\\\\/g, \"/\");\nlet s = {};\nif (fs.existsSync(settingsPath)) s = JSON.parse(fs.readFileSync(settingsPath, \"utf-8\"));\ns.statusLine = { type: \"command\", command: `node \"${scriptPath}\"`, padding: 0 };\nfs.writeFileSync(settingsPath, JSON.stringify(s, null, 2));\nconsole.log(\"statusLine registered:\", scriptPath);\n'\n```\n\n### 4. Wrap up\n\nAfter installing:\n- Restart Claude Code (`/clear` or a new session).\n- Success looks like `Opus ctx:NN% 5h:NN% wk:NN%` on the statusline row.\n- The first run may be slightly delayed by the Anthropic API call; it is cached for 1 minute afterward.\n\n---\n\n## Update\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/developer0hye/minimal-claude-hud/main/omc-limits-statusline.mjs \\\n  -o \"$HOME/.claude/omc-limits-statusline.mjs\"\n```\n\nJust re-download the script file. No need to touch settings.json.\n\n## Uninstall\n\nDelete the `statusLine` key from `~/.claude/settings.json` and remove the `~/.claude/omc-limits-statusline.mjs` file.\n\n## Troubleshooting\n\n| Symptom | Cause / fix |\n|---------|-------------|\n| Nothing shows on the statusline | 1) Check `node --version`. 2) Run `node ~/.claude/omc-limits-statusline.mjs` manually and inspect the output. 3) Restart Claude Code. |\n| Only `5h:0%` shows | The API likely did not return a response. `OMC_DEBUG` is disabled in this extract. Delete the cache file `~/.claude/cache/omc-limits-cache.json` and retry. |\n| Credentials not read on macOS | Check directly with `security find-generic-password -s \"Claude Code-credentials\" -w`. If empty, log back into Claude Code. |\n| Non-default config via `CLAUDE_CONFIG_DIR` | The script picks up the env var automatically. The Keychain service name is computed as `Claude Code-credentials-\u003csha256(CLAUDE_CONFIG_DIR)[:8]\u003e`. |\n\n## How it works (summary)\n\n1. On macOS, reads the OAuth access/refresh token via `security find-generic-password`; elsewhere from `~/.claude/.credentials.json`.\n2. If the access token is expired, refreshes it via `platform.claude.com/v1/oauth/token`.\n3. Calls `GET https://api.anthropic.com/api/oauth/usage` (header `anthropic-beta: oauth-2025-04-20`).\n4. Parses `five_hour.utilization`, `seven_day.utilization`, and each `resets_at` from the response.\n5. Caches in `~/.claude/cache/omc-limits-cache.json` for 1 minute. 429 uses exponential backoff (up to 5 minutes); network errors use a 2-minute TTL.\n6. Reads `model.display_name` and `context_window.used_percentage` from the JSON Claude Code passes on stdin. The trailing context-window label on the model name (e.g. `(1M context)` in `Opus 4.8 (1M context)`) is stripped before display.\n7. Applies ANSI colors and prints to stdout as `Model ctx:NN% 5h:NN%(Hh Mm) wk:NN%(Dd Hh)`.\n\n## License / Credits\n\nThe original code is MIT-licensed — yeachan-heo/oh-my-claudecode (`src/hud/usage-api.ts`, `src/hud/elements/limits.ts`). This minimal extract follows the same MIT license. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloper0hye%2Fminimal-claude-hud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeveloper0hye%2Fminimal-claude-hud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloper0hye%2Fminimal-claude-hud/lists"}