{"id":46080552,"url":"https://github.com/alexanderheffernan/rashun","last_synced_at":"2026-03-15T15:00:41.026Z","repository":{"id":341085117,"uuid":"1168838449","full_name":"AlexanderHeffernan/Rashun","owner":"AlexanderHeffernan","description":"A macOS menu bar app that tracks your free AI coding tool usage so you don't burn through your quota before the month is over.","archived":false,"fork":false,"pushed_at":"2026-03-09T09:11:09.000Z","size":2504,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-09T12:14:07.185Z","etag":null,"topics":["ai","dev-tools","macos","open-source","swift","usage-tracking"],"latest_commit_sha":null,"homepage":"https://rashun.alexheffernan.dev","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/AlexanderHeffernan.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":null,"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-02-27T21:21:50.000Z","updated_at":"2026-03-09T09:00:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AlexanderHeffernan/Rashun","commit_stats":null,"previous_names":["alexanderheffernan/rashun"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/AlexanderHeffernan/Rashun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderHeffernan%2FRashun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderHeffernan%2FRashun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderHeffernan%2FRashun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderHeffernan%2FRashun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexanderHeffernan","download_url":"https://codeload.github.com/AlexanderHeffernan/Rashun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexanderHeffernan%2FRashun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30545040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-15T14:38:58.992Z","status":"ssl_error","status_checked_at":"2026-03-15T14:38:29.659Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","dev-tools","macos","open-source","swift","usage-tracking"],"created_at":"2026-03-01T15:30:44.712Z","updated_at":"2026-03-15T15:00:41.020Z","avatar_url":"https://github.com/AlexanderHeffernan.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"icon.jpg\" width=\"128\" alt=\"Rashun app icon\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eRashun\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA usage tracker for AI coding tools: macOS menu bar app + cross-platform CLI.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-install\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/install-one_command-935AFD?style=for-the-badge\" alt=\"Install\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/app-macOS_14%2B-000?style=for-the-badge\u0026logo=apple\u0026logoColor=white\" alt=\"macOS app\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/CLI-macOS%20%7C%20Linux%20%7C%20Windows-1f6feb?style=for-the-badge\" alt=\"Cross-platform CLI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/swift-6.2-F05138?style=for-the-badge\u0026logo=swift\u0026logoColor=white\" alt=\"Swift 6.2\" /\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-0DE4D1?style=for-the-badge\" alt=\"MIT License\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nIf you juggle multiple AI coding tools — Amp, GitHub Copilot, Codex, Gemini CLI — keeping track of how much quota you have left across all of them is a pain. You're deep in a project, it's day 22 of the month, and suddenly one of them cuts you off.\n\nRashun sits in your menu bar, polls each source on a timer, and gives you a single at-a-glance view of your remaining quota. It charts your usage history over time, forecasts when you'll run out, and nudges you with notifications before you hit zero.\n\nRashun is currently rolling out cross-platform support in phases:\n\n- **Today:** full macOS app experience + CLI on macOS/Linux/Windows.\n- **In progress:** extracting more shared logic into `RashunCore` so future Linux/Windows app shells can be added with minimal OS-specific code.\n\n### Why I built this\n\nAs a student relying on the free tiers of multiple AI coding tools, I kept running into the same problem — burning through one tool's quota without realizing it, then scrambling to figure out which others I had left. I built Rashun so I'd never have to guess again.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/alexanderheffernan/rashun/main/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://raw.githubusercontent.com/alexanderheffernan/rashun/main/scripts/install/windows.ps1 | iex\n```\n\n---\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"340\"\u003e\n      \u003cimg src=\"screenshots/menu-bar.png\" width=\"320\" alt=\"Menu bar dropdown showing source usage\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003eMenu bar dropdown\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"screenshots/usage-history.png\" width=\"560\" alt=\"Usage History window with chart and forecasts\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003eUsage history with forecasts\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" colspan=\"2\"\u003e\n      \u003cimg src=\"screenshots/preferences.png\" width=\"660\" alt=\"Preferences window — Sources tab\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003ePreferences — Sources \u0026 notification rules\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Features\n\n- **Menu bar at a glance** — Ring icons show remaining quota per metric, with your choice of monochrome or source-branded colors. Display the AI source's logo or the overall remaining usage percentage in the center.\n- **Four sources built in** — Ships with support for **Amp Free**, **GitHub Copilot**, **Codex** (tested with free-tier weekly rate limits only), and **Gemini CLI** (with per-model metric tracking for Gemini). Enable whichever ones you use.\n- **Usage history \u0026 charts** — A dedicated window charts your usage trends over time with selectable ranges (Day, Week, Month, All). Toggle individual sources on and off in the legend.\n- **Forecasting** — Each source projects when you'll run out based on your burn rate. Amp models its regenerating quota; Copilot, Codex, and Gemini project against their reset windows. Forecast curves appear as dashed lines on the chart alongside a summary of insights.\n- **Smart notifications** — Get alerted when remaining usage drops below a threshold, when you're burning through tokens unusually fast, or when you're on pace to run out before reset. All thresholds are configurable.\n- **Source health monitoring** — If a source fails to fetch, Rashun tracks consecutive failures, surfaces actionable error messages, and shows warning indicators in the menu dropdown and Preferences.\n- **Auto-updates** — Rashun checks GitHub releases every 6 hours and notifies you when a new version is available. One-click install \u0026 restart from the Updates tab in Preferences.\n- **Cross-platform CLI** — Query all sources or a specific source from terminal with optional JSON output (`rashun`, `rashun \u003csource\u003e`, `rashun --json`).\n- **Launch at login** — Optionally start Rashun when you sign in to your Mac.\n- **Data management** — Export and import usage history as JSON. Delete history by source, date range, or entirely.\n- **Configurable polling** — Set how often Rashun checks your usage (default: every 2 minutes).\n- **Branded native UI** — A polished dark theme with source logos, card-based layouts, and segmented controls — all built with SwiftUI and AppKit.\n- **Extensible by design** — Adding a new AI source is a single Swift file in `Sources/AISources/`. The build script auto-discovers it.\n\n---\n\n## How It Works\n\nRashun polls each enabled source on a timer. For each source, it fetches current usage data (remaining quota vs. total limit), calculates the percentage remaining, records a snapshot for historical tracking, and updates the menu bar icon. It evaluates notification rules against current and historical data, and generates per-source forecasts that are rendered as dashed projections on the usage chart.\n\nThe CLI uses the same `RashunCore` sources and models, so command-line output and app output are consistent.\n\n| Source | Metrics | How it fetches data |\n|---|---|---|\n| **Amp** | Amp Free | Runs `~/.amp/bin/amp usage` and parses `Amp Free: $x/$y remaining` |\n| **Copilot** | Premium Interactions | Uses `gh auth token` for authentication, then hits the GitHub Copilot internal API |\n| **Codex** | Codex | Extracts the latest usage percentage from `~/.codex/sessions/*.jsonl` session logs |\n| **Gemini** | 2.5-Flash, 2.5-Flash-Lite, 2.5-Pro, 3-Flash-Preview, 3-Pro-Preview | Uses local `~/.gemini/oauth_creds.json` auth to call Gemini Code Assist quota APIs and tracks each model's remaining usage independently |\n\n---\n\n## Prerequisites\n\n- **macOS 14+** for the desktop app\n- **Linux/Windows/macOS** for CLI usage\n- **Swift 6.2+** toolchain (only needed if building from source)\n\nEach source has its own requirements:\n\n| Source | What you need |\n|---|---|\n| **Amp** | [Amp CLI](https://ampcode.com) installed and available on PATH (or at `~/.amp/bin/amp`) |\n| **Copilot** | [GitHub CLI (`gh`)](https://cli.github.com/) installed, authenticated (`gh auth login`), and available on PATH |\n| **Codex** | Codex app/CLI installed with local session logs in `~/.codex/sessions` |\n| **Gemini** | Gemini CLI installed and authenticated (credentials at `~/.gemini/oauth_creds.json`) |\n\nYou only need the prerequisites for the sources you enable — Rashun won't complain about tools you don't use.\n\n---\n\n## Installation\n\n### Quick Install (macOS app)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/alexanderheffernan/rashun/main/install.sh | bash\n```\n\nThis downloads the latest release from GitHub, installs it to `/Applications`, and clears macOS quarantine flags. To update, run the same command again — or use the built-in auto-update from Preferences.\n\n### CLI install (Linux)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/alexanderheffernan/rashun/main/install.sh | bash\n```\n\nThen run:\n\n```bash\nrashun --help\n```\n\n### CLI install (Windows)\n\n```powershell\nirm https://raw.githubusercontent.com/alexanderheffernan/rashun/main/scripts/install/windows.ps1 | iex\n```\n\nThen run:\n\n```powershell\nrashun --help\n```\n\n### CLI usage\n\n```bash\nrashun\nrashun copilot\nrashun --json\nrashun gemini --json\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/alexanderheffernan/rashun.git\ncd rashun\nchmod +x build.sh\n./build.sh --open\n```\n\n`build.sh` will:\n1. Auto-generate the source registry from `Sources/AISources/`\n2. Build a release binary via `swift build`\n3. Package it into `Rashun.app` with the app icon and code signing\n4. Launch the app (with `--open`)\n\n---\n\n## Usage\n\nOnce running, you'll see **ring icons** in your menu bar representing the remaining quota for each selected metric.\n\n1. **Click the menu bar icon** to see a breakdown of remaining usage per source, with progress bars and percentage values.\n2. **Open Usage History** to view charts, toggle sources in the legend, and see forecast projections for when each source will run out or reset.\n3. **Open Preferences** (`⌘,`) to configure everything:\n\n| Tab | What you can do |\n|---|---|\n| **General** | Launch at login, set polling interval, customize menu bar appearance (color mode, center content, which metrics to display) |\n| **Sources** | Enable/disable sources, view requirements, configure notification rules and thresholds per source and metric |\n| **Data** | View stored data stats, export/import usage history as JSON, delete history by source or date range |\n| **Updates** | See current version, toggle automatic update checks, check now, and install updates with one click |\n\n### Notification Rules\n\nEach source comes with notification rules you can toggle on:\n\n| Rule | What it does |\n|---|---|\n| **Percent remaining below** | Fires when remaining usage drops below a threshold (e.g., 50%) |\n| **Recent usage spike** | Fires when you burn through a large chunk of quota in a short time window |\n| **Pacing alert** | Fires when your current burn rate projects you'll hit 0% before the source resets *(only for sources with reset windows)* |\n\nAll thresholds and time windows are configurable in Preferences → Sources.\n\n---\n\n## Adding a New Source\n\nRashun is designed to make adding sources trivial. To add a new one:\n\n1. **Create a new file** in `Sources/AISources/` — e.g., `ClaudeSource.swift`\n2. **Define a struct** conforming to `AISource`:\n\n```swift\nimport Foundation\n\nstruct ClaudeSource: AISource {\n    let name = \"Claude\"\n    let requirements = \"Describe what the user needs installed/configured.\"\n    let metrics = [AISourceMetric(id: \"claude\", title: \"Claude\")]\n\n    func fetchUsage(for metricId: String) async throws -\u003e UsageResult {\n        // Fetch remaining and total quota however you need to\n        return UsageResult(remaining: 80, limit: 100)\n    }\n}\n```\n\n3. **Run `./build.sh`** — it auto-discovers any struct conforming to `AISource` in that directory and registers it. No other wiring needed.\n\n### Optional Overrides\n\nSources can also customize their behavior by implementing any of these:\n\n| Method | Purpose |\n|---|---|\n| `mapFetchError(for:_:)` | Provide actionable, source-specific error messages |\n| `forecast(for:current:history:)` | Generate forecast projections on the usage chart |\n| `pacingLookbackStart(for:)` | Enable pacing alerts with a custom cycle-start resolver |\n| `notificationDefinitions(for:)` | Define custom notification rules |\n| `menuBarBrandColorHex` | Set the source's brand color for colored menu bar rings |\n\n---\n\n## Project Structure\n\n```\nSources/\n├── RashunCore/                        # Cross-platform logic and data model\n│   ├── AISources/                     # Amp, Copilot, Codex, Gemini source fetchers\n│   ├── GeneratedSourceList.swift      # Auto-generated source registry (build.sh)\n│   ├── Notification*.swift            # Notification rules/models\n│   ├── UsageHistory*.swift            # Cross-platform history storage and transfer\n│   └── UpdateChecking.swift           # Cross-platform update check service\n├── RashunCLI/\n│   └── main.swift                     # Cross-platform terminal interface\n└── RashunApp/\n    ├── macOS/                         # macOS app shell (AppKit/SwiftUI integration)\n    └── Resources/                     # App assets (logos/icons)\n```\n\n---\n\n## CI/CD\n\nRashun uses GitHub Actions for continuous integration and automated releases:\n\n- **Tests** — Runs on every push and PR to `main`. Core/CLI tests run on macOS, Linux, and Windows. macOS also runs app build + app smoke test.\n- **Release** — Triggers automatically when tests pass on `main`. Builds and publishes artifacts for macOS app (`Rashun.zip`) plus CLI artifacts for macOS/Linux/Windows.\n\n---\n\n## Contributing\n\nContributions are welcome — whether it's a new AI source, a new notification rule, a bug fix, or a UI improvement.\n\n1. Fork the repo\n2. Create a feature branch (`git checkout -b my-new-source`)\n3. Make your changes\n4. Test by running `./build.sh --test \u0026\u0026 swift test` and then `./build.sh --open` to verify the app works\n5. Open a pull request\n\nSome ideas for contributions:\n- New AI sources (Claude, ChatGPT, Cursor, Windsurf, etc.)\n- New notification rule types\n- Additional forecast models\n- UI improvements and accessibility\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderheffernan%2Frashun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexanderheffernan%2Frashun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderheffernan%2Frashun/lists"}