claudelink 1.6.0 → 1.6.3

package/README.md

@@ -10,15 +10,13 @@
 [![Local-first](https://img.shields.io/badge/Local--First-no%20cloud-22c55e.svg?style=flat-square)](#local-first-security)
 
 
-![Focus. Build. Automate. Scale.](docs/assets/Command_grok.jpg)
-
 ClaudeLink is an open-source [MCP](https://modelcontextprotocol.io/) server that turns multiple AI coding agents — Claude Code, OpenAI Codex CLI, Google Gemini CLI, Block's Goose, or any MCP-compatible client — into a **single coordinated team**. Open four terminals, give each one a role, and they share a real-time message bus, a bulletin board, and a closed-loop autonomous pipeline that keeps them working together when you step away.
 
 **The name says "Claude" but ClaudeLink is model-agnostic.** Each CLI you plug in chooses its own backing model — and through Goose alone you can wire any of **25+ LLM providers**, putting hundreds of models within reach of the same mesh. A Claude reviewer talking to a Codex developer talking to a Gemini tester talking to a Llama-via-Ollama deep-thinker is a fully supported pattern. The mesh doesn't care; the LLM is somebody else's problem.
 
 You don't need to invent a multi-agent framework. You already have one.
 
-![ClaudeLink Command Center](docs/assets/command-center.png)
+> **Recommended terminal: [iTerm2](https://iterm2.com) (macOS).** ClaudeLink is developed and tested in iTerm2. Running several agents side by side works best with its split panes and tabs, and the autonomous features are built around it. tmux is supported but less tested. Apple Terminal is not recommended and has not been tested.
 
 ---
 
@@ -70,7 +68,7 @@ A single Goose terminal in your mesh can speak to whatever provider you point it
 
 This means **ClaudeLink isn't really "Claude" anymore** — it's the coordination plane, and the model space below it is essentially open. Want a Llama-3 reviewer running locally via Ollama, a Claude Sonnet implementer for hard reasoning, and a Groq-powered Llama for fast scaffolding? Spin up three Goose terminals (or a Goose + a Claude Code + a Codex), hand each one its role, and they share the same SQLite mesh. Pick the model for the job, on a per-agent basis, with no ClaudeLink-side configuration.
 
-> **What's the catch?** The auto-nudge layer that types `check for updates` into a terminal needs the CLI to be running in iTerm2 or tmux on macOS / Linux. Apple Terminal isn't supported (Accessibility permission we don't want to silently ask for). MCP messaging itself works regardless of terminal.
+> **What's the catch?** The auto-nudge layer that types `check for updates` into a terminal needs the CLI to be running in iTerm2 (recommended, tested) or tmux (supported, less tested) on macOS / Linux. Apple Terminal isn't supported (Accessibility permission we don't want to silently ask for). MCP messaging itself works regardless of terminal.
 
 Beyond the four flagged CLIs, **any MCP-compatible client can join** — point its MCP config at `claudelink-server`, add a copy of the multi-agent instructions to its project-instructions file. Roll your own and want a `--<your-cli>` flag? Open a PR with the install path; it's roughly an hour of work to add one.
 
@@ -297,7 +295,7 @@ ClaudeLink tools appear automatically. Messaging, inbox, bulletin board, and the
 
 ### 4. iTerm2 only — allow the one-time keystroke permission
 
-**Skip this entirely if you use tmux** (it needs zero setup) or if you only want the messaging/dashboard features (those need no permissions either). This step is only for the **autonomous keystroke layer** on **iTerm2** — the auto-nudge "check your inbox" pokes, auto-compact, and the Command Center's **Compact / Clear** buttons.
+**Skip this if you use tmux** (it needs no setup, though it is less tested than iTerm2) or if you only want the messaging/dashboard features (those need no permissions either). This step is only for the **autonomous keystroke layer** on **iTerm2** — the auto-nudge "check your inbox" pokes, auto-compact, and the Command Center's **Compact / Clear** buttons.
 
 Those work by having ClaudeLink's background watcher send iTerm2 standard **Apple Events** (the same public scripting API a `osascript` one-liner uses — no Accessibility, no kernel extensions). The first time it does, macOS asks for consent:
 
@@ -334,7 +332,7 @@ If you've been hesitant to wire AI agents together because every "multi-agent fr
 - Node.js 18+
 - One or more MCP-compatible clients: Claude Code, OpenAI Codex CLI, Google Gemini CLI, or Block's Goose
 - macOS or Linux (Windows works for messaging; auto-nudge requires tmux)
-- **For the autonomous keystroke layer on macOS:** tmux works with zero setup; iTerm2 needs a one-time Automation permission ([step 4 below](#4-iterm2-only--allow-the-one-time-keystroke-permission)). Messaging + the Command Center need no permissions on any terminal.
+- **Terminal: iTerm2 recommended.** It is what ClaudeLink is developed and tested in, and it needs a one-time Automation permission for the autonomous keystroke layer ([step 4 below](#4-iterm2-only--allow-the-one-time-keystroke-permission)). tmux also works with no setup, but is less tested. Messaging + the Command Center need no permissions on any terminal.
 
 ---
 
@@ -352,6 +350,7 @@ The Command Center is a local web UI at `http://127.0.0.1:7878` — a live conso
 | **Auto-nudge** | Global on/off + tick interval (1–120 min). Scheduler only fires for terminals that *actually have* unread mail — no wasted Claude turns. |
 | **Recovery Watcher** *(v1.4.0+)* | Detects Anthropic API rate-limit / overload errors in agent terminals and types a recovery prompt automatically. Configurable poll interval, cooldown, and escalate-to-desktop-notification threshold. See [Recovery Watcher](#3-recovery-watcher-api-error-auto-recovery) below. |
 | **Fleet — live context** *(v1.5.0+)* | Per-agent context occupancy, $/turn, handoff freshness and last-signal age, sorted most-urgent-first. Per-row **Copy prompt**, **Compact**, and **Clear** — an on-demand, consent-gated handshake to act on a heavy terminal. See [Fleet live context](#fleet-live-context--on-demand-compaction-v150) below. |
+| **Plan Usage** *(v1.6.0+, opt-in)* | Your Claude subscription's real quota — session (5-hour), weekly, and frontier-model weekly pool — as live meters with reset countdowns, without opening Claude Desktop → Settings. Off by default; `claudelink usage --on` to enable. See [Plan Usage meter](#plan-usage-meter--see-your-subscription-quota-v160-opt-in) below. |
 | **Recent messages** | Live feed of the last several messages across all agents, with priority and unread badges. |
 
 The page auto-refreshes every 2 seconds. **Kill all servers** in the header drops the entire mesh in one click.
@@ -397,6 +396,37 @@ Agents opt into the protection by calling `signal_checkpoint` at natural rest po
 
 ---
 
+## Plan Usage meter — see your subscription quota *(v1.6.0, opt-in)*
+
+Running a fleet of agents spends your Claude subscription quota fast — and the only built-in way to see where you stand (the 5-hour session window, the weekly ceiling, the separate weekly pool some plans have for the newest frontier model) is buried in Claude Desktop → Settings → Usage. When you're pacing six terminals against a limit that resets at 4 a.m., that's not a workflow.
+
+The **Plan Usage** tile on the Command Center's Overview tab shows three live meters — **Session (5h)**, **Weekly (7d)**, and the **frontier-model weekly pool** — each with utilization %, a color ramp as you approach the limit, and a countdown to its reset. Off by default; nothing runs until you opt in:
+
+```bash
+claudelink usage --on     # start the local passthrough proxy (127.0.0.1:8788)
+claudelink usage          # status: proxy state + last capture
+claudelink usage --off    # stop it
+```
+
+**How it works.** The command starts a transparent passthrough proxy on `127.0.0.1:8788`. Point a terminal's `ANTHROPIC_BASE_URL` at it and every response coming back from `api.anthropic.com` — which already carries `anthropic-ratelimit-unified-*` headers describing your plan's real windows — gets its rate-limit headers scraped into `~/.claudelink/quota.json`. The Command Center reads that file and renders the meters. That's the whole trick: the data was in every response all along; ClaudeLink just makes it visible.
+
+Wire a terminal per-shell, ephemerally:
+
+```bash
+ANTHROPIC_BASE_URL="http://127.0.0.1:8788" claude
+```
+
+> **Do not** bake `ANTHROPIC_BASE_URL` into `~/.claude/settings.json` or your shell profile. If the proxy isn't running, every session pointed at it hangs on connection-refused. An ephemeral per-shell export (or a small shell function that checks the proxy is alive first) fails safe.
+
+**Security contract** — this is an auth-path component, so the rules are strict and the code is short enough to audit in one sitting:
+
+- Your auth token is **forwarded verbatim, never read, parsed, or logged**.
+- Only **response** rate-limit headers are captured — request and response bodies pass through untouched.
+- Binds to `127.0.0.1` only. Fail-open: if header parsing ever breaks, your traffic still flows.
+- **Default OFF.** No proxy process exists until you run `claudelink usage --on`.
+
+---
+
 ## Available tools
 
 Once connected, every agent session — Claude Code, Codex CLI, Gemini CLI, Goose, or any other MCP client — gains these MCP tools:
@@ -427,6 +457,9 @@ claudelink ui --stop                  # stop the Command Center
 claudelink install-hooks              # install autonomous-reply hooks (project)
 claudelink install-hooks --global     # install hooks in ~/.claude/settings.json
 claudelink install-hooks --uninstall  # remove ClaudeLink hooks
+claudelink usage --on                 # start the Plan Usage quota proxy (opt-in)
+claudelink usage                      # quota proxy status + last capture
+claudelink usage --off                # stop the quota proxy
 claudelink reset                      # clear all data (fresh start)
 claudelink help                       # full help
 ```
@@ -448,11 +481,11 @@ The scheduler is **smart**: the SQL filter only nudges terminals with unread mai
 
 | Terminal | Mechanism | Permissions |
 |---|---|---|
-| **tmux** | `tmux send-keys -t <pane>` | none |
-| **iTerm2** | `osascript` matched by tty | one-time macOS **Automation** grant ([setup](#4-iterm2-only--allow-the-one-time-keystroke-permission)) |
+| **iTerm2** (recommended, tested) | `osascript` matched by tty | one-time macOS **Automation** grant ([setup](#4-iterm2-only--allow-the-one-time-keystroke-permission)) |
+| **tmux** (supported, less tested) | `tmux send-keys -t <pane>` | none |
 | **Apple Terminal** | unsupported (would need Accessibility) | not silently prompted |
 
-> This permission applies **only** to the autonomous keystroke layer (auto-nudge, auto-compact, the Command Center's Compact/Clear buttons). Plain messaging, `read_inbox`, and the dashboard work on any terminal with no permissions. Running inside **tmux** avoids the iTerm2 grant entirely.
+> This permission applies **only** to the autonomous keystroke layer (auto-nudge, auto-compact, the Command Center's Compact/Clear buttons). Plain messaging, `read_inbox`, and the dashboard work on any terminal with no permissions. Running inside **tmux** avoids the iTerm2 grant entirely, though tmux is less tested than iTerm2.
 
 When the keystroke arrives, the receiving CLI treats it as normal user input and the agent calls `read_inbox` via its own tool — fully trusted path. **This works identically for Claude Code, Codex CLI, Gemini CLI, and Goose** because the keystroke is the lowest common denominator every terminal app handles the same.
 
@@ -523,8 +556,6 @@ flowchart LR
 
 When a recovery prompt fires, the receiving CLI treats it as a normal user prompt, the agent calls `read_inbox` and resumes — the same path that already works for routine auto-nudge.
 
-![Recovery Watcher in the Command Center](docs/assets/recovery-watcher.png)
-
 #### Configuration
 
 Configurable directly from the Command Center (Recovery Watcher panel) or via `~/.claudelink/recovery-watcher.json`:
@@ -746,7 +777,7 @@ If you'd like a one-command `--<your-cli>` flag, [open an issue](https://github.
 
 ### Does this work on Windows?
 
-Messaging works on any platform with Node 18+. The auto-nudge scheduler currently dispatches to tmux and iTerm2 only; on Windows you'd run inside WSL + tmux for the full autonomous loop.
+Messaging works on any platform with Node 18+. The auto-nudge scheduler currently dispatches to tmux and iTerm2 only; on Windows you'd run inside WSL + tmux for the full autonomous loop (untested).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudelink",
-  "version": "1.6.0",
+  "version": "1.6.3",
   "description": "The hub where your AI agents connect. Multi-terminal Claude Code agent communication via MCP.",
   "main": "./dist/index.js",
   "bin": {