tokentray 0.1.0__tar.gz

tokentray-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,79 @@
+name: Bug report
+description: Something in tokentray does not work as described. 한국어로 작성해도 됩니다.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. Please **never paste login tokens, webhook URLs or your
+        email address**. `tokentray doctor` prints no tokens, but its file paths can
+        contain your user name - edit those out if that matters to you.
+        Security problems belong in a private report instead: see SECURITY.md.
+  - type: input
+    id: version
+    attributes:
+      label: tokentray version
+      description: Output of `tokentray --version`.
+      placeholder: tokentray 0.1.0
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: How did you install it?
+      options:
+        - Release download (zip / tar.gz)
+        - uv tool install tokentray
+        - From source (git clone)
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: Include the version, and on Linux the desktop and session type (`echo $XDG_SESSION_TYPE`).
+      placeholder: Ubuntu 24.04, GNOME, Wayland / Windows 11 24H2 / macOS 15.6
+    validations:
+      required: true
+  - type: checkboxes
+    id: services
+    attributes:
+      label: Which services are signed in?
+      options:
+        - label: Claude Code
+        - label: Codex
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what did you expect?
+      description: Screenshots help, especially for tray, panel or notification problems.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Start tokentray
+        2. Click the tray icon
+        3. ...
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `tokentray doctor`
+      description: On macOS packaged builds the CLI is at `/Applications/tokentray.app/Contents/MacOS/tokentray`.
+      render: text
+  - type: textarea
+    id: log
+    attributes:
+      label: Relevant log lines
+      description: Tray menu → **Open log**. The lines around the time of the problem are enough.
+      render: text
+  - type: checkboxes
+    id: redacted
+    attributes:
+      label: Before submitting
+      options:
+        - label: I removed tokens, webhook URLs and email addresses from everything above.
+          required: true

tokentray-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/messy-snail/tokentray/security/advisories/new
+    about: Token handling, keyring storage or webhook problems - please report privately, not as a public issue.

tokentray-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Suggest something tokentray should show or do. 한국어로 작성해도 됩니다.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: Describe the situation first; a proposed solution is welcome but optional.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would help?
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: Windows 11 / macOS 15 / Ubuntu 24.04

tokentray-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    # Style only, and deliberately not a gate on release.yml: a tag should not
+    # be blocked by an import order, and the suite is what proves behaviour.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv run ruff check .
+
+  test:
+    uses: ./.github/workflows/tests.yml
+
+  bundle:
+    # The packaged build has its own failure modes - a spec that picks the wrong
+    # executable, a missing icon, an entry point that never returns - and none of
+    # them show up in the unit suite. Building here means a tag is not the first
+    # time anyone finds out.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-14]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Qt runtime libraries
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libegl1 libgl1 libxkbcommon0 libdbus-1-3 libfontconfig1 libglib2.0-0 \
+            libxcb-cursor0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-xkb1
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv run pyinstaller --noconfirm --distpath dist --workpath build packaging/tokentray.spec
+
+      - name: Smoke test the bundle
+        shell: bash
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: ./packaging/smoke.sh

