ResearchBar

Corbis-gated research intelligence in your macOS menu bar.

ResearchBar is the Agentic Assets fork of CodexBar for academic and industry research workflows. The public product identity is ResearchBar with bundle id com.corbis.researchbar, app group <team>.com.corbis.researchbar, config at ~/.config/researchbar/config.json, Keychain services under com.corbis.researchbar, and local logs under ~/Library/Logs/ResearchBar/.

The inherited SwiftPM package, target names, and source folders still use CodexBar* names where that keeps upstream sync and avoids a broad risky module rename. The shipped app bundle, executable, CLI helper, widget extension, bundle id, menu bar accessibility identity, storage roots, scripts, and guides are ResearchBar-owned.

Start with ResearchBar/README.md, ResearchBar/BUILD.md, and ResearchBar/researchbar-in-60-seconds.md. The Corbis backend contract lives in agentic-assets-app/docs/researchbar-evaluation/.

Current App

ResearchBar is a macOS 14+ menu bar app that shows the Corbis research pulse: academic identity, citation metrics, tracking state, low-confidence warnings, and credit-safe refresh status. The inherited provider-usage machinery remains available as implementation scaffolding and optional future surface, but Corbis research intelligence is the default product direction.

ResearchBar currently builds from this fork with:

• ResearchBar.app
• CFBundleIdentifier=com.corbis.researchbar
• CFBundleExecutable=ResearchBar
• ResearchBarCLI bundled at ResearchBar.app/Contents/Helpers/ResearchBarCLI
• ResearchBarWidget.appex bundled with widget id com.corbis.researchbar.widget

Install

Requirements

• macOS 14+ (Sonoma)

ResearchBar is not on a public Homebrew cask or Sparkle feed yet. Use local builds from this repo until a ResearchBar-specific release channel is approved.

First run

• Open Settings → Research and connect a Corbis MCP token.
• Keep provider features disabled unless you are intentionally testing inherited CodexBar surfaces.

Set API keys from the CLI

Provider toggles and API keys live in the resolved ResearchBar config file. New installs use ~/.config/researchbar/config.json; RESEARCHBAR_CONFIG can point at a custom file. ResearchBar still accepts CODEXBAR_CONFIG as an explicit compatibility override, but it does not auto-load CodexBar's old config path. You can script the same provider list that Settings → Providers uses:

researchbar config providers
researchbar config enable --provider grok
researchbar config disable --provider cursor

For API-key providers, store a key without opening Settings:

printf '%s' "$ELEVENLABS_API_KEY" | researchbar config set-api-key --provider elevenlabs --stdin

set-api-key trims the piped value, stores it with restrictive config-file permissions, and enables the provider by default. Use --no-enable to only save the key, or --api-key <key> for one-off local scripts where shell history is not a concern. See CLI configuration for the full flow.

Inherited Provider Surface

The sections below document inherited CodexBar provider behavior that still exists in the codebase. It is useful for upstream sync, diagnostics, and optional beta surfaces, but it is not the primary ResearchBar product surface.

Providers

