Skip to content

Commit 362e2b8

Browse files
kvnwolfkvnwolf
committed
docs: launch-ready README with hero mark, MIT license, and capture guide
Rewrite the scaffold README into a launch-facing page: hero eye (hand-authored SVG from the tray geometry), moods table, Homebrew install, privacy/trust section, dev setup. Add MIT LICENSE and assets/CAPTURE.md (demo GIF + popover screenshot guide). README references assets/demo.gif + assets/popover.png, added at launch.
1 parent 1612eb1 commit 362e2b8

4 files changed

Lines changed: 193 additions & 7 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Kevin Wolf
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 119 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,129 @@
1-
# mad-eye 👁️
1+
<div align="center">
22

3-
Mad-Eye Moody in your macOS menubar, watching your Claude subscription usage limits. The Eye gets more agitated as you approach a limit; click it for the detailed Gauges.
3+
<img src="assets/hero.svg" alt="mad-eye" width="140" height="140" />
44

5-
## Develop
5+
# mad-eye
6+
7+
**Your Claude usage limits, watching you back.**
8+
9+
A macOS menubar app that shows your Claude subscription usage as an animated eye —
10+
[Mad-Eye Moody](https://harrypotter.fandom.com/wiki/Alastor_Moody) style. The Eye gets more
11+
agitated as you approach a limit, and its ring shatters when you hit 100%. No numbers in your
12+
menubar — just an Eye that tells you how close you are at a glance.
13+
14+
[![CI](https://github.com/kvnwolf/mad-eye/actions/workflows/ci.yml/badge.svg)](https://github.com/kvnwolf/mad-eye/actions/workflows/ci.yml)
15+
&nbsp;![macOS](https://img.shields.io/badge/macOS-Monterey%2B-000000?logo=apple&logoColor=white)
16+
&nbsp;![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
17+
&nbsp;![Built with Tauri](https://img.shields.io/badge/built%20with-Tauri-24C8DB?logo=tauri&logoColor=white)
18+
19+
<br/>
20+
21+
<!-- Add assets/demo.gif before launch — see assets/CAPTURE.md -->
22+
<img src="assets/demo.gif" alt="mad-eye animating in the menubar" width="640" />
23+
24+
</div>
25+
26+
---
27+
28+
## Why
29+
30+
If you live in Claude Code, you want an ambient sense of *"how close am I to my limit?"*
31+
without opening a dashboard. mad-eye puts that in your menubar as a single Eye:
32+
33+
- a **calm, slow glance** when you've got headroom,
34+
- a **frantic dart** when you're about to run out,
35+
- a **cracked, frozen stare** when you've hit the wall.
36+
37+
Click it for the detailed gauges.
38+
39+
## The moods
40+
41+
The Eye tracks **one** gauge — your **Session** limit by default. Click any gauge in the
42+
popover to make it the one that drives the Eye (it remembers your choice).
43+
44+
| Usage | Mood | The Eye… |
45+
|:--:|:--|:--|
46+
| `< 50%` | 😌 **Calm** | slow, wide glances |
47+
| `< 80%` | 😐 **Nervous** | quicker, tighter darts |
48+
| `< 95%` | 😰 **Paranoid** | fast, wide, restless |
49+
| `< 100%` | 😱 **Frantic** | can't sit still |
50+
| `100%` | 💥 **Shattered** | the ring cracks, the eye freezes |
51+
52+
<div align="center">
53+
<!-- Add assets/popover.png before launch — see assets/CAPTURE.md -->
54+
<img src="assets/popover.png" alt="the popover with usage gauges" width="360" />
55+
</div>
56+
57+
## Install
58+
59+
### Homebrew (recommended)
660

761
```sh
62+
brew install --cask kvnwolf/tap/mad-eye
63+
```
64+
65+
### Manual
66+
67+
Download the latest `.dmg` from [**Releases**](https://github.com/kvnwolf/mad-eye/releases),
68+
open it, and drag **mad-eye** into Applications.
69+
70+
> It's an unsigned build, so the first time: **right-click → Open** (or run
71+
> `xattr -dr com.apple.quarantine /Applications/mad-eye.app`). Homebrew does this for you.
72+
73+
## Requirements
74+
75+
- **macOS Monterey or later.**
76+
- **[Claude Code](https://claude.com/claude-code) installed and logged in.** mad-eye reads your
77+
usage from the same credentials Claude Code stores — no Claude Code, no data (the Eye goes dark).
78+
79+
## Privacy & trust
80+
81+
mad-eye reads your Claude OAuth token from the macOS Keychain **(read-only)** and calls
82+
Anthropic's usage endpoint — the same data behind Claude Code's `/usage` panel. That's the whole
83+
story:
84+
85+
- 🔒 **Your token never leaves your Mac** except to `api.anthropic.com`.
86+
- 🚫 **No telemetry, no analytics, no servers.** There's no backend — just your Mac and Anthropic.
87+
- 👁 **It never writes or refreshes your credentials** — strictly read-only. If the token expires,
88+
the Eye just goes blind until Claude Code refreshes it.
89+
- On first launch macOS asks to read the *"Claude Code-credentials"* Keychain item — click
90+
**Always Allow**.
91+
92+
Don't take my word for it — read the [Keychain read](src-tauri/src/keychain/read.rs) and the
93+
[usage fetch](src-tauri/src/usage/client.rs) yourself. That's the whole point of open-sourcing it.
94+
95+
## How it works
96+
97+
- A **Rust core** renders the Eye directly to a monochrome template tray icon (tiny-skia, no image
98+
assets) and animates the pupil ~30fps by mood.
99+
- It polls Anthropic's OAuth usage endpoint (undocumented — a future change on their side could
100+
break it) and maps the limits to gauges + a mood.
101+
- The **popover** is a native frosted panel — vanilla TypeScript, macOS vibrancy, theme-aware.
102+
- It's a **ghost app**: no Dock icon, no ⌘-Tab. Launch-at-login and Quit live in the Eye's
103+
right-click menu.
104+
105+
## Development
106+
107+
```sh
108+
git clone https://github.com/kvnwolf/mad-eye
109+
cd mad-eye
8110
bun install
9-
bun tauri dev # native app: menubar Eye + Popover
10-
bunx dobby dev # Popover UI only, in the browser
111+
bun tauri dev # the native app: menubar Eye + popover
11112
```
12113

13-
## Build
114+
Drive the Eye through every mood without burning real usage:
14115

15116
```sh
16-
bun tauri build
117+
MAD_EYE_FAKE_PCT=97 bun tauri dev # 40 calm · 70 nervous · 90 paranoid · 97 frantic · 100 shattered
17118
```
119+
120+
Releases are cut with the [`release`](.claude/skills/release/SKILL.md) skill (universal DMG →
121+
GitHub Release → Homebrew cask).
122+
123+
## License
124+
125+
[MIT](LICENSE) © Kevin Wolf
126+
127+
---
128+
129+
<div align="center"><sub>Built with 🦀 Rust + <a href="https://tauri.app">Tauri</a> · not affiliated with Anthropic</sub></div>

‎assets/CAPTURE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Capturing the launch visuals
2+
3+
The README references two images — drop them in this folder with these exact names.
4+
5+
## 1. `demo.gif` — the hero (and your tweet's video)
6+
7+
A short (5–10s) screen recording of the Eye in the menubar: let it climb through the moods and
8+
shatter, then click it to open the popover.
9+
10+
**Record it**
11+
- Tool: [Kap](https://getkap.co) (free, open source, exports GIF **and** MP4) — or QuickTime → New Screen Recording.
12+
- Drive the moods on demand instead of waiting for real usage (the Eye reads `MAD_EYE_FAKE_PCT`):
13+
```sh
14+
MAD_EYE_FAKE_PCT=40 bun tauri dev # calm
15+
MAD_EYE_FAKE_PCT=90 bun tauri dev # paranoid
16+
MAD_EYE_FAKE_PCT=97 bun tauri dev # frantic
17+
MAD_EYE_FAKE_PCT=100 bun tauri dev # shattered
18+
```
19+
Record a zoomed-in region around the menubar Eye so it reads at tweet size.
20+
- Click the Eye to reveal the frosted popover with the gauges.
21+
22+
**Export**
23+
- **`demo.gif`** for the README — ~640px wide, keep it **under 10 MB** (GitHub's cap; smaller loops load faster).
24+
- **`demo.mp4`** to attach to the tweet — X prefers native video (autoplays, loops, far more reach than a link). Don't commit the MP4 to the README; GitHub won't autoplay a committed MP4. Attach it straight to the tweet.
25+
26+
## 2. `popover.png` — the detail shot
27+
28+
Open the popover, then **⌘⇧4 → Space → click the popover** to grab just that window (with its shadow). Save as `popover.png`.
29+
30+
## Repo social preview (the X link-card thumbnail)
31+
32+
If you paste the repo link in the tweet, X shows a card from the image at
33+
**repo → Settings → General → Social preview** (1280×640). A still of the demo — Eye + a sliver of
34+
the popover — works well. (If you attach the MP4 directly instead, the video is the star and this
35+
matters less.)

‎assets/hero.svg‎

Lines changed: 18 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)