tokentray-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,132 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Check tag against package version
+        run: uv run --no-project python scripts/check_release_version.py
+
+  test:
+    needs: validate
+    uses: ./.github/workflows/tests.yml
+    permissions:
+      contents: read
+
+  bundle:
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Built inside a 22.04 container so the glibc requirement stays low
+          # enough for older distributions; a 24.04 runner would not run there.
+          - os: ubuntu-latest
+            container: ubuntu:22.04
+            asset: tokentray-linux-x86_64
+          - os: windows-latest
+            asset: tokentray-windows-x86_64
+          - os: macos-14
+            asset: tokentray-macos-arm64
+    runs-on: ${{ matrix.os }}
+    container: ${{ matrix.container }}
+    steps:
+      - name: Install container prerequisites
+        if: matrix.container
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends \
+            ca-certificates curl git binutils \
+            libegl1 libgl1 libxkbcommon0 libdbus-1-3 libfontconfig1 libglib2.0-0 \
+            libxcb-cursor0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-xkb1
+
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv run pyinstaller --noconfirm --distpath dist --workpath build packaging/tokentray.spec
+
+      - name: Smoke test the bundle
+        env:
+          QT_QPA_PLATFORM: offscreen
+        shell: bash
+        # Same script CI runs on every pull request, so a release cannot be the
+        # first build anyone actually checks.
+        run: ./packaging/smoke.sh
+
+      - name: Sign ad-hoc (macOS)
+        if: runner.os == 'macOS'
+        # Unsigned, unnotarised: Gatekeeper still needs the quarantine flag
+        # cleared by hand. The README says so; ad-hoc signing just keeps the
+        # bundle from being rejected outright.
+        run: codesign --force --deep --sign - dist/tokentray.app || true
+
+      - name: Archive
+        shell: bash
+        run: |
+          if [ "$RUNNER_OS" = "Windows" ]; then
+            cd dist && 7z a -tzip "../${{ matrix.asset }}.zip" tokentray
+          elif [ "$RUNNER_OS" = "macOS" ]; then
+            cd dist && zip -qry "../${{ matrix.asset }}.zip" tokentray.app
+          else
+            # Linux gets the desktop integration alongside the binaries: there is
+            # no package manager in a tarball, so install.sh is how the app gets
+            # a launcher entry and an icon.
+            cp packaging/linux/install.sh packaging/linux/*.desktop dist/
+            mkdir -p dist/resources
+            cp packaging/resources/tokentray-*.png dist/resources/
+            cd dist && tar czf "../${{ matrix.asset }}.tar.gz" \
+              tokentray install.sh io.github.messy-snail.tokentray.desktop resources
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset }}
+          path: |
+            ${{ matrix.asset }}.zip
+            ${{ matrix.asset }}.tar.gz
+          if-no-files-found: error
+
+  release:
+    needs: bundle
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+          generate_release_notes: true
+
+  pypi:
+    needs: bundle
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing; no API token stored in the repo
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish

tokentray-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,41 @@
+name: Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-14]
+        # 3.12 is what .python-version pins, so it is what a developer's
+        # `uv run` actually uses; 3.11 and 3.13 are the supported edges.
+        python: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Qt runtime libraries
+        if: runner.os == 'Linux'
+        # PySide6 links these even when running headless under the offscreen
+        # platform plugin; without them `import PySide6.QtWidgets` fails. Kept
+        # in step with the release workflow's list.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libegl1 libgl1 libxkbcommon0 libdbus-1-3 libfontconfig1 libglib2.0-0 \
+            libxcb-cursor0 libxcb-icccm4 libxcb-keysyms1 libxcb-shape0 libxcb-xkb1
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run tests
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: uv run --python ${{ matrix.python }} pytest -q
+

tokentray-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# packaging
+/build/
+/dist/
+*.spec.bak
+
+# Claude Code scratch. A git worktree must never be committed into its own repo.
+.claude/worktrees/
+
+# scripts/verify-linux.sh writes its log into the repo root; the tree has to be
+# clean at tag time.
+verify-linux-*.log

tokentray-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

tokentray-0.1.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## 0.1.0 - 2026-09-14
+
+First release. A cross-platform reimplementation of
+[haomingkoo/claude-codex-monitor](https://github.com/haomingkoo/claude-codex-monitor)
+(MIT), whose macOS and Windows scripts had drifted apart; here both platforms
+run the same code.
+
+### Added
+- Tray icon showing Claude Code and Codex remaining quota as concentric rings.
+- Self-drawn toast notifications at 50/25/10% remaining, plus reset reminders.
+- Detail panel with per-window meters, reset countdown, pace and burnout.
+- `status`, `setup`, `doctor`, `open`, `refresh`, `stop`, `config`, `autostart`.
+- Start-at-login on Windows, macOS and Linux, registering the GUI entry point.
+- Single-instance enforcement with a local command socket.
+- English and Korean, chosen from the desktop locale on first run.
+- Optional Slack, Discord, ntfy or generic webhook delivery, configurable from
+  the tray with URLs kept in the OS keyring.
+- Provider-labelled notifications with the tokentray ring icon, so Claude Code
+  and Codex alerts can be identified at a glance.
+- `state reset` for re-arming the first-run notice and the alert memory, applied
+  through the running instance so its in-memory copy cannot overwrite it.
+- `doctor` reports whether OS notification delivery stands any chance here: the
+  `.app` bundle, its signature, and what that means on macOS.
+- Every OS notification attempt is logged, so a channel that drops them silently
+  leaves evidence instead of nothing.
+- "Test notification" now fires the OS notification centre alongside the in-app
+  toast, so a dead native channel can be told from one nobody called.
+- `config set` hands the change to a running instance, so thresholds, reminders,
+  popup position and duration, and `native_notifications` no longer wait for a
+  restart.
+- `popup.position` now works. It was listed in the defaults, written into every
+  config file and read by nothing; `auto`, `bottom-right` and `top-right` are
+  honoured, and the `off` it used to offer is gone - it never did anything, so a
+  config still carrying it keeps behaving as before.
+- Launching `tokentray` while it is already running now says so, with the
+  running pid and, on Windows, where hidden tray icons live. It used to exit
+  without a word, which reads exactly like a failed start. `doctor` reports the
+  running instance too.
+- The tray tooltip always leads with `tokentray`, so the entry can be found in
+  Windows' "Other system tray icons" settings, where it is otherwise a python.exe.
+- On Windows the tray icon follows the taskbar's colour mode instead of the apps'
+  mode, so light apps on a dark taskbar no longer paint a ring that all but vanishes.
+
+### Fixed
+- The self-drawn card stayed hidden on macOS whenever another app was frontmost.
+  A Qt::Tool window is an NSPanel that the OS hides on deactivation - exactly
+  when an alert is worth seeing, and outside an app bundle macOS delivers no
+  banner, so the card may be the only channel.
+- Switching language left the detail panel half-translated until the next poll.
+  The views carry already-translated text, so the switch now rebuilds them from
+  the last snapshots instead of re-rendering what was already worded.
+- Stacked cards overlapped by the height of a menu bar. The top slot asked for a
+  position above the work area - the transparent shadow margin is wider than the
+  edge inset - and macOS answered by sliding that window back down, while the
+  cards below were still spaced from the position nothing ever had.
+- Hovering a card no longer let it expire under the cursor. Qt reports Leave when
+  the pointer crosses onto a child widget, so settling on the card body counted
+  as leaving and restarted the eight seconds.
+- On Windows, `status`, `config set` and a second launch could now and then fail
+  to hear back from the running app. The app hung up right after answering, and
+  closing the server end of a named pipe throws away bytes the client has not
+  read yet; it now waits for the client to hang up first.
+- "Refresh now" reported failure whenever one service was not signed in, so
+  anyone using only Claude Code or only Codex saw "Refresh failed" on every
+  click. A service nobody signed in to no longer counts against the result.
+- Closing "Notification integrations…" left its menu item dead until restart.
+  The dialog deletes itself on close; the controller kept the stale wrapper, so
+  the next open raised inside the slot and silently did nothing.
+- A refused Claude Code keychain read was retried on every poll and on every
+  two-second login probe, each call able to bring the authorization prompt back,
+  and it was shown as "not logged in". It now says the keychain could not be
+  read and asks again only when you refresh or press Check again. At launch the
+  first poll and the login probe also read it at the same moment, so a denied
+  keychain could ask twice before either saw the refusal; those reads now wait
+  for each other.
+
+### Differences from the reference implementation
+- Alerts cover every window, including Codex and the per-model sub-limits;
+  upstream alerted only on Claude's two windows.
+- A sharp drop reports the worst threshold crossed instead of stepping down one
+  level per poll, which delayed an "almost out" warning by several minutes.
+- "Still working?" is measured as a usage delta between polls. Upstream compared
+  pace against 1.3x, which its own 60/30/10-minute reminder defaults can never
+  satisfy - exceeding 1.3x needs at least 23% of the window still to run.
+- Backoff is stored as an explicit timestamp rather than by touching the cache
+  file's mtime, so a suppressed failure is distinguishable from a fresh success.
+- Claude's OAuth token is never refreshed by tokentray; Codex refresh is opt-in
+  and re-checks the file before writing so it cannot clobber the Codex CLI.
+- A missing seven-day window no longer blanks the display, and Codex window
+  labels follow the API-reported duration.

tokentray-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to tokentray
+
+Thanks for helping out. Issues and pull requests are welcome in English or
+Korean (한국어로 작성해도 됩니다).
+
+## Bugs, ideas and security reports
+
+- **Bug** - open a
+  [bug report](https://github.com/messy-snail/tokentray/issues/new?template=bug_report.yml).
+  Include `tokentray --version`, your operating system and the output of
+  `tokentray doctor`. Remove tokens, webhook URLs and email addresses first.
+- **Idea** - open a
+  [feature request](https://github.com/messy-snail/tokentray/issues/new?template=feature_request.yml)
+  that describes what you are trying to do.
+- **Security problem** - please do not open a public issue; follow
+  [SECURITY.md](SECURITY.md).
+
+## Development setup
+
+You need [uv](https://docs.astral.sh/uv/); it fetches a suitable Python.
+
+```bash
+git clone https://github.com/messy-snail/tokentray
+cd tokentray
+uv sync
+uv run tokentray        # run the tray app from the checkout
+uv run pytest           # widget tests use Qt's offscreen platform
+uv run ruff check .
+```
+
+## Pull requests
+
+1. Branch from `dev` and open the pull request against `dev`. Releases are cut
+   from `main`.
+2. Add or update tests when you change behaviour.
+3. If you change something users see, update both `README.md` and
+   `README.ko.md`. A short English note is fine; the maintainer can fill in the
+   Korean.
+4. If you change the panel, alert cards, tray icon or integrations window,
+   regenerate the README screenshots:
+
+   ```bash
+   uv run python scripts/render_screenshots.py
+   ```
+
+5. Write commit messages as [Conventional Commits](https://www.conventionalcommits.org/),
+   for example `fix(ui): keep the panel inside the screen`. English is
+   preferred; Korean is fine too.
+
+## Packaging and desktop checks
+
+Build and smoke-test a bundle the same way CI and the release workflow do:
+
+```bash
+uv run pyinstaller --noconfirm --distpath dist --workpath build packaging/tokentray.spec
+./packaging/smoke.sh
+```
+
+After changing the icon design, regenerate and commit the icon files:
+
+```bash
+QT_QPA_PLATFORM=offscreen uv run python packaging/make_icons.py
+```
+
+Automated tests cannot see a real desktop. [MANUAL_TEST.md](MANUAL_TEST.md)
+lists what to check by hand, and on Linux `./scripts/verify-linux.sh` runs every
+desktop check that does not need a person watching.

tokentray-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 koohaoming
+Copyright (c) 2026 hskang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.