ContextBar

Live demo

ContextBar gives Claude Code and Codex a native macOS surface, so context drift and rolling usage stay visible while you work.

Install

Homebrew (recommended)

brew install --cask htahaozlu/context-bar/context-bar

brew auto-taps htahaozlu/homebrew-context-bar on first install. Upgrade later with brew update && brew upgrade --cask htahaozlu/context-bar/context-bar.

macOS app (DMG)

Download ContextBar.dmg from the latest release (universal: Apple Silicon + Intel).
Drag ContextBar.app into Applications.
First launch: right-click ContextBar.app → Open → Open again. The app is ad-hoc signed (not notarized).
Eject and delete the DMG.

If macOS reports the app as "damaged", remove the quarantine flag:

xattr -dr com.apple.quarantine /Applications/ContextBar.app

CLI

cargo install --path .

Terminal CLI

Build from source or install from crates.io once published:

git clone https://github.com/htahaozlu/context-bar.git
cd context-bar
cargo build --release   # binary at target/release/context-bar

# or, once published:
cargo install context-bar

The terminal CLI currently spawns python3 for usage aggregation, so it needs python3 on PATH. Cross-platform prebuilt binaries, a pure-Rust engine (no python3), npx context-bar, and Windows support are rolling out in 0.5.0 — see docs/ai/ROADMAP.md.

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.

The Cost tab estimates what your subscription usage would cost on the metered API — per day, per project, for Claude and Codex — and projects it against your plan price (e.g. "~41× your Max 20× plan"). It replicates better-ccusage daily --instances natively, then adds a monthly projection and a cost trend that a CLI can't show passively. Numbers are estimates priced from the LiteLLM rate table (the same source ccusage uses), not bills.

What it does

ContextBar 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-bar/
Stable AGENT.md and CLAUDE.md
CLI for refresh, watch, and global views
Native AppKit menubar companion
Estimated API-equivalent cost per day per project (Claude + Codex)
Markdown and JSON artifacts for tooling

Key capabilities

Repository context generation

Each refresh writes agent-readable state into .context-bar/:

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-bar hud refreshes the current repository and prints the HUD
context-bar snapshot writes artifacts without printing the HUD
context-bar watch 30 . keeps repository context fresh on an interval
context-bar global builds a cross-project HUD under ~/.context-bar/

Native macOS companion

The companion app reads ~/.context-bar/context.json (hud.json before v0.3.13) 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
three data views (Usage, Stats, Cost) plus a clean, Apple-style settings set (General · Appearance · Privacy) and About
per-session context percentage for parallel Claude / Codex sessions

Estimated cost & plan value

The Cost tab answers a question subscription users increasingly ask — "what would this cost if I were forced onto the metered API?"

per-day, per-project cost breakdown (the native equivalent of better-ccusage daily --instances), for both Claude and Codex
estimated cost for today / last 7 days / last 30 days, plus 30-day input vs. output token totals
a monthly projection compared to your actual plan price (e.g. "≈ $8,268/mo — about 41× your Max 20× plan")
an interactive 30-day cost-trend chart — hover any day for its date, estimated cost, and tokens
priced per turn by model from the LiteLLM rate table (the same canonical source ccusage uses), fetched live with a 24h on-disk cache and a bundled offline fallback; Anthropic's prompt-cache and >200K long-context rules are honored
everything is clearly labelled an estimate — subscription plans are not billed per token. Set CONTEXTBAR_PRICING_OFFLINE=1 to skip the live rate fetch.

Desktop & Notification Center widget

ContextBar ships with a native WidgetKit extension in three sizes — systemSmall, systemMedium, and systemLarge. The widget reads the same context.json as the menubar via a shared App Group container (DQJT5BCZCM.com.htahaozlu.contextbar), so it always reflects the active agent, project, model, context %, rolling 5h/7d limits, and a per-agent breakdown without any extra daemon.

To add it:

Install ContextBar 0.3.12 or later and launch it once so macOS indexes the extension (pluginkit -m -v -i com.htahaozlu.contextbar.widget should list it).
Open Notification Center (click the clock) → Edit Widgets, or right-click the desktop → Edit Widgets.
Search for ContextBar, then drop the small / medium / large variant wherever you want.

The widget extension is sandboxed and signed with the App Group entitlement, which is required by chronod on macOS 14+ (the previous unsandboxed bundle was silently rejected with Ignoring restricted or unknown extension). The host menubar app mirrors ~/.context-bar/context.json into the App Group container on every refresh so the sandboxed widget can read it.

Share Today's HUD

The popover footer has a Share button (square.and.arrow.up) that renders the current HUD as a PNG share card — active agent, model, context %, 5h/7d usage, and other detected tools — masked by default so project names are not leaked. The image is saved to a temporary path and opened in Preview / a save dialog so you can drop it into Slack, X, or a status thread without screenshotting and cropping.

Headless render (no UI) for automation:

CONTEXTBAR_SHARE_RENDER_PATH=/tmp/hud.png \
CONTEXTBAR_SHARE_MASK=1 \
/Applications/ContextBar.app/Contents/MacOS/context-bar

