{"id":51681687,"url":"https://github.com/aashutoshrathi/toki","last_synced_at":"2026-07-15T14:04:47.371Z","repository":{"id":370001295,"uuid":"1277131490","full_name":"aashutoshrathi/toki","owner":"aashutoshrathi","description":"Native macOS menu bar app for tracking Claude Code and Codex account usage.","archived":false,"fork":false,"pushed_at":"2026-07-15T04:55:07.000Z","size":3173,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-15T06:12:13.886Z","etag":null,"topics":["ai-tools","anthropic","appkit","claude-code","codex","macos","menu-bar","openai","productivity","swift","swiftui","usage-tracker"],"latest_commit_sha":null,"homepage":"http://toki.aashutosh.dev/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aashutoshrathi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-06-22T15:58:01.000Z","updated_at":"2026-07-15T04:55:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aashutoshrathi/toki","commit_stats":null,"previous_names":["aashutoshrathi/toki"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/aashutoshrathi/toki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashutoshrathi%2Ftoki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashutoshrathi%2Ftoki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashutoshrathi%2Ftoki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashutoshrathi%2Ftoki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aashutoshrathi","download_url":"https://codeload.github.com/aashutoshrathi/toki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashutoshrathi%2Ftoki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35507818,"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-15T02:00:06.706Z","response_time":131,"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":["ai-tools","anthropic","appkit","claude-code","codex","macos","menu-bar","openai","productivity","swift","swiftui","usage-tracker"],"created_at":"2026-07-15T14:04:44.936Z","updated_at":"2026-07-15T14:04:47.361Z","avatar_url":"https://github.com/aashutoshrathi.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toki\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"Sources/Toki/Resources/toki-logo.svg\" alt=\"Toki logo\" width=\"112\" height=\"112\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA tiny macOS menu bar companion for AI coding agents and usage.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Version 2.1.8\" src=\"https://img.shields.io/badge/version-2.1.8-2f80ed\"\u003e\n  \u003cimg alt=\"macOS 14+\" src=\"https://img.shields.io/badge/macOS-14%2B-111111\"\u003e\n  \u003cimg alt=\"Swift 6\" src=\"https://img.shields.io/badge/Swift-6-f05138\"\u003e\n  \u003ca href=\"https://github.com/aashutoshrathi/toki\"\u003e\u003cimg alt=\"Contribute on GitHub\" src=\"https://img.shields.io/badge/contribute-GitHub-24292e?logo=github\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003e/toki\u003c/code\u003e keeps your active AI coding accounts, current-session quota, and weekly quota one click away.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://files.aashutosh.dev/toki-preview.png\" alt=\"Toki menu bar popover preview\" width=\"420\"\u003e\n\u003c/p\u003e\n\n## Why Toki\n\nToki is built for people who jump between Claude Code, Codex, Copilot, Gemini, and OpenCode during the day and want a fast, local view of usage and active agents.\n\nIt works especially well with [`claude-swap`](https://github.com/realiti4/claude-swap): Toki discovers the same Claude Code account registry, shows active and inactive accounts, and lets you switch accounts without reimplementing credential-management logic.\n\nToki stays local. Credentials are read from your Mac, your configured commands, or provider auth files. The app does not run a cloud service.\n\n## Features\n\n- Live quota, rate-limit, and spend tracking for Claude Code (multi-account via `claude-swap`, with discovery, one-click switching, and Keychain credential lookup), Codex, and OpenCode.\n- One-click redemption of banked Codex rate-limit reset credits, gated to when the current window is mostly used.\n- Active-agent discovery across Codex, Claude Code, Copilot CLI, Gemini CLI, OpenCode, and ChatGPT-hosted Codex, with best-effort navigation to the matching terminal tab or host app.\n- AI-powered insight card with on-device Apple Intelligence summarization (macOS 26+), falling back to a deterministic recommendation with one-click smart switch.\n- Native low-quota and session-warning notifications with cooldowns, DND mode, and local event/usage history.\n- Session mode for tracking quota burn during a focused coding run.\n- `Toki status` CLI for scripting and shell prompts, plus a Launch at Login toggle backed by `SMAppService`.\n- Configurable menu bar display modes, inline account aliases, an \"Add account\" button to connect more providers any time (not just on first run), and optional manual ledgers for plans without a usage API.\n- One-click, verified app updates and privacy-safe rotating diagnostics.\n\n## Requirements\n\n- macOS 14 or newer.\n- Swift 6 toolchain.\n- Claude Code installed and authenticated.\n- `claude-swap` installed and configured for multi-account Claude workflows.\n- Codex installed and authenticated for Codex usage.\n- Copilot CLI, Gemini CLI, or OpenCode installed when using active-agent discovery for those tools.\n\nmacOS may ask for Keychain access the first time Toki reads Claude Code or `claude-swap` credentials.\n\n## Install\n\n### Homebrew\n\n```sh\nbrew tap aashutoshrathi/tap\nbrew install --cask toki\n```\n\nThe cask installs the latest release DMG. Toki is ad-hoc signed and not notarized, so on first launch macOS may block it - right-click Toki in Applications and choose Open, or run `xattr -dr com.apple.quarantine /Applications/Toki.app`.\n\n### Direct download\n\nGrab the latest `Toki_\u003cversion\u003e_universal.dmg` from the [releases page](https://github.com/aashutoshrathi/toki/releases/latest), open it, and drag Toki to Applications. Updates install in-app once running.\n\n## Install From Source\n\nBuild and run:\n\n```sh\nswift run Toki\n```\n\nBuild and install an app bundle:\n\n```sh\nscripts/install-app.sh\nopen ~/Applications/Toki.app\n```\n\nBuild the app bundle without installing:\n\n```sh\nscripts/build-app.sh\nopen .build/Toki.app\n```\n\nThe generated app bundle is written to `.build/Toki.app`.\n\n## Configuration\n\nWhenever `~/.toki/config.json` is missing, or exists but has no accounts yet, Toki's popover shows a **Connect an account** screen instead of an empty list. It scans for Claude Code (Keychain), Codex (`~/.codex/auth.json`), OpenCode (its local database), and Gemini CLI (`~/.gemini/oauth_creds.json`), and a single click on **Connect** (or **Connect all detected**) writes the right entries to `~/.toki/config.json` for you - no JSON to hand-write. Gemini shows up as signed-in but has no Connect button: like Copilot, it's detection-only (see Features), so there's nothing to write for it. If nothing is detected yet, sign in to Claude Code or Codex and reopen the menu.\n\nThis screen isn't just for the first run - the header's **+** button opens it any time, so starting with just Claude Code and adding Codex (or anything else newly signed in) later needs no config editing either. It only offers providers you haven't already connected.\n\nFor scripting, multi-account setups, or fields the wizard doesn't cover (API keys, budgets, manual trackers), edit the config directly. Toki reads:\n\n```text\n~/.toki/config.json\n```\n\nCreate a starting config:\n\n```sh\nmkdir -p ~/.toki\ncp examples/config.example.json ~/.toki/config.json\n```\n\nMinimal Claude Code plus Codex config:\n\n```json\n{\n  \"refreshMinutes\": 5,\n  \"accountLabels\": [\n    {\n      \"email\": \"work@example.com\",\n      \"organizationUuid\": \"00000000-0000-0000-0000-000000000000\",\n      \"nickname\": \"Work\",\n      \"color\": \"#4F8EF7\"\n    },\n    {\n      \"email\": \"personal@example.com\",\n      \"nickname\": \"Personal\",\n      \"color\": \"#F59E0B\"\n    }\n  ],\n  \"accounts\": [\n    {\n      \"label\": \"Claude\",\n      \"type\": \"claudeCode\",\n      \"claudeSwapCommand\": \"claude-swap\"\n    },\n    {\n      \"label\": \"Codex\",\n      \"type\": \"codex\",\n      \"codexAuthPath\": \"~/.codex/auth.json\"\n    }\n  ]\n}\n```\n\nEach account needs a `label` (display name) and a `type` (provider). An `id` is optional and derived from the label when omitted. Older configs using `name`/`provider`/`id` are migrated automatically on launch, keeping a `.bak` of the original.\n\n`accountLabels` are optional presentation overrides. Toki matches discovered Claude accounts by email and, when provided, organization UUID or name. Labels do not alter credentials or switching behavior.\n\n`refreshMinutes` defaults to `5`. API-backed providers refresh stale-while-revalidate style: Toki keeps the last visible usage while refreshing in the background. Automatic refreshes pace Claude Code API calls at 7.5 minutes to reduce early `429` responses, while Codex uses the 5-minute cadence. Opening the popover or pressing reload can refresh sooner, but still keeps a 1-minute minimum between provider API calls. If a provider returns `429`, Toki keeps showing the last good usage snapshot.\n\n`aiInstructions` is an optional string that customizes the on-device LLM prompt used by the AIInsightCard on macOS 26+. When absent, Toki uses a default prompt based on the current recommendation and account snapshots.\n### Smart Recommendations, AI Insights, Notifications, and History\n\nToki keeps v2.1 preferences, notification cooldowns, event history, usage history, and session state in:\n\n```text\n~/.toki/usage-state.json\n```\n\nThe overview shows a single AIInsightCard replacing the three separate stat blocks (Use, Status, Session). When running macOS 26+ with Apple Intelligence available, Toki generates a natural-language summary of your account state with actionable suggestions. A purple sparkle icon and border distinguish AI-generated content from the rule-based fallback. The optional `aiInstructions` config field lets you steer the on-device LLM prompt. On older systems the card shows the same deterministic recommendation with a lightbulb icon.\n\nThe settings panel controls native notifications, DND mode, low-quota threshold, session warning threshold, notification cooldown, history retention, and the menu bar display mode. DND mode suppresses macOS notification delivery but still records events so you can audit what would have fired.\n\nThe Agents tab inspects the local process table without persisting command lines, prompts, workspace names, or session titles. Each agent shows its conversation title when available, otherwise the project folder name relative to your home directory (`~/Code/project`). When an agent has a terminal TTY, clicking it selects the matching tab in iTerm2 or Terminal. For other hosts (iTerm, VS Code, Cursor, ChatGPT), Toki activates the resolved host app via its bundle ID.\n\nOpenCode usage is automatically detected from its local SQLite database and surfaced as an account. Copilot and Gemini are agent-detection-only: Toki detects running Copilot or Gemini CLI processes locally (and, for Gemini, whether `gemini` is signed in for the onboarding screen), but does not invent quotas - neither GitHub nor Google expose a usage/quota API for these that Toki could read from.\n\n### Updates and Diagnostics\n\nToki checks the latest public GitHub release at most once every six hours, including while the app remains open. Settings also provides a manual “Check now” action that bypasses the schedule. A newer release shows an Update button that downloads its DMG, verifies the `local.toki` bundle identity, version, and code signature, stages the app, replaces the installed bundle after Toki exits, and relaunches it. Set `TOKI_MOCK_UPDATE_VERSION=9.9.9` when developing to preview the banner without publishing a release.\n\nToki writes rotating diagnostics to `~/.toki/logs/toki.log`. These logs contain app-level error categories and status codes only; they exclude credentials, account configuration, prompts, session titles, workspace names, and full file paths. “Send debug report” in Settings creates a local text attachment and opens the macOS share picker. Toki never sends the report automatically.\n\nThe AIInsightCard picks the healthiest available account from live snapshots and can optionally surface an on-device LLM summary on macOS 26+. For Claude Code multi-account setups, it can switch to the recommended inactive account through the same configured `claude-swap --switch-to` path used by account rows.\n\nSession mode records starting quota for visible accounts, then shows a prominent red banner with a live stopwatch and per-account burn during the current coding session. It logs session warning events when quota drops sharply or crosses the configured warning threshold. The play/stop toggle lives in the header bar next to the refresh button.\n\n### Launch at Login\n\nSettings has a \"Launch at login\" toggle backed by `SMAppService`. It reflects whatever System Settings \u003e General \u003e Login Items actually says rather than a separate stored preference, so removing Toki there also turns the toggle off. macOS occasionally requires approving a freshly-added login item in that same pane before it takes effect - when that happens, the toggle shows an inline \"Needs approval\" note with a shortcut straight there.\n\n### Command Line Status\n\n```sh\nToki status              # one line per account, e.g. \"Work: 82% left\" (uses each account's configured name, not the provider name)\nToki status --compact    # single line matching the menu bar icon, for prompts/status bars\nToki status --json       # full snapshot as JSON\n```\n\nRun the installed app's binary directly, e.g. `/Applications/Toki.app/Contents/MacOS/Toki status`. This reads a cache the running app writes after every refresh at `~/.toki/status.json` (override with `TOKI_STATUS_CACHE`) - it never launches the menu bar app or makes a live network/Keychain call, so it's safe to call on every shell prompt render. If Toki hasn't run yet, or the cache is more than 15 minutes old, it says so on stderr.\n\n### Environment Overrides\n\n```sh\nTOKI_CONFIG=/path/to/config.json swift run Toki\nTOKI_STATE=/path/to/usage-state.json swift run Toki\nTOKI_STATUS_CACHE=/path/to/status.json swift run Toki\n```\n\nLegacy TokenBar paths and variables are still recognized during the rename:\n\n- `TOKENBAR_CONFIG`\n- `TOKENBAR_STATE`\n- `~/.tokenbar/config.json`\n- `~/.tokenbar/usage-state.json`\n\n## Account Switching\n\nWhen an inactive Claude Code account is switched, Toki runs:\n\n```sh\nclaude-swap --switch-to \u003cslot\u003e\n```\n\nAfter the command succeeds, Toki reloads account discovery and refreshes usage. If `claude-swap` is not on your `PATH`, set `claudeSwapCommand` to the full executable path.\n\n## Codex Usage\n\nAdd a Codex account when this Mac is signed in to Codex:\n\n```json\n{\n  \"label\": \"Codex\",\n  \"type\": \"codex\",\n  \"codexAuthPath\": \"~/.codex/auth.json\"\n}\n```\n\nToki reads `~/.codex/auth.json` by default and asks the local Codex app-server for account usage and rate limits. Set `codexAuthPath` to use a different auth file.\n\nCodex usage is separate from OpenAI organization API usage.\n\nWhen OpenAI has a banked rate-limit reset credit for the account, the expanded Codex card shows a **Reset now** button (with the count when more than one is banked). It stays disabled until the current window is at least 80% used, so a reset isn't spent while there's still plenty of quota left - redeeming one resets the rate-limit window immediately via the Codex app-server.\n\n## Development\n\nCommon commands:\n\n```sh\nswift build\nswift run Toki\nscripts/build-app.sh\n```\n\nBefore shipping a local change, run:\n\n```sh\nswift build\nscripts/build-app.sh\nplutil -p .build/Toki.app/Contents/Info.plist\n```\n\n`swift-format` is not vendored in this repository. Keep Swift changes compiler-clean, locally scoped, and consistent with existing SwiftUI/AppKit conventions.\n\n## Repository\n\n```text\naashutoshrathi/toki\n```\n\nToki keeps backwards-compatible config fallbacks for the old TokenBar name, but new docs, app bundles, examples, and package metadata use Toki.\n\n## Troubleshooting\n\n- `Config needed`: create `~/.toki/config.json` or set `TOKI_CONFIG`.\n- `No credentials found`: confirm Claude Code and `claude-swap` are authenticated and that Keychain access was allowed.\n- `Claude Code usage unavailable`: Anthropic did not return usage data for that account. Try refreshing later or check the account in Claude Code.\n- `Codex usage unavailable`: confirm `codex login` has created `~/.codex/auth.json`, then refresh Toki.\n- Switch fails: run `claude-swap --switch-to \u003cslot\u003e` in Terminal to inspect the underlying error.\n- Notifications do not appear: open the Events tab to check whether DND or cooldowns suppressed delivery, then confirm macOS notification permission for Toki.\n\n## License\n\nToki is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nToki is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with Toki. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashutoshrathi%2Ftoki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faashutoshrathi%2Ftoki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashutoshrathi%2Ftoki/lists"}