• Codex — OAuth API or local Codex CLI, plus optional OpenAI web dashboard extras.
• OpenAI — Admin API key usage/cost graphs with legacy credit-balance fallback.
• Claude — OAuth API, browser cookies, or CLI PTY fallback; session and weekly usage where available.
• Cursor — Browser session cookies for plan + usage + billing resets.
• OpenCode — Browser cookies for workspace subscription usage.
• OpenCode Go — Browser cookies for Go usage windows.
• Alibaba Coding Plan — Web cookies or API key for coding-plan quotas.
• Alibaba Token Plan — Bailian browser/manual cookies for token-plan credits.
• Gemini — OAuth-backed quota API using Gemini CLI credentials (no browser cookies).
• Antigravity — Local language server probe (experimental); no external auth.
• Droid — Browser cookies + WorkOS token flows for Factory usage + billing.
• Copilot — GitHub device flow + Copilot internal usage API.
• Devin — Chrome localStorage session or manual Bearer token for daily and weekly quotas.
• z.ai — API token for quota + MCP windows.
• Manus — Browser session_id auth for credit balance, monthly credits, and daily refresh tracking.
• MiniMax — API token, cookie header, or browser cookies for coding-plan usage.
• T3 Chat — Browser cookies capture for Base and Overage usage buckets.
• Kimi — Auth token (JWT from kimi-auth cookie) for weekly quota + 5‑hour rate limit.
• Kimi K2 (unofficial) — Legacy API key flow for credit-based usage totals.
• Kilo — API token with CLI-auth fallback for Kilo Pass usage.
• Kiro — CLI-based usage; monthly credits + bonus credits.
• Vertex AI — Google Cloud gcloud OAuth with token cost tracking from local Claude logs.
• Augment — Augment CLI or browser cookies for credits tracking and usage monitoring.
• Amp — Browser cookie-based authentication with Amp Free usage tracking.
• Ollama — API key access plus browser cookies for Ollama Cloud usage windows.
• JetBrains AI — Local XML-based quota from JetBrains IDE configuration; monthly credits tracking.
• Warp — API token for GraphQL request limits and monthly credits.
• ElevenLabs — API key for character credits and voice slot usage.
• OpenRouter — API token for credit-based usage tracking across multiple AI providers.
• Windsurf — Browser localStorage session import or local SQLite cache for plan usage.
• Zed — Zed editor Keychain session for plan, edit-prediction quota, billing cycle, and overdue invoices.
• Perplexity — Account usage credits from Perplexity usage data.
• Xiaomi MiMo — Browser cookies for balance and token-plan usage.
• Doubao — API key for Volcengine Ark request-limit probes.
• Abacus AI — Browser cookie auth for ChatLLM/RouteLLM compute credit tracking.
• Mistral — Browser cookies for monthly spend tracking.
• DeepSeek — API key for credit balance tracking (paid vs. granted breakdown).
• Moonshot / Kimi API — API key for Moonshot/Kimi API account balance tracking.
• Venice — API key for DIEM or USD balance tracking.
• Codebuff — API token (or ~/.config/manicode/credentials.json) for credit balance + weekly rate limit.
• Crof — API key for dollar credit balance and request quota tracking.
• Command Code — Browser cookies for monthly USD credits from Command Code billing.
• StepFun — Username + password login for Step Plan rate limits (5‑hour + weekly windows) and subscription plan name.
• AWS Bedrock — AWS access keys or a named AWS profile (SSO/assume-role via the AWS CLI) for Cost Explorer usage and monthly budget tracking.
• Grok — Grok CLI billing RPC plus grok.com browser-session fallback.
• GroqCloud — API key for Enterprise Prometheus request/token/cache-hit metrics.
• LLM Proxy — API key + base URL for aggregate proxy quota stats and provider breakdowns.
• LiteLLM — Virtual key + proxy URL for personal and team budget/spend tracking.
• Deepgram — API key usage summaries across speech, agent, token, and TTS metrics.
• Poe — API key for current point balance and recent points history.
• Chutes — API key for subscription usage, rolling and monthly quota windows, and pay-as-you-go quotas.
• Open to new providers: provider authoring guide.

Icon & Screenshot

The menu bar icon is a tiny usage meter. Bar meaning is provider-specific, and errors/stale data can dim the icon or show an incident indicator.

Features

• Multi-provider menu bar with per-provider toggles (Settings → Providers).
• Provider-specific usage meters with reset countdowns.
• Optional Codex web dashboard enrichments (code review remaining, usage breakdown, credits history).
• Inline spend and usage charts for API-backed providers such as OpenAI, Claude Admin API, OpenRouter, LiteLLM, z.ai, MiniMax, Mistral, and AWS Bedrock.
• Configurable cost-usage scans for Codex + Claude, plus reused chart UI for supported provider histories.
• Provider status polling with incident badges in the menu and icon overlay.
• Merge Icons mode to combine providers into one status item + switcher.
• Display controls for provider icons, labels, bars, reset-time style, and highest-usage auto-selection.
• Refresh cadence presets (manual, 1m, 2m, 5m, 15m).
• Bundled CLI (researchbar) for scripts and CI (including researchbar cost --provider codex, claude, or both for local cost usage); macOS and Linux CLI builds available.
• WidgetKit widgets for supported providers.
• Localized app and website with a shared 21-language catalog, automatic website detection, persistent pickers, and RTL support.
• Optional session quota notifications and weekly-reset confetti.
• Privacy-first: on-device parsing by default; browser cookies are opt-in and reused (no passwords stored).

Privacy note

Wondering if ResearchBar scans your disk? It doesn’t crawl your filesystem; it reads a small set of known locations (browser cookies/local storage, provider config files, local JSONL logs) when the related features are enabled. Provider tokens and token-account settings live in the ResearchBar config file with restrictive file permissions. See the upstream CodexBar discussion and audit notes in issue #12.

macOS permissions (why they’re needed)