Set CONTEXTBAR_SHARE_MASK=0 to keep real project names in the card.

If the menubar icon is hidden by overflow (Bartender, Hidden Bar, or a crowded menubar), launching ContextBar 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

context-bar hud

Write artifacts without printing the HUD

context-bar snapshot

Keep repository context fresh

context-bar watch 30 .

Generate the global HUD

context-bar global
context-bar watch-global 30

The global HUD is written to ~/.context-bar/hud.md.

Terminal CLI

context-bar 0.4.0 adds a first-class terminal CLI built on the same cost engine that powers the macOS app (which remains the premium surface and is unchanged). New report verbs render ccusage-style tables for Claude Code and Codex usage.

Report verbs

context-bar daily — per-day usage + cost table (Claude + Codex), grouped with an "All" row, per-agent sub-rows, and a Total row
context-bar weekly — per-ISO-week table
context-bar monthly — per-month table
context-bar session — recent sessions table
context-bar blocks — active 5h block per agent: usage % of limit, burn rate ($/hr · tok/min), projected total, reset countdown, ETA-to-limit
context-bar live — the same 5h-block burn metrics as an auto-refreshing terminal dashboard (ratatui): a color-tiered gauge per agent, refreshing every --interval seconds; q to quit, r to refresh now. Works over SSH and on Linux/Windows.

Report flags

--instances — split the daily table by project (per day × project)
--breakdown, -b — also print a per-model breakdown table
--agent <claude|codex|all> — restrict to one agent (default: all)
--since <YYYYMMDD> / --until <YYYYMMDD> — inclusive date filter
--json — emit the report as JSON (for piping / jq)
--offline — skip the live pricing fetch (cached / bundled rates)
--lang <en|tr> — force UI language (default: locale; tables and headers are fully bilingual EN/TR)
--no-color — disable ANSI color (also auto-off when piped or NO_COLOR is set)

The engine verbs hud, snapshot, global, claude-statusline, watch, watch-global, and --version are unchanged.

Example

Coding Agent Usage Report — Daily
| Date       | Agent      | Models            | Input   | Output    | Cache Create | Cache Read    | Total         | Cost (USD) |
| 2026-05-29 | All        | opus-4-8, gpt-5.5 | 937,053 | 5,372,832 | 17,259,276   | 997,890,608   | 1,021,459,769 | $746.00    |
|            |   - Claude | opus-4-8          | 652,442 | 5,336,901 | 17,259,276   | 995,772,208   | 1,019,020,827 | $742.44    |
|            |   - Codex  | gpt-5.5           | 284,611 | 35,931    | 0            | 2,118,400     | 2,438,942     | $3.56      |
| Total      |            |                   | ...     | ...       | ...          | ...           | ...           | $1,682.65  |

In the real terminal these are Unicode box-drawing tables via comfy-table. Total follows ccusage's Total Tokens — input + output + cache_creation + cache_read. Costs are estimates of what the metered API would charge, not a bill — subscription users aren't billed per token.

Artifact layout

Each refresh writes the following files atomically:

.context-bar/state.json
.context-bar/brief-now.md
.context-bar/brief-session.md
.context-bar/brief-week.md
.context-bar/AGENT.md
.context-bar/hud.md
CLAUDE.md

Atomic writes ensure agents do not observe partial state during refresh.

Data sources

ContextBar combines:

Git branch, recent commits, and worktree status
file activity inferred from repository mtimes
optional Claude Code statusline snapshot from ~/.context-bar/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. ContextBar can persist that payload locally:

{
  "statusLine": {
    "type": "command",
    "command": "context-bar claude-statusline"
  }
}

This writes ~/.context-bar/claude-statusline.json, which ContextBar reads as the primary Claude context source. If the snapshot is missing or stale, ContextBar falls back to transcript-based estimation.

Packaging

The repository includes scripts for the macOS companion build:

scripts/build-menubar-app.sh
scripts/create-macos-dmg.sh

To include the WidgetKit extension in a direct app build:

WIDGET_BUILD=1 scripts/build-menubar-app.sh

scripts/create-macos-dmg.sh enables the widget build by default.

Artifacts:

dist/ContextBar.app
dist/ContextBar.dmg

Repository layout

src/ core engine, artifact rendering, and usage aggregation
src/bin/context-bar.rs standalone CLI entry point
menubar/context-bar.swift macOS companion app
examples/snapshot.rs native development harness

Development

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

context-bar 0.6.1

ContextBar

Live demo

Install

Homebrew (recommended)

macOS app (DMG)

CLI

Terminal CLI

Preview

What it does

Core surfaces

Key capabilities

Repository context generation

CLI workflow

Native macOS companion

Estimated cost & plan value

Desktop & Notification Center widget

Share Today's HUD

Usage

Refresh the current repository

Write artifacts without printing the HUD

Keep repository context fresh

Generate the global HUD

Terminal CLI

Report verbs

Report flags

Example

Artifact layout

Data sources

Claude Code parity

Packaging

Repository layout

Development

Community

License