{"id":51457415,"url":"https://github.com/shw1606/token-grass","last_synced_at":"2026-07-06T02:00:27.626Z","repository":{"id":368643502,"uuid":"1286144363","full_name":"shw1606/token-grass","owner":"shw1606","description":"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 \u0026 open source.","archived":false,"fork":false,"pushed_at":"2026-07-01T13:46:34.000Z","size":3551,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T15:25:53.086Z","etag":null,"topics":["anthropic","claude","claude-code","contribution-graph","developer-tools","heatmap","homescreen-widget","ios","ios-widget","macos","menubar","swift","swiftui","usage-tracker","widgetkit"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shw1606.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-01T13:40:58.000Z","updated_at":"2026-07-01T13:47:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shw1606/token-grass","commit_stats":null,"previous_names":["shw1606/token-grass"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shw1606/token-grass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shw1606%2Ftoken-grass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shw1606%2Ftoken-grass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shw1606%2Ftoken-grass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shw1606%2Ftoken-grass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shw1606","download_url":"https://codeload.github.com/shw1606/token-grass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shw1606%2Ftoken-grass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35175119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude","claude-code","contribution-graph","developer-tools","heatmap","homescreen-widget","ios","ios-widget","macos","menubar","swift","swiftui","usage-tracker","widgetkit"],"created_at":"2026-07-06T02:00:21.056Z","updated_at":"2026-07-06T02:00:27.489Z","avatar_url":"https://github.com/shw1606.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TokenGrass 🌱\n\n\u003e Your Claude usage as a GitHub-style contribution graph, on your iPhone home-screen widget. Free, open source.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/app-light.png\" width=\"270\" alt=\"TokenGrass, light mode\"\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"docs/screenshots/app-dark.png\" width=\"270\" alt=\"TokenGrass, dark mode\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eDemo data shown, running on the iOS 26 simulator.\u003c/sub\u003e\u003c/p\u003e\n\nTokenGrass turns your daily Claude usage into a familiar contribution heatmap and\nputs it **directly on your home screen as a widget**, glance, don't tap. No paywall.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/widget-small.png\" width=\"150\" alt=\"Small (2×2) grass widget\"\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"docs/screenshots/widget-medium.png\" width=\"322\" alt=\"Medium (4×2) grass widget\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eThe home-screen widget in both sizes, pixel-matched to GitHub's contribution graph, in Claude orange. Demo data.\u003c/sub\u003e\u003c/p\u003e\n\n## Get started\n\nTokenGrass comes in two parts:\n\n1. **iPhone app + widget** — from the App Store _(in review)_.\n2. **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.\n\nThen 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.\n\n\u003e **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.\n\n## How it works\n\nAnthropic doesn't let third-party apps log in as you or read your subscription\nusage from the phone, so the data is collected on your Mac (where you're already\nsigned into Claude Code) and synced to the phone, the same shape as the validated\n\"Usage for Claude\", plus the home-screen **grass widget** it lacks.\n\n```\n[Mac companion]  reads Claude Code's keychain token → polls /api/oauth/usage\n      │          → accumulates daily usage intensity → renders grass\n      ▼  iCloud (key-value, a few KB)\n[iPhone app]  mirrors into the App Group → [Widget] renders the grass\n```\n\n- **No backend, no server, no accounts.** Apple's iCloud does the sync; the token\n  never leaves your Mac's Keychain.\n- The grass fills **forward** from when you install it (Anthropic exposes current\n  rate-limit utilization, not a backfillable daily history).\n\n**Requires** Claude Code installed and logged in on the Mac (the data source).\n\n## Project layout\n\n```\ntoken-grass/\n├─ TokenGrassCore/      # Pure logic (Foundation-only), models, grass math, accumulator, OAuth/usage parsing. Unit-tested.\n│  └─ TokenGrassPoll/   #   dev CLI: validate keychain → usage → accumulate headlessly\n├─ SharedUI/            # SwiftUI grass views (cross-platform) + iCloud store\n├─ TokenGrass/          # iOS app target (display + iCloud pull)\n├─ TokenGrassWidget/    # iOS widget extension (WidgetKit)\n├─ TokenGrassMac/       # macOS menu-bar companion (the data engine)\n├─ docs/                # DESIGN / ROADMAP / APPSTORE / ARCHITECTURE\n└─ project.yml          # XcodeGen project definition (source of truth)\n```\n\nDesign choice: all grass math lives in `TokenGrassCore`, a plain Swift package with\n**no SwiftUI/WidgetKit imports**, so it compiles and unit-tests without Xcode.\n\n## Build\n\nRequires Xcode 17+ and [XcodeGen](https://github.com/yonaskolb/XcodeGen).\n\n```bash\nbrew install xcodegen        # once\nxcodegen generate            # creates TokenGrass.xcodeproj from project.yml\nopen TokenGrass.xcodeproj     # set your signing team, then run TokenGrassMac / TokenGrass\n```\n\n| Target | Bundle ID | Distribution |\n|---|---|---|\n| iOS app | `dev.yulebuilds.tokengrass` | App Store |\n| iOS widget | `dev.yulebuilds.tokengrass.widget` | (with the app) |\n| macOS companion | `dev.yulebuilds.tokengrass.mac` | Direct download (notarized) |\n\nApp Group `group.dev.yulebuilds.tokengrass` · min iOS 17 / macOS 14. iCloud sync and\nApp Store / TestFlight distribution require the paid Apple Developer Program.\n\n## Test\n\nThe core logic is verified headlessly (no Xcode project needed):\n\n```bash\ncd TokenGrassCore \u0026\u0026 swift test\n```\n\n## Disclaimer\n\nTokenGrass is an independent, open-source project and is not affiliated with,\nendorsed by, or sponsored by Anthropic. \"Claude\" and \"Claude Code\" are trademarks\nof Anthropic. It uses unofficial endpoints and your existing Claude Code login, and\nmay stop working if Anthropic changes them.\n\n## Privacy\n\nTokenGrass collects nothing, no account, no backend, no analytics. Your Claude\ncredentials never leave your Mac; only a few KB of daily usage summary syncs\nbetween your own devices via iCloud. See [PRIVACY.md](PRIVACY.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshw1606%2Ftoken-grass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshw1606%2Ftoken-grass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshw1606%2Ftoken-grass/lists"}