vinzdg/codenotch

Codenotch – a tiny on‑screen monitor for AI‑coding‑assistant usage limits

What it is

• A macOS (and Windows via a Rust/Tauri port) utility that lives as a small “notch” pinned to any screen edge. Each ring in the notch represents a coding‑assistant provider (Claude, Cursor, Codex, Ollama, etc.) and shows how much of the provider’s usage quota has been consumed, when the quota resets, and whether the assistant is currently busy, finished, or waiting for you.

Why you might want it

• If you regularly use multiple AI‑coding tools that have daily/weekly token limits, Codenotch gives you a glance‑at‑a‑glance view so you don’t unexpectedly hit a quota.
• It also alerts you when a limit crosses 80 % or hits 100 %.
• The UI is unobtrusive: a thin pill that expands on hover, with optional always‑show or menu‑bar modes.

Key features (as described in the README)

• Provider support – Reads usage data from dozens of services, both cloud (Claude, DeepSeek, Antigravity, OpenCode, GitHub Copilot, etc.) and local runtimes (Ollama, LM Studio, oMLX). Most providers reuse credentials already stored by the respective CLI or desktop app; a few (DeepSeek, MiniMax, QianwenAI) require an explicit sign‑in via an embedded WebView.
• Live status – Rings spin while a session is busy, pulse amber when blocked, and show a tooltip with current limit windows, reset times, and session state.
• Multi‑account handling – Detects separate configuration directories (e.g., ~/.claude‑work) and creates separate rings for each account.
• Phone companion – An iOS/Android app can mirror the same usage percentages over a local‑network QR‑code pairing.
• Custom endpoints – You can add arbitrary OpenAI‑compatible, Anthropic, or Gemini endpoints and manually enter usage data.
• Speed & thinking metrics – For local models (Ollama, LM Studio, oMLX) you can enable measurement of tokens‑per‑second and “thinking” time, without sending any prompts to Codenotch.
• Highly configurable UI – Choose edge placement, size, colour, always‑show vs. hover‑only, dock/menu‑bar visibility, and which providers appear in the menu‑bar summary.
• Alerts – macOS notifications fire once when a provider’s usage crosses 80 % or reaches 100 %, with per‑provider mute controls.
• Updates – Signed, notarized releases for macOS; a Windows installer (unsigned) for the Tauri port; preview builds for the main branch.

Installation

• macOS – Download the latest Codenotch.dmg from the releases page. The app is signed and notarized; after dragging it to Applications you may need to clear the quarantine flag (xattr -dr com.apple.quarantine /Applications/Codenotch.app).
• Windows – Download Codenotch-Setup.exe; the installer runs without admin rights and will fetch WebView2 if needed.
• From source – The README points to a Building section (not reproduced here) for compiling the Swift macOS app or the Rust/Tauri Windows version.

How it works under the hood

• For cloud providers it queries the same usage endpoints that the official CLI or desktop app uses, re‑using OAuth tokens, API keys, or keychain entries that already exist on the machine.
• For local runtimes it discovers running servers, reads status sockets or log files (~/.lmstudio/server-logs, ~/.omlx/logs/server.log), and extracts token counts and speed metrics. No prompt or response data is ever transmitted to Codenotch.
• The phone app communicates locally over the same network; pairing uses a single‑use QR‑code that expires after five minutes.

License

• MIT (as indicated by the badge in the README).

Who might use it

• Developers who juggle several AI‑coding assistants and need to stay within quota limits.
• Teams that want a shared visual cue for when an assistant is waiting on user input.
• Anyone who prefers a lightweight, always‑visible status bar rather than opening each provider’s dashboard.

---

All information above is taken directly from the project's README; no additional features have been inferred.