https://github.com/shw1606/token-grass
Your Claude Code usage as a GitHub-style contribution grass on your iPhone home screen — a WidgetKit widget fed by a macOS menu-bar companion. Free & open source.
https://github.com/shw1606/token-grass
anthropic claude claude-code contribution-graph developer-tools heatmap homescreen-widget ios ios-widget macos menubar swift swiftui usage-tracker widgetkit
Last synced: 2 days ago
JSON representation
Your Claude Code usage as a GitHub-style contribution grass on your iPhone home screen — a WidgetKit widget fed by a macOS menu-bar companion. Free & open source.
- Host: GitHub
- URL: https://github.com/shw1606/token-grass
- Owner: shw1606
- License: mit
- Created: 2026-07-01T13:40:58.000Z (7 days ago)
- Default Branch: main
- Last Pushed: 2026-07-01T13:46:34.000Z (7 days ago)
- Last Synced: 2026-07-01T15:25:53.086Z (7 days ago)
- Topics: anthropic, claude, claude-code, contribution-graph, developer-tools, heatmap, homescreen-widget, ios, ios-widget, macos, menubar, swift, swiftui, usage-tracker, widgetkit
- Language: Swift
- Size: 3.39 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: docs/ROADMAP.md
Awesome Lists containing this project
README
# TokenGrass 🌱
> Your Claude usage as a GitHub-style contribution graph, on your iPhone home-screen widget. Free, open source.
Demo data shown, running on the iOS 26 simulator.
TokenGrass turns your daily Claude usage into a familiar contribution heatmap and
puts it **directly on your home screen as a widget**, glance, don't tap. No paywall.
The home-screen widget in both sizes, pixel-matched to GitHub's contribution graph, in Claude orange. Demo data.
## Get started
TokenGrass comes in two parts:
1. **iPhone app + widget** — from the App Store _(in review)_.
2. **Free Mac app** — [**⬇️ Download for Mac**](https://github.com/shw1606/token-grass/releases/latest). Open it once. It lives in your menu bar, reads your Claude Code usage, and syncs to your phone over iCloud.
Then add the TokenGrass widget to your home screen. Your grass fills in as you use Claude Code. No account, no servers, and your Claude login never leaves your Mac.
> **You'll need:** a Mac with [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and logged in, and the same iCloud account on your Mac and iPhone.
## How it works
Anthropic doesn't let third-party apps log in as you or read your subscription
usage from the phone, so the data is collected on your Mac (where you're already
signed into Claude Code) and synced to the phone, the same shape as the validated
"Usage for Claude", plus the home-screen **grass widget** it lacks.
```
[Mac companion] reads Claude Code's keychain token → polls /api/oauth/usage
│ → accumulates daily usage intensity → renders grass
▼ iCloud (key-value, a few KB)
[iPhone app] mirrors into the App Group → [Widget] renders the grass
```
- **No backend, no server, no accounts.** Apple's iCloud does the sync; the token
never leaves your Mac's Keychain.
- The grass fills **forward** from when you install it (Anthropic exposes current
rate-limit utilization, not a backfillable daily history).
**Requires** Claude Code installed and logged in on the Mac (the data source).
## Project layout
```
token-grass/
├─ TokenGrassCore/ # Pure logic (Foundation-only), models, grass math, accumulator, OAuth/usage parsing. Unit-tested.
│ └─ TokenGrassPoll/ # dev CLI: validate keychain → usage → accumulate headlessly
├─ SharedUI/ # SwiftUI grass views (cross-platform) + iCloud store
├─ TokenGrass/ # iOS app target (display + iCloud pull)
├─ TokenGrassWidget/ # iOS widget extension (WidgetKit)
├─ TokenGrassMac/ # macOS menu-bar companion (the data engine)
├─ docs/ # DESIGN / ROADMAP / APPSTORE / ARCHITECTURE
└─ project.yml # XcodeGen project definition (source of truth)
```
Design choice: all grass math lives in `TokenGrassCore`, a plain Swift package with
**no SwiftUI/WidgetKit imports**, so it compiles and unit-tests without Xcode.
## Build
Requires Xcode 17+ and [XcodeGen](https://github.com/yonaskolb/XcodeGen).
```bash
brew install xcodegen # once
xcodegen generate # creates TokenGrass.xcodeproj from project.yml
open TokenGrass.xcodeproj # set your signing team, then run TokenGrassMac / TokenGrass
```
| Target | Bundle ID | Distribution |
|---|---|---|
| iOS app | `dev.yulebuilds.tokengrass` | App Store |
| iOS widget | `dev.yulebuilds.tokengrass.widget` | (with the app) |
| macOS companion | `dev.yulebuilds.tokengrass.mac` | Direct download (notarized) |
App Group `group.dev.yulebuilds.tokengrass` · min iOS 17 / macOS 14. iCloud sync and
App Store / TestFlight distribution require the paid Apple Developer Program.
## Test
The core logic is verified headlessly (no Xcode project needed):
```bash
cd TokenGrassCore && swift test
```
## Disclaimer
TokenGrass is an independent, open-source project and is not affiliated with,
endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks
of Anthropic. It uses unofficial endpoints and your existing Claude Code login, and
may stop working if Anthropic changes them.
## Privacy
TokenGrass collects nothing, no account, no backend, no analytics. Your Claude
credentials never leave your Mac; only a few KB of daily usage summary syncs
between your own devices via iCloud. See [PRIVACY.md](PRIVACY.md).
## License
[MIT](LICENSE)