• Full Disk Access (optional): only required to read Safari cookies/local storage for web-based providers. If you don’t grant it, use another supported browser, manual cookies/API keys, OAuth, or CLI/local sources where that provider supports them.
• Keychain access (prompted by macOS):
  • Chromium cookie import needs the browser “Safe Storage” key to decrypt cookies.
  • Claude OAuth bootstrap may read the Claude CLI Keychain item when ResearchBar has no usable cached credentials.
  • ResearchBar may use Keychain for browser cookie decryption, cached cookie headers, and OAuth/device-flow credentials where those sources require it.
  • How do I prevent those keychain alerts?
    • Open Keychain Access.app → login keychain → search the prompted item (for Claude OAuth, usually “Claude Code-credentials”).
    • Open the item → Access Control → add ResearchBar.app under “Always allow access by these applications”.
    • Prefer adding just ResearchBar (avoid “Allow all applications” unless you want it wide open).
    • Relaunch ResearchBar after saving.
    • Reference screenshot:
  • How to do the same for the browser?
    • Find the browser’s “Safe Storage” key (e.g., “Chrome Safe Storage”, “Brave Safe Storage”, “Microsoft Edge Safe Storage”).
    • Open the item → Access Control → add ResearchBar.app under “Always allow access by these applications”.
    • This removes the prompt when ResearchBar decrypts cookies for that browser.
  • Last resort: stop all Keychain reads entirely: if "Always Allow" does not stick (for example, macOS resets the ACL after a Chromium update or a partition_id reset), open ResearchBar → Settings → Advanced → Keychain access and enable Disable Keychain access. ResearchBar will no longer touch the Keychain. Browser-cookie-based providers will be skipped, but Claude/Codex OAuth via the CLI still works because it reads ~/.codex / ~/.claude config files, not the Keychain.
• Files & Folders prompts (folder/volume access): ResearchBar launches provider CLIs and local probes for some providers. If those helpers read a project directory or external drive, macOS may ask ResearchBar for that folder/volume (e.g., Desktop or an external volume). This is driven by the helper’s working directory, not background disk scanning.
• What we do not request in the background: no Screen Recording or Accessibility permissions; user-triggered helper actions may ask macOS for Automation permission to open Terminal. No passwords are stored (browser cookies are reused when you opt in).

Docs

• Providers overview: docs/providers.md
• Provider authoring: docs/provider.md
• Issue labeling guide: docs/ISSUE_LABELING.md
• UI & icon notes: docs/ui.md
• CLI reference: docs/cli.md
• Configuration: docs/configuration.md
• CLI configuration: docs/cli-configuration.md
• Widgets: docs/widgets.md
• Architecture: docs/architecture.md
• Refresh loop: docs/refresh-loop.md
• Status polling: docs/status.md
• Sparkle updates: docs/sparkle.md
• Packaging: docs/packaging.md
• Development: docs/DEVELOPMENT.md
• Release checklist: docs/RELEASING.md
• Changelog: CHANGELOG.md

Getting started (dev)

• Clone the repo and open it in Xcode or run the scripts directly.
• Launch once, then toggle providers in Settings → Providers.
• Install/sign in to provider sources you rely on (CLIs, browser cookies, OAuth/device flow, API keys, or local app/config files).
• Optional: set OpenAI cookies (Automatic or Manual) for Codex dashboard extras.

Build from source

Requires macOS 14+ and Swift 6.2+.

./Scripts/package_app.sh        # builds ResearchBar.app in-place
CODEXBAR_SIGNING=adhoc ./Scripts/package_app.sh  # ad-hoc signing (no Apple Developer account)
open ResearchBar.app

Dev loop:

./Scripts/compile_and_run.sh
./Scripts/compile_and_run.sh --test  # also run the sharded test suite before packaging/relaunching
make check                           # SwiftFormat + SwiftLint
make docs-list                       # list docs with frontmatter summaries

CLI install:

# after installing ResearchBar.app in /Applications
./bin/install-researchbar-cli.sh

Related

• ✂️ Trimmy — “Paste once, run once.” Flatten multi-line shell snippets so they paste and run.
• 🧳 MCPorter — TypeScript toolkit + CLI for Model Context Protocol servers.
• 🧿 oracle — Ask the oracle when you're stuck. Invoke GPT-5 Pro with a custom context and files.

Looking for a Windows version?

• Win-CodexBar

Linux desktop integration?

• codexbar-waybar — Waybar custom module + GTK4 popover for Hyprland / Sway / other Wayland compositors, built on top of the bundled Linux CLI.
• Codexbar GNOME — GNOME Shell extension that brings CodexBar usage into the desktop panel.
• noctalia-codex-usage — Noctalia/Quickshell plugin that shows Codex 5-hour and weekly usage limits, built on top of the bundled Linux CLI.

Status bar & terminal integration

• showy-quota — always-on AI plan quota strips for SketchyBar, tmux, and Zellij (standalone WASM plugin), built on researchbar serve / the bundled CLI.

Credits

Inspired by ccusage (MIT), specifically the cost usage tracking.

License

MIT • Peter Steinberger (steipete)