https://github.com/htahaozlu/context-hud
Local-first repository context and native macOS HUD for Claude Code and Codex.
https://github.com/htahaozlu/context-hud
agent-workflows claude-code codex developer-tools macos zed-extension
Last synced: 4 days ago
JSON representation
Local-first repository context and native macOS HUD for Claude Code and Codex.
- Host: GitHub
- URL: https://github.com/htahaozlu/context-hud
- Owner: htahaozlu
- License: other
- Created: 2026-05-11T07:14:28.000Z (9 days ago)
- Default Branch: main
- Last Pushed: 2026-05-13T02:44:42.000Z (7 days ago)
- Last Synced: 2026-05-13T04:34:04.724Z (7 days ago)
- Topics: agent-workflows, claude-code, codex, developer-tools, macos, zed-extension
- Language: Rust
- Homepage: https://github.com/htahaozlu/context-hud/releases/latest
- Size: 1.91 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# ContextHUD
English | Türkçe
Local-first repository context and native macOS usage visibility for coding agents.
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.
## Live demo
ContextHUD gives Claude Code and Codex a native macOS surface, so context drift and rolling usage stay visible while you work.
## Install
### Homebrew (recommended)
```bash
brew install --cask htahaozlu/context-hud/context-hud
```
`brew` auto-taps `htahaozlu/homebrew-context-hud` on first install. Upgrade later with `brew upgrade --cask context-hud`.
### macOS app (DMG)
1. Download `ContextHUD.dmg` from the [latest release](https://github.com/htahaozlu/context-hud/releases/latest) (universal: Apple Silicon + Intel).
2. Drag `ContextHUD.app` into `Applications`.
3. First launch: right-click `ContextHUD.app` → **Open** → **Open** again. The app is ad-hoc signed (not notarized).
4. Eject and delete the DMG.
If macOS reports the app as "damaged", remove the quarantine flag:
```bash
xattr -dr com.apple.quarantine /Applications/ContextHUD.app
```
### CLI
```bash
cargo install --path .
```
## Preview
Native macOS usage window with rolling session visibility for Claude Code and Codex.
Compact 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.
## What it does
ContextHUD solves two persistent problems in agent-driven development:
- repository context drifts faster than an agent brief can keep up
- usage and session state stay buried in terminal output and local transcripts
It addresses both through a local pipeline that continuously produces stable project summaries and a native macOS HUD for Claude Code and Codex activity.
### Core surfaces
- Repository snapshots under `.context-hud/`
- Stable `AGENT.md` and `CLAUDE.md`
- CLI for refresh, watch, and global views
- Native AppKit menubar companion
- Markdown and JSON artifacts for tooling
## Key capabilities
### Repository context generation
Each refresh writes agent-readable state into `.context-hud/`:
- `state.json`
- `brief-now.md`
- `brief-session.md`
- `brief-week.md`
- `AGENT.md`
- `hud.md`
For Claude Code compatibility, `CLAUDE.md` is mirrored at the repository root.
### CLI workflow
- `context-hud hud` refreshes the current repository and prints the HUD
- `context-hud snapshot` writes artifacts without printing the HUD
- `context-hud watch 30 .` keeps repository context fresh on an interval
- `context-hud global` builds a cross-project HUD under `~/.context-hud/`
### Native macOS companion
The companion app reads `~/.context-hud/hud.json` and provides:
- a compact menubar status item (active agent + project + context %)
- a modern AppKit popover with cards for the active agent, context window,
rolling 5h/7d limits with progress bars, parallel sessions, and other
detected AI tools
- a theme picker with inline color swatches and live preview — hover a
theme and the menubar title repaints in that palette before you commit
- a full Settings window with Usage, Appearance, Menubar, and About tabs
- per-session context percentage for parallel Claude / Codex sessions
- a Notification Center / desktop widget (small, medium, large) showing the
active agent, project, context ring, and 5h/7d limit bars — kept in sync
with the menubar via `WidgetCenter` reloads on every regeneration
The widget reads the same `~/.context-hud/hud.json` snapshot, so the menubar
title and the widget never disagree. To add it, open Notification Center →
"Edit Widgets" → search "ContextHUD" and pick a size.
If the menubar icon is hidden by overflow (Bartender, Hidden Bar, or a
crowded menubar), launching ContextHUD again from Finder / Spotlight opens
the Settings window directly so you can still reach preferences.
The desktop UI is native AppKit (NSPopover + NSVisualEffectView, continuous
corner curves, SF Symbol toolbar). `detail.html` is an export artifact, not
the primary app experience.
## Usage
### Refresh the current repository
```bash
context-hud hud
```
### Write artifacts without printing the HUD
```bash
context-hud snapshot
```
### Keep repository context fresh
```bash
context-hud watch 30 .
```
### Generate the global HUD
```bash
context-hud global
context-hud watch-global 30
```
The global HUD is written to `~/.context-hud/hud.md`.
## Artifact layout
Each refresh writes the following files atomically:
- `.context-hud/state.json`
- `.context-hud/brief-now.md`
- `.context-hud/brief-session.md`
- `.context-hud/brief-week.md`
- `.context-hud/AGENT.md`
- `.context-hud/hud.md`
- `CLAUDE.md`
Atomic writes ensure agents do not observe partial state during refresh.
## Data sources
ContextHUD combines:
- Git branch, recent commits, and worktree status
- file activity inferred from repository mtimes
- optional Claude Code statusline snapshot from `~/.context-hud/claude-statusline.json`
- Claude Code usage from `~/.claude/projects/**/*.jsonl`
- Codex CLI usage from `~/.codex/sessions/**/*.jsonl`
No external service is required for the core repository summaries. Usage aggregation relies on locally available transcripts, optional native Claude Code statusline data, and `python3`.
### Claude Code parity
For Claude context percentage, the best source is Claude Code's native statusline payload. ContextHUD can persist that payload locally:
```json
{
"statusLine": {
"type": "command",
"command": "context-hud claude-statusline"
}
}
```
This 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.
## Packaging
The repository includes scripts for the macOS companion build:
```bash
scripts/build-menubar-app.sh
scripts/create-macos-dmg.sh
```
Artifacts:
- `dist/ContextHUD.app`
- `dist/ContextHUD.dmg`
## Repository layout
- `src/` core engine, artifact rendering, and usage aggregation
- `src/bin/context-hud.rs` standalone CLI entry point
- `menubar/context-hud.swift` macOS companion app
- `examples/snapshot.rs` native development harness
## Development
```bash
cargo check
cargo run --example snapshot
```
## Community
- Questions and usage help: GitHub Discussions
- Bugs and feature requests: GitHub Issues
- Contribution guide: `CONTRIBUTING.md`
- Security reporting: `SECURITY.md`
## License
Apache-2.0