AgentHarbor

<div align="center"> <img src="src/assets/icon.png" alt="AgentHarbor" width="120" /> **English** | [Español](README.es-ES.md) # AgentHarbor **One tray app to manage all your AI coding agents.** For developers running Claude Code, Cursor, Codex, Gemini CLI, Kimi, DeepSeek, or Windsurf: track usage and spend, manage configurations, deploy capabilities, and keep every tool in sync — all from one native app. <p align="center"><img src="docs/assets/demo.gif" alt="Live per-provider rate limits and spend in the AgentHarbor tray popover (stylized)" width="720"></p> <p align="center">_{<a href="docs/assets/agentharbor-launch-1080p.mp4">▶ Watch the 36-second launch video</a>}</p> [](https://github.com/abhiunix/AgentHarbor/stargazers) [](https://github.com/abhiunix/AgentHarbor/releases/latest) [](https://github.com/abhiunix/AgentHarbor/releases) [](https://github.com/abhiunix/AgentHarbor/releases/latest) [](https://github.com/abhiunix/AgentHarbor/releases/latest) [](LICENSE) [](https://tauri.app) [](https://www.rust-lang.org) [](https://react.dev) [](https://www.typescriptlang.org) [](https://tailwindcss.com) [**Website**](https://agentharbor.openxsecurity.com) · [**Download**](https://github.com/abhiunix/AgentHarbor/releases/latest) · [**Getting Started**](docs/getting-started.md) · [**Features**](docs/features.md) · [**Docs**](docs/) </div> --- ## What is it? AgentHarbor is an AI coding agent manager — a native tray app for macOS and Windows that sits quietly in your menu bar / system tray while you code. It shows you real-time rate limits, session usage, and monthly spend for every AI provider you use — without opening a browser or running CLI commands. When you want to deploy an MCP server, rule, skill, or sub-agent across Claude Code, Cursor, and Windsurf at once, a guided wizard handles the diffs, backups, and atomic writes for you. --- ## Screenshots <div align="center"> <img src="docs/assets/screenshot-tray.webp" alt="AgentHarbor tray popover with live limits and spend for Claude, Cursor, Codex and Gemini" width="300"> _{Live limits, active agents, and Today / Week / All-time spend for every provider, right in your menu bar.} <br><br> ### Deep analytics behind every provider <img src="docs/assets/screenshot-usage-limits.webp" alt="Session and weekly usage limits with per-window severity coloring and reset countdowns" width="820"> _{Session and weekly limits with severity coloring, an active-window marker, and reset countdowns.} <br><br> <table> <tr> <td width="50%"><img src="docs/assets/screenshot-cost-analysis.webp" alt="Cost analysis broken down by component and by model"><br>_{Cost by component and by model, at API-equivalent rates}</td> <td width="50%"><img src="docs/assets/screenshot-token-usage.webp" alt="Token usage over time, input, output and cache"><br>_{Token usage over time: input, output, and cache}</td> </tr> <tr> <td width="50%"><img src="docs/assets/screenshot-message-log.webp" alt="Per-message log with model, tokens, tier and cost"><br>_{Per-message log: model, tokens, tier, and cost}</td> <td width="50%"><img src="docs/assets/screenshot-cursor-analytics.webp" alt="Cursor analytics inside AgentHarbor"><br>_{Not just Claude: Cursor, Codex, and Gemini too}</td> </tr> </table> <br> <a href="https://openxsecurity.com/blog/agentharbor-vs-ccusage-vs-codexbar"><b>See how it compares to ccusage and CodexBar &rarr;</b></a> </div> --- ## Why AgentHarbor? Tools like [ccusage](https://github.com/ryoppippi/ccusage) and [Claude Code Usage Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) do one job very well: if you want a terminal-based Claude Code usage monitor, use them. AgentHarbor is built for a different job — an always-on desktop app that watches **all** your providers and also manages the config files they read. | | AgentHarbor | ccusage | Claude Code Usage Monitor | |---|---|---|---| | Interface | Native tray app (macOS / Windows) | CLI | Terminal UI | | Providers | Claude Code, Cursor, Codex, Gemini CLI, Windsurf | Claude Code | Claude Code | | Spend tracking | Per-provider, incl. API-equivalent cost engine | Claude Code cost reports | Claude Code cost projections | | MCP / rules / skills / sub-agent deploy | ✅ guided wizard with diffs, backups, undo | — | — | | Drift detection | ✅ hash-based, with side-by-side review | — | — | | Local-only (no telemetry) | ✅ | ✅ | ✅ | --- ## Features - **Live tray analytics** — menu-bar metric updates every ~60 s: session percentage, monthly spend, quota bars — whichever is most relevant for each provider. - **Limit-state ladder** — tracks `Unauthenticated → ApiDisabled → BillablePaused → SubscriptionIssue → RateLimited → Reached → Approaching → Healthy` and surfaces native macOS notifications on transitions. - **Deploy wizard** — syntax-highlighted split/unified diffs, per-file `Replace / Merge / Append` strategy, automatic backups before every write. - **Undo Deploy** — one click restores the pre-deploy snapshot from the backup store. - **Presets** — bundle any set of capabilities for one-click deploy and reuse them across projects. - **Drift detection** — keeps MCP config sync honest across editors: detects when a teammate or another tool changes a managed file and shows a side-by-side diff with Accept or Restore. - **Cost engine** — per-model API-equivalent costs for Claude (Opus / Sonnet / Haiku) and Codex (GPT-5 / 4 / 3.5), token-deduplicated across session windows. - **Secrets manager** — stores sensitive env vars in the macOS Keychain and injects them into MCP `env` blocks at deploy time. - **Auto-update** — Tauri updater checks GitHub Releases every 4 hours; in-app banner with one-click install and optional 24 h snooze. - **Native macOS** — Keychain integration, system tray popover with click-through, optional menu-bar-only mode, native notifications. --- ## Supported providers | Provider | Analytics | Rate limits / spend | Deploy targets | |---|---|---|---| | **Claude Code** | Full (Pro / Max / Enterprise) | Session 5h, Weekly, Sonnet/Opus, monthly $ | MCP, skills, rules, hooks, agents | | **Cursor** | Full | Plan included + bonus + on-demand $, team OD | MCP, rules, agents | | **Codex (OpenAI)** | Full | Primary 5h, Weekly 7d, per-model $ | MCP, skills | | **Gemini CLI** | Quota | Pro → Flash → Flash Lite tier waterfall | Skills, hooks, agents | | **Kimi (Moonshot)** | Full (local sessions) | Subscription 5h/weekly or Moonshot balance | — | | **DeepSeek** | Full (local sessions) | Account balance | — | | **Windsurf** | Config | — | MCP, rules | | **GitHub Copilot** | — | — | Skills | | **VS Code** | — | — | Skills | | **Antigravity** | — | — | Skills | | JetBrains | *Coming soon* | | | | Amp | *Coming soon* | | | | Kiro | *Coming soon* | | | Cursor spend tracking covers the full picture — plan-included, bonus, and on-demand usage — not just a single total. See [Analytics & Tray](docs/analytics.md) for how each metric is derived. --- ## Installation > **macOS 13+ · Apple Silicon** · Signed with Apple Developer ID and notarized. 1. **Download the latest DMG:** [**AgentHarbor — latest release**](https://github.com/abhiunix/AgentHarbor/releases/latest) - Pick `AgentHarbor_<version>_aarch64.dmg`. 2. Open the DMG and drag **AgentHarbor.app** into **Applications**. 3. Launch from Spotlight or `/Applications`. If macOS flags it as "damaged" (rare, caused by quarantine attribute surviving an unusual download path): ```bash xattr -cr /Applications/AgentHarbor.app ``` ### Windows 10/11 · x64 1. Download `AgentHarbor_<version>_x64-setup.exe` (NSIS, friendlier wizard) or `AgentHarbor_<version>_x64_en-US.msi` (MSI, enterprise-deployable) from the [**latest release**](https://github.com/abhiunix/AgentHarbor/releases/latest). 2. Run the installer — it adds a Start menu shortcut (search **AgentHarbor**) and registers under *Settings → Apps → Installed apps*. Per-user install, no admin required. > **First-run note:** the Windows installer is currently **unsigned**, so Windows SmartScreen will show *"Windows protected your PC"*. Click **More info → Run anyway**. A code-signing cert is on the roadmap. On Windows the tray popover anchors above the system tray (clamped to the monitor). The tray icon shows the active provider's logo; hover reveals the current spend (`Provider · $X.YZ`) in the tooltip — Windows tray icons can't show inline text the way macOS NSStatusItem can, so the spend lives in the hover tooltip. **Linux** — *Coming soon.* --- ## Tray metric quick reference | Provider | Menu-bar title | Source | |---|---|---| | Claude Code Pro/Max | `XX%` of active **Session (5h)**, fallback to Weekly | `/api/oauth/usage` | | Claude Code Enterprise | `$N` total spend this cycle | `/api/oauth/usage` extra_usage | | Cursor | `$N` total spend = included + bonus + on-demand | Cursor API | | Codex | `XX%` of **Primary (5h)** WHAM window | OpenAI `wham` | | Gemini CLI | `XX%` of highest-priority tier with quota remaining | Cloud Code Assist | The icon swaps to its red variant and appends `!` whenever the active provider is in any non-healthy state. --- ## Documentation | Document | Contents | |---|---| | [Features](docs/features.md) | Visual tour of every major feature | | [Getting Started](docs/getting-started.md) | Install, first launch, connect providers, first deploy | | [Analytics & Tray](docs/analytics.md) | Menu-bar metrics, tray popover, LimitState ladder, per-provider pages | | [Deploying Capabilities & Agents](docs/deploying-capabilities.md) | Deploy wizard, presets, backups, drift detection, removing capabilities | | [Build & Release](docs/build-and-release.md) | Local dev, signed builds, release checklist | | [Troubleshooting](docs/troubleshooting.md) | Common issues and fixes | | [Regression Checklist](docs/regression-checklist.md) | QA checklist before every release | --- ## Privacy AgentHarbor is **local-only**. The only outbound network calls it makes are to each provider's official API endpoints using **your** OAuth tokens. No telemetry, no analytics pings, no data leaves your machine. Local files (Claude project JSONLs, Gemini telemetry) are read with file-share-friendly opens and never copied off-disk. --- ## Tech stack | Layer | Technology | |---|---| | Framework | [](https://tauri.app) | | Backend | [](https://www.rust-lang.org) · `reqwest`, `serde`, `keyring`, `chrono` | | Frontend | [](https://react.dev) [](https://www.typescriptlang.org) [](https://vite.dev) | | Styling | [](https://tailwindcss.com) · dark theme | | State | [](https://zustand-demo.pmnd.rs) | | Build target | macOS aarch64 + Windows x64 | --- ## Development ```bash npm install npm run tauri dev # hot reload dev npm run test:regression # tsc + vite build + cargo test ``` For signed/notarized release builds, see [`docs/build-and-release.md`](docs/build-and-release.md). ### Project layout ``` agentharbor/ ├── src/ React frontend │ ├── components/ UI (tray, registry, deploy, settings, analytics) │ ├── pages/ Route pages │ ├── stores/ Zustand state │ ├── lib/ Tauri IPC, types, utilities │ └── hooks/ Custom hooks ├── src-tauri/ Rust backend │ ├── src/ │ │ ├── analytics/ Per-provider analytics + tray commands │ │ ├── adapters/ Adapter implementations (Claude/Cursor/Windsurf/…) │ │ ├── commands/ Tauri IPC commands │ │ ├── registry/ Capability registry loader & validator │ │ ├── utils/ File I/O, keychain, paths, drift, manifest, backup │ │ ├── tray.rs System tray │ │ └── lib.rs App setup & command registration │ └── tauri.conf.json ├── registry/ Bundled capability/agent definitions ├── docs/ User & contributor docs ├── scripts/ bump-build, clear-quarantine, tauri-wrapper └── public/ Static assets served by Vite ``` --- ## Star History <div align="center"> <a href="https://github.com/abhiunix/AgentHarbor/stargazers"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/star-history-dark.svg" /> <img alt="Cumulative GitHub stars over time" src="docs/assets/star-history.svg" width="720" /> </picture> </a> </div> --- ## Contributing Contributions are welcome — bug fixes, new registry capabilities, provider analytics, or docs improvements. See [**CONTRIBUTING.md**](CONTRIBUTING.md) for the full guide: dev setup, code standards, adding registry entries, PR checklist, and commit conventions. --- ## License MIT — see [LICENSE](LICENSE).