{"id":49919971,"url":"https://github.com/htahaozlu/context-hud","last_synced_at":"2026-05-16T19:12:43.746Z","repository":{"id":357502424,"uuid":"1235282141","full_name":"htahaozlu/context-hud","owner":"htahaozlu","description":"Local-first repository context and native macOS HUD for Claude Code and Codex.","archived":false,"fork":false,"pushed_at":"2026-05-13T02:44:42.000Z","size":2002,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T04:34:04.724Z","etag":null,"topics":["agent-workflows","claude-code","codex","developer-tools","macos","zed-extension"],"latest_commit_sha":null,"homepage":"https://github.com/htahaozlu/context-hud/releases/latest","language":"Rust","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/htahaozlu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","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},"funding":{"github":["htahaozlu"]}},"created_at":"2026-05-11T07:14:28.000Z","updated_at":"2026-05-13T02:44:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/htahaozlu/context-hud","commit_stats":null,"previous_names":["htahaozlu/context-hud"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/htahaozlu/context-hud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htahaozlu%2Fcontext-hud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htahaozlu%2Fcontext-hud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htahaozlu%2Fcontext-hud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htahaozlu%2Fcontext-hud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/htahaozlu","download_url":"https://codeload.github.com/htahaozlu/context-hud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htahaozlu%2Fcontext-hud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33115530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T18:38:32.183Z","status":"ssl_error","status_checked_at":"2026-05-16T18:38:29.903Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-workflows","claude-code","codex","developer-tools","macos","zed-extension"],"created_at":"2026-05-16T19:12:42.166Z","updated_at":"2026-05-16T19:12:43.714Z","avatar_url":"https://github.com/htahaozlu.png","language":"Rust","funding_links":["https://github.com/sponsors/htahaozlu"],"categories":[],"sub_categories":[],"readme":"# ContextHUD\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"ContextHUD logo\" width=\"560\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  English | \u003ca href=\"README.tr.md\"\u003eTürkçe\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first repository context and native macOS usage visibility for coding agents.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  ContextHUD keeps agents grounded in the repository they are working on, writes stable agent-readable briefs, and gives Claude Code and Codex usage a native macOS surface.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/htahaozlu/context-hud/releases/latest/download/ContextHUD.dmg\"\u003e\n    \u003cimg src=\"docs/images/download-macos-cta.svg\" alt=\"Download app for macOS\" width=\"300\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/downloads/htahaozlu/context-hud/total?style=flat-square\u0026label=downloads\" alt=\"Total Downloads\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/htahaozlu/context-hud?style=flat-square\" alt=\"Stars\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/htahaozlu/context-hud/releases/latest\"\u003e\n    \u003cimg alt=\"Latest release\" src=\"https://img.shields.io/github/v/release/htahaozlu/context-hud?style=flat-square\u0026label=release\u0026color=2F81F7\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-5DADE2\"\u003e\n  \u003c/a\u003e\n  \u003cimg alt=\"Platform\" src=\"https://img.shields.io/badge/platform-macOS-7DCEA0\"\u003e\n\u003c/p\u003e\n\n## Live demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/context-hud-demo.gif\" alt=\"ContextHUD demo showing Claude Code and Codex usage updating live on macOS\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nContextHUD gives Claude Code and Codex a native macOS surface, so context drift and rolling usage stay visible while you work.\n\n## Install\n\n### Homebrew (recommended)\n\n```bash\nbrew install --cask htahaozlu/context-hud/context-hud\n```\n\n`brew` auto-taps `htahaozlu/homebrew-context-hud` on first install. Upgrade later with `brew upgrade --cask context-hud`.\n\n### macOS app (DMG)\n\n1. Download `ContextHUD.dmg` from the [latest release](https://github.com/htahaozlu/context-hud/releases/latest) (universal: Apple Silicon + Intel).\n2. Drag `ContextHUD.app` into `Applications`.\n3. First launch: right-click `ContextHUD.app` → **Open** → **Open** again. The app is ad-hoc signed (not notarized).\n4. Eject and delete the DMG.\n\nIf macOS reports the app as \"damaged\", remove the quarantine flag:\n\n```bash\nxattr -dr com.apple.quarantine /Applications/ContextHUD.app\n```\n\n### CLI\n\n```bash\ncargo install --path .\n```\n\n## Preview\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/context-hud-screenshot.png\" alt=\"ContextHUD native usage window\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nNative macOS usage window with rolling session visibility for Claude Code and Codex.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/context-hud-menubar.png\" alt=\"ContextHUD menubar\" width=\"400\"\u003e\n\u003c/p\u003e\n\nCompact menubar status item showing active agent, project, and context usage. Clicking it opens a native popover with the active session, context window, rolling 5h/7d limits, parallel sessions, and a live theme picker.\n\n## What it does\n\nContextHUD solves two persistent problems in agent-driven development:\n\n- repository context drifts faster than an agent brief can keep up\n- usage and session state stay buried in terminal output and local transcripts\n\nIt addresses both through a local pipeline that continuously produces stable project summaries and a native macOS HUD for Claude Code and Codex activity.\n\n### Core surfaces\n\n- Repository snapshots under `.context-hud/`\n- Stable `AGENT.md` and `CLAUDE.md`\n- CLI for refresh, watch, and global views\n- Native AppKit menubar companion\n- Markdown and JSON artifacts for tooling\n\n## Key capabilities\n\n### Repository context generation\n\nEach refresh writes agent-readable state into `.context-hud/`:\n\n- `state.json`\n- `brief-now.md`\n- `brief-session.md`\n- `brief-week.md`\n- `AGENT.md`\n- `hud.md`\n\nFor Claude Code compatibility, `CLAUDE.md` is mirrored at the repository root.\n\n### CLI workflow\n\n- `context-hud hud` refreshes the current repository and prints the HUD\n- `context-hud snapshot` writes artifacts without printing the HUD\n- `context-hud watch 30 .` keeps repository context fresh on an interval\n- `context-hud global` builds a cross-project HUD under `~/.context-hud/`\n\n### Native macOS companion\n\nThe companion app reads `~/.context-hud/hud.json` and provides:\n\n- a compact menubar status item (active agent + project + context %)\n- a modern AppKit popover with cards for the active agent, context window,\n  rolling 5h/7d limits with progress bars, parallel sessions, and other\n  detected AI tools\n- a theme picker with inline color swatches and live preview — hover a\n  theme and the menubar title repaints in that palette before you commit\n- a full Settings window with Usage, Appearance, Menubar, and About tabs\n- per-session context percentage for parallel Claude / Codex sessions\n- a Notification Center / desktop widget (small, medium, large) showing the\n  active agent, project, context ring, and 5h/7d limit bars — kept in sync\n  with the menubar via `WidgetCenter` reloads on every regeneration\n\nThe widget reads the same `~/.context-hud/hud.json` snapshot, so the menubar\ntitle and the widget never disagree. To add it, open Notification Center →\n\"Edit Widgets\" → search \"ContextHUD\" and pick a size.\n\nIf the menubar icon is hidden by overflow (Bartender, Hidden Bar, or a\ncrowded menubar), launching ContextHUD again from Finder / Spotlight opens\nthe Settings window directly so you can still reach preferences.\n\nThe desktop UI is native AppKit (NSPopover + NSVisualEffectView, continuous\ncorner curves, SF Symbol toolbar). `detail.html` is an export artifact, not\nthe primary app experience.\n\n## Usage\n\n### Refresh the current repository\n\n```bash\ncontext-hud hud\n```\n\n### Write artifacts without printing the HUD\n\n```bash\ncontext-hud snapshot\n```\n\n### Keep repository context fresh\n\n```bash\ncontext-hud watch 30 .\n```\n\n### Generate the global HUD\n\n```bash\ncontext-hud global\ncontext-hud watch-global 30\n```\n\nThe global HUD is written to `~/.context-hud/hud.md`.\n\n## Artifact layout\n\nEach refresh writes the following files atomically:\n\n- `.context-hud/state.json`\n- `.context-hud/brief-now.md`\n- `.context-hud/brief-session.md`\n- `.context-hud/brief-week.md`\n- `.context-hud/AGENT.md`\n- `.context-hud/hud.md`\n- `CLAUDE.md`\n\nAtomic writes ensure agents do not observe partial state during refresh.\n\n## Data sources\n\nContextHUD combines:\n\n- Git branch, recent commits, and worktree status\n- file activity inferred from repository mtimes\n- optional Claude Code statusline snapshot from `~/.context-hud/claude-statusline.json`\n- Claude Code usage from `~/.claude/projects/**/*.jsonl`\n- Codex CLI usage from `~/.codex/sessions/**/*.jsonl`\n\nNo external service is required for the core repository summaries. Usage aggregation relies on locally available transcripts, optional native Claude Code statusline data, and `python3`.\n\n### Claude Code parity\n\nFor Claude context percentage, the best source is Claude Code's native statusline payload. ContextHUD can persist that payload locally:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"context-hud claude-statusline\"\n  }\n}\n```\n\nThis writes `~/.context-hud/claude-statusline.json`, which ContextHUD reads as the primary Claude context source. If the snapshot is missing or stale, ContextHUD falls back to transcript-based estimation.\n\n## Packaging\n\nThe repository includes scripts for the macOS companion build:\n\n```bash\nscripts/build-menubar-app.sh\nscripts/create-macos-dmg.sh\n```\n\nArtifacts:\n\n- `dist/ContextHUD.app`\n- `dist/ContextHUD.dmg`\n\n## Repository layout\n\n- `src/` core engine, artifact rendering, and usage aggregation\n- `src/bin/context-hud.rs` standalone CLI entry point\n- `menubar/context-hud.swift` macOS companion app\n- `examples/snapshot.rs` native development harness\n\n## Development\n\n```bash\ncargo check\ncargo run --example snapshot\n```\n\n## Community\n\n- Questions and usage help: GitHub Discussions\n- Bugs and feature requests: GitHub Issues\n- Contribution guide: `CONTRIBUTING.md`\n- Security reporting: `SECURITY.md`\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtahaozlu%2Fcontext-hud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhtahaozlu%2Fcontext-hud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtahaozlu%2Fcontext-hud/lists"}