ContextBar

English | Türkçe

Local-first repository context and native macOS usage visibility for coding agents.

ContextBar 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

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 upgrade --cask context-bar.

macOS app (DMG)

1. Download ContextBar.dmg from the latest release (universal: Apple Silicon + Intel).
2. Drag ContextBar.app into Applications.
3. First launch: right-click ContextBar.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:

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

CLI

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

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
• 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/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) is wired up in
menubar/widget/Widget.swift and ready to ship, but bundling it requires an
Xcode subproject — building widget extensions with raw swiftc produces an
.appex that pluginkit silently refuses to enumerate. The build-script flag
WIDGET_BUILD=1 opts into the experimental swiftc path; the proper Xcode
hand-off is tracked as the next milestone for the macOS companion.

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.

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

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