### Setup Project Environment

Source: https://github.com/xiufengsun/tokentracker/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and build the dashboard for local development.

```bash
git clone https://github.com/xiufengsun/TokenTracker.git
cd TokenTracker
npm install

# Build the dashboard once so the CLI can serve it
cd dashboard && npm install && npm run build && cd ..
```

--------------------------------

### Development Build Commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Commands to install dependencies, build the dashboard, bundle the node server, and start the development environment.

```bash
npm ci --prefix TokenTrackerLinux
npm run dashboard:build                        # from the repo root
npm --prefix TokenTrackerLinux run bundle:node # stages EmbeddedServer/
npm --prefix TokenTrackerLinux run dev
```

--------------------------------

### Global CLI Installation and Commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/README.md

Install the CLI globally to access commands for dashboard management, manual synchronization, and status reporting.

```bash
npm i -g tokentracker-cli

tokentracker              # Open the dashboard
tokentracker sync         # Manual sync
tokentracker status       # Check hook status
tokentracker status --json     # Machine-readable summary (pipe to jq, ingest from AI agents)
tokentracker status --light    # Plain ASCII table (CI / SSH, no spinner)
tokentracker doctor       # Health check
```

--------------------------------

### Install and manage TokenTracker via npm

Source: https://github.com/xiufengsun/tokentracker/wiki/Installation

Install the CLI globally and use standard commands for dashboard access, synchronization, and maintenance.

```bash
npm i -g tokentracker-cli

tokentracker          # Opens the dashboard
tokentracker sync     # Manual sync
tokentracker status   # Integration status
tokentracker doctor   # Health check
tokentracker uninstall
```

--------------------------------

### Initialize TokenTracker Project

Source: https://github.com/xiufengsun/tokentracker/blob/main/README.md

Commands to clone the repository, install dependencies, build the dashboard, and run the CLI.

```bash
git clone https://github.com/xiufengsun/TokenTracker.git
cd TokenTracker
npm install

# Build dashboard + run CLI
cd dashboard && npm install && npm run build && cd ..
node bin/tracker.js

# Tests
npm test
```

--------------------------------

### Manual OpenClaw plugin installation

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/openclaw-integration.md

Manually link and enable the session sync plugin if the automated installation fails.

```bash
openclaw plugins install --link ~/.tokentracker/tracker/openclaw-plugin/openclaw-session-sync
openclaw plugins enable openclaw-session-sync
```

--------------------------------

### Run Manual Verification

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to start the tracker service for manual testing.

```bash
node bin/tracker.js serve --no-sync
```

--------------------------------

### Build Arch Package

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Build and install the package from a local repository checkout.

```bash
cd TokenTrackerLinux/packaging/arch/tokentracker-linux
makepkg -si
```

--------------------------------

### Install GNOME AppIndicator Extension

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Install the required extension to enable tray icon support on Debian/Ubuntu or Fedora.

```bash
# Debian / Ubuntu
sudo apt install gnome-shell-extension-appindicator
# Fedora
sudo dnf install gnome-shell-extension-appindicator
```

--------------------------------

### Check Node.js version

Source: https://github.com/xiufengsun/tokentracker/wiki/Installation

Verify that Node.js version 20 or higher is installed before proceeding with installation.

```bash
node --version
```

--------------------------------

### Install and upgrade TokenTracker via Homebrew

Source: https://github.com/xiufengsun/tokentracker/wiki/Installation

Manage the macOS menu bar application and CLI using Homebrew formulas.

```bash
# Menu bar app + CLI (recommended on macOS)
brew install --cask mm7894215/tokentracker/tokentracker
brew install mm7894215/tokentracker/tokentracker

# Upgrade
brew upgrade --cask mm7894215/tokentracker/tokentracker
brew upgrade mm7894215/tokentracker/tokentracker
```

--------------------------------

### Run TokenTracker with npx

Source: https://github.com/xiufengsun/tokentracker/wiki/Installation

Execute the CLI tool without a permanent global installation.

```bash
npx tokentracker-cli
```

--------------------------------

### Activate TokenTracker Integrations

Source: https://github.com/xiufengsun/tokentracker/wiki/Supported-AI-Tools

Run this command to re-run detection and activate integrations after installing a new AI tool.

```bash
tokentracker activate-if-needed
```

--------------------------------

### Run CLI Commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/CONTRIBUTING.md

Execute various CLI operations including starting the dashboard server, syncing, checking status, and running health checks.

```bash
node bin/tracker.js              # Start the local dashboard server (default: http://localhost:7680)
node bin/tracker.js sync         # Manual sync
node bin/tracker.js status       # Check hook status
node bin/tracker.js doctor       # Health check
```

--------------------------------

### Pass Device ID to Fetcher

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Example of passing the device parameter to the daily fetcher call.

```ts
          dailyFetcher({
            baseUrl,
            accessToken: tokenForFetch,
            from,
            to,
            device: deviceId,
            timeZone,
            tzOffsetMinutes,
          }),
```

--------------------------------

### Update Cloud Fetcher

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Example of updating a cloud fetcher function to accept and pass the device parameter.

```ts
export async function fetchCloudUsageSummary({
  from, to, source, model, device,
  timeZone, tzOffsetMinutes, rolling = false, accessToken,
}: AnyRecord = {}) {
  const tzParams = buildTimeZoneParams({ timeZone, tzOffsetMinutes });
  const filterParams = buildFilterParams({ source, model, device });
  const rollingParams = rolling ? { rolling: "1" } : {};
  return fetchAccountFunction(
    ACCOUNT_PATHS.summary,
    { from, to, ...filterParams, ...tzParams, ...rollingParams },
    accessToken,
  );
}
```

--------------------------------

### Run tests and commit changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command-line instructions to verify the implementation and commit the new files.

```bash
cd dashboard && npx tsc --noEmit && cd ..
git add dashboard/src/hooks/use-account-devices.ts dashboard/src/hooks/use-account-devices.test.tsx
git commit -m "feat(dashboard): add useAccountDevices hook"
```

--------------------------------

### Execute AppImage

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Make the AppImage executable and run it.

```bash
chmod +x TokenTracker-linux-x86_64.AppImage
./TokenTracker-linux-x86_64.AppImage
```

--------------------------------

### Bundle a self-contained runtime for distribution

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerWin/README.md

Prepares the application for distribution by building the dashboard, bundling the Node runtime, and publishing the .NET project.

```powershell
npm run dashboard:build                                   # from repo root
powershell -ExecutionPolicy Bypass -File scripts\bundle-node.ps1
dotnet publish -c Release -r win-x64 --self-contained false
```

--------------------------------

### Build macOS Application

Source: https://github.com/xiufengsun/tokentracker/blob/main/README.md

Steps to bundle the dashboard, generate the Xcode project, and package the application into a DMG.

```bash
cd TokenTrackerBar
npm run dashboard:build              # Build the dashboard bundle
./scripts/bundle-node.sh             # Bundle Node.js + tokentracker source
xcodegen generate                    # Generate the Xcode project
ruby scripts/patch-pbxproj-icon.rb   # Patch in the Icon Composer asset
xcodebuild -scheme TokenTrackerBar -configuration Release clean build
./scripts/create-dmg.sh              # Package the .app into a DMG
```

--------------------------------

### Run Test Suite

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to execute the device scope tests.

```bash
cd dashboard && npx vitest run src/hooks/use-usage-data.device.test.tsx
```

--------------------------------

### Run TokenTracker in development mode

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerWin/README.md

Builds the dashboard and launches the application using the system Node runtime and local CLI source.

```powershell
npm run dashboard:build

$env:TOKENTRACKER_NODE  = (Get-Command node).Source
$env:TOKENTRACKER_ENTRY = "$PWD\..\bin\tracker.js"   # from TokenTrackerWin\
.\bin\Debug\net8.0-windows\TokenTracker.exe
```

--------------------------------

### Build the TokenTracker application

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerWin/README.md

Compiles the project using the .NET 8 SDK.

```powershell
dotnet build -c Debug   # output: bin\Debug\net8.0-windows\TokenTracker.exe
```

--------------------------------

### Run verification tests

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Execute the test suite to ensure new device-specific functionality works without regressing existing all-devices behavior.

```bash
cd dashboard && npx vitest run src/hooks/use-usage-data.device.test.tsx src/hooks/use-trend-data.test.tsx src/hooks/use-usage-data.account-resolving.test.tsx
```

--------------------------------

### Build Local DMG for Testing

Source: https://github.com/xiufengsun/tokentracker/blob/main/CLAUDE.md

Commands to build the TokenTracker application locally. Note that CI is the authoritative source for production releases.

```bash
cd TokenTrackerBar && npm run dashboard:build && ./scripts/bundle-node.sh
xcodegen generate && ruby scripts/patch-pbxproj-icon.rb
xcodebuild -scheme TokenTrackerBar -configuration Release clean build
APP="$(find ~/Library/Developer/Xcode/DerivedData/TokenTrackerBar-*/Build/Products/Release -name 'TokenTracker.app' -maxdepth 1)"
bash scripts/create-dmg.sh "$APP"
```

--------------------------------

### Run test suite

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to execute the vitest suite for the UsageOverview component.

```bash
cd dashboard && npx vitest run src/ui/dashboard/components/UsageOverview.device.test.jsx
```

--------------------------------

### Handle TokenTracker Startup Errors

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/src/index.html

JavaScript event listener to catch and display startup errors reported by the backend.

```javascript
// The server is started on a worker thread so this page can paint // immediately; main.rs reports a failure through this event rather than // leaving the window stuck on the loading message forever. window.addEventListener('tokentracker:startup-error', (event) => { document.getElementById('loading').hidden = true; document.getElementById('error').hidden = false; // textContent, never innerHTML: the detail carries filesystem paths. document.getElementById('error-detail').textContent = String(event.detail ?? 'Unknown error'); });
```

--------------------------------

### Configure PetWindow CSS

Source: https://github.com/xiufengsun/tokentracker/blob/main/dashboard/pet.html

Sets the window to be fully transparent and enables drag-to-move functionality via cursor styles.

```css
/* Fully transparent surface: the Windows PetWindow composites the WebView2 alpha with its DWM backdrop, so anything not painted here stays see-through. */ html, body, #pet-root { margin: 0; padding: 0; width: 100%; height: 100%; background: transparent !important; overflow: hidden; } body { /* Whole surface is a drag handle (the host starts a native move on mousedown); show the grab affordance. */ cursor: grab; -webkit-user-select: none; user-select: none; } body:active { cursor: grabbing; }
```

--------------------------------

### Run verification tests

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to execute the test suite for the account device filter.

```bash
node --test test/account-device-filter.test.js
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Execute Rust tests and run clippy for code analysis.

```bash
cd TokenTrackerLinux/src-tauri
cargo test
cargo clippy --all-targets -- -D warnings
```

--------------------------------

### Run component tests

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to execute the Vitest suite for the DeviceUsageCard component.

```bash
cd dashboard && npx vitest run src/ui/dashboard/components/DeviceUsageCard.test.jsx
```

--------------------------------

### Verify and commit changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Run type checking and commit the implemented features.

```bash
cd dashboard && npx tsc --noEmit && cd ..
git add dashboard/src/ui/dashboard/components/UsageOverview.jsx dashboard/src/ui/dashboard/components/UsageOverview.device.test.jsx
git commit -m "feat(dashboard): device dropdown in UsageOverview top bar"
```

--------------------------------

### Execute common project commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/CLAUDE.md

Use these npm scripts and node commands for testing, development, and validation tasks.

```bash
npm test                                  # node --test test/*.test.js  (209 files)
node --test test/<name>.test.js           # single test file
npm run ci:local                          # tests + validations + builds
npm run dashboard:dev                     # Vite dev server with local API mock (port 5173)
npm run dashboard:build                   # build to dashboard/dist/
npm run validate:copy                     # copy registry completeness
npm run validate:ui-hardcode              # no hardcoded UI strings
npm run validate:guardrails               # architecture guardrails
node bin/tracker.js serve --no-sync       # local dashboard server on :7680
```

--------------------------------

### Configure OpenCode Go environment variables

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/opencode-go-limits.md

Set these variables in your local environment to enable usage tracking. Never commit these secrets to version control.

```dotenv
# Preferred: official OpenCode Go usage API.
OPENCODE_GO_API_KEY=

# Legacy compatibility fallback: signed-in workspace dashboard scrape.
OPENCODE_GO_WORKSPACE_ID=
OPENCODE_GO_AUTH_COOKIE=

# Optional and explicitly unverified local historical estimate.
# TOKENTRACKER_OPENCODE_GO_LOCAL_ESTIMATE=1
```

--------------------------------

### Execute Tests

Source: https://github.com/xiufengsun/tokentracker/blob/main/CONTRIBUTING.md

Run the full test suite, individual test files, or the complete CI validation pipeline.

```bash
npm test                                     # Full suite (96 test files, node --test)
node --test test/rollout-parser.test.js      # A single test file
npm run ci:local                             # Tests + validations + builds (everything CI runs)
```

--------------------------------

### Run TokenTracker diagnostics

Source: https://github.com/xiufengsun/tokentracker/wiki/FAQ

Dumps machine state, integration status, and configuration flags to a JSON file for inspection.

```bash
tokentracker diagnostics > /tmp/tt.json
```

--------------------------------

### Dashboard Development Commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/CONTRIBUTING.md

Commands for running the Vite development server, building for production, and validating the copy registry.

```bash
npm run dashboard:dev                        # Vite dev server with mocked API
npm run dashboard:build                      # Production build (output: dashboard/dist/)
npm run validate:copy                        # Validate copy registry completeness
```

--------------------------------

### Run Verification Commands

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Commands to run tests and commit changes.

```bash
cd dashboard && npx tsc --noEmit && cd ..
git add dashboard/src/lib/api.ts dashboard/src/lib/api.device.test.ts
git commit -m "feat(dashboard): thread device_id through api + add fetchAccountDevices"
```

--------------------------------

### Monitor server logs

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Displays the tail of the server log file to diagnose startup failures or port binding issues.

```bash
tail -f ~/Library/Logs/TokenTrackerBar/server.log
```

--------------------------------

### Initialize Native App and Theme State

Source: https://github.com/xiufengsun/tokentracker/blob/main/dashboard/index.html

Detects native bridge availability and synchronizes the UI theme from local storage before the first paint to prevent visual flashes.

```javascript
(function () { try { if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.nativeBridge) { document.documentElement.classList.add("native-app"); } } catch (e) {} })(); // Sync theme before first paint to prevent dark→light flash (FOUC) (function(){ var t; try { t = localStorage.getItem("tokentracker-theme"); } catch(e) {} var dark = t === "dark" || (t !== "light" && matchMedia("(prefers-color-scheme:dark)").matches); if (dark) document.documentElement.classList.add("dark"); })();
```

--------------------------------

### Implement fetchAccountDevices

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Adds the new fetcher for retrieving account devices.

```ts
export async function fetchAccountDevices({
  from, to, timeZone, tzOffsetMinutes, accessToken,
}: AnyRecord = {}) {
  const tzParams = buildTimeZoneParams({ timeZone, tzOffsetMinutes });
  return fetchAccountFunction(ACCOUNT_PATHS.devices, { from, to, ...tzParams }, accessToken);
}
```

--------------------------------

### Execute OpenCode Go tests

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/opencode-go-limits.md

Run targeted tests for the OpenCode Go implementation or the full local validation suite.

```bash
node --test test/opencode-go-limits.test.js
npm run ci:local
```

--------------------------------

### Check TokenTracker Status and Diagnostics

Source: https://github.com/xiufengsun/tokentracker/wiki/Supported-AI-Tools

Use these commands to verify the configuration state of integrated tools, perform health checks, or export diagnostic data.

```bash
tokentracker status       # Per-tool state (configured / skipped / error)
tokentracker doctor       # Deeper health check — paths, permissions, queue size
tokentracker diagnostics  # Full JSON dump (safe to attach to issues)
```

--------------------------------

### Manage sync and upload queue

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Commands to force synchronization or reset the upload queue.

```bash
tokentracker sync
```

```bash
tokentracker doctor
```

--------------------------------

### Configure DashboardPage State and Logic

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

State management and filtering logic for device selection in the dashboard.

```jsx
  const [selectedDevice, setSelectedDevice] = useState(null);
  const { devices: accountDevices } = useAccountDevices({
    from,
    to,
    timeZone,
    tzOffsetMinutes,
    accountView,
    accountAccessToken,
    accountRevision,
  });
  // Device filter is meaningful only across 2+ devices in account view.
  const showDeviceFilter = accountView && accountDevices.length >= 2;
  // Reset the filter when leaving account view, or when the selected device
  // disappears (revoked / not in the latest list).
  useEffect(() => {
    if (!showDeviceFilter) {
      if (selectedDevice !== null) setSelectedDevice(null);
      return;
    }
    if (selectedDevice && !accountDevices.some((d) => d.id === selectedDevice)) {
      setSelectedDevice(null);
    }
  }, [showDeviceFilter, accountDevices, selectedDevice]);

  const deviceOptions = useMemo(() => {
    if (!showDeviceFilter) return [];
    return [
      { value: "", label: copy("dashboard.device_filter.all") },
      ...accountDevices.map((d) => ({
        value: d.id,
        label: d.device_name || copy("dashboard.device_card.unnamed"),
      })),
    ];
  }, [showDeviceFilter, accountDevices, resolvedLocale]);

  const deviceUsageBlock = showDeviceFilter ? (
    <DeviceUsageCard
      devices={accountDevices}
      selectedDeviceId={selectedDevice || ""}
      onSelectDevice={(id) => setSelectedDevice(id || null)}
    />
  ) : null;
```

--------------------------------

### Diagnose Provider Issues

Source: https://github.com/xiufengsun/tokentracker/blob/main/README.md

Commands to check integration status and run health checks for providers.

```bash
tokentracker status
```

```bash
tokentracker doctor
```

--------------------------------

### Check TokenTracker Status

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Verify if hooks are correctly configured for AI tools.

```bash
tokentracker status
```

--------------------------------

### Update TokenTracker via Homebrew

Source: https://github.com/xiufengsun/tokentracker/wiki/FAQ

Use these commands to upgrade the CLI or macOS application cask via Homebrew.

```bash
brew upgrade mm7894215/tokentracker/tokentracker
```

--------------------------------

### Configure OpenClaw plugin settings

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/openclaw-integration.md

Manually update the OpenClaw configuration file to enable the plugin and allow conversation access.

```json
{
  "plugins": {
    "entries": {
      "openclaw-session-sync": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}
```

--------------------------------

### Run Diagnostics

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Generate sanitized diagnostic information for troubleshooting issues in GitHub issues.

```bash
tokentracker diagnostics
```

--------------------------------

### Implement ES2022 Polyfills for WebKit

Source: https://github.com/xiufengsun/tokentracker/blob/main/dashboard/share.html

Provides compatibility for Object.hasOwn and Array.prototype.at in browsers older than Safari 15.4. Execute this before the main application bundle.

```javascript
(function () { try { if (typeof Object.hasOwn !== "function") { Object.defineProperty(Object, "hasOwn", { value: function (o, k) { return Object.prototype.hasOwnProperty.call(o, k); }, configurable: true, writable: true, }); } function at(n) { n = Math.trunc(n) || 0; if (n < 0) n += this.length; return n < 0 || n >= this.length ? undefined : this[n]; } if (typeof Array.prototype.at !== "function") { Object.defineProperty(Array.prototype, "at", { value: at, configurable: true, writable: true }); } if (typeof String.prototype.at !== "function") { Object.defineProperty(String.prototype, "at", { value: at, configurable: true, writable: true }); } } catch (e) {} })();
```

--------------------------------

### Implement Device-Scoped Storage Key

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Logic for generating a storage key that includes the device scope.

```ts
  const deviceScope = deviceId || "all";
  const storageKey = (() => {
    if (!cacheKey) return null;
    const host = safeHost(baseUrl) || "default";
    const dailyKey = includeDaily ? "daily" : "summary";
    const tzKey = getTimeZoneCacheKey({ timeZone, offsetMinutes: tzOffsetMinutes });
    return `tokentracker.usage.${cacheKey}.${scopeKey}.${host}.${from}.${to}.${dailyKey}.${tzKey}.${deviceScope}`;
  })();
```

--------------------------------

### Define Dashboard Styles

Source: https://github.com/xiufengsun/tokentracker/blob/main/dashboard/index.html

Sets base background colors and handles transparency overrides for native webview environments.

```css
/* Prevent dark flash: set background before CSS loads */ html { background: #fafafa; } html.dark { background: #0a0a0a; } /* Native app: must override the two lines above — otherwise WKWebView stays opaque over NSVisualEffectView */ html.native-app, html.native-app.dark { background: transparent !important; } html.native-app body { background: transparent !important; } .js .aeo-seed-content { display: none; } .aeo-seed-content { margin: 0; padding: 1.5rem; font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; line-height: 1.55; } .aeo-seed-content h1, .aeo-seed-content h2, .aeo-seed-content h3 { margin: 0.75rem 0; }
```

--------------------------------

### Initialize ES2022 Polyfills and DOM State

Source: https://github.com/xiufengsun/tokentracker/blob/main/dashboard/index.html

Provides polyfills for Object.hasOwn and Array.prototype.at to ensure compatibility with WebKit versions older than 15.4. Also marks the document root to handle initial rendering states.

```javascript
(function () { try { if (typeof Object.hasOwn !== "function") { Object.defineProperty(Object, "hasOwn", { value: function (o, k) { return Object.prototype.hasOwnProperty.call(o, k); }, configurable: true, writable: true, }); } function at(n) { n = Math.trunc(n) || 0; if (n < 0) n += this.length; return n < 0 || n >= this.length ? undefined : this[n]; } if (typeof Array.prototype.at !== "function") { Object.defineProperty(Array.prototype, "at", { value: at, configurable: true, writable: true }); } if (typeof String.prototype.at !== "function") { Object.defineProperty(String.prototype, "at", { value: at, configurable: true, writable: true }); } } catch (e) {} })(); document.documentElement.classList.add("js");
```

--------------------------------

### Commit implementation changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Git commands to stage and commit the new edge endpoint and test files.

```bash
git add dashboard/edge-patches/tokentracker-account-devices.ts test/account-device-filter.test.js
git commit -m "feat(edge): add account-devices endpoint (per-device usage totals)"
```

--------------------------------

### Test UsageOverview device filtering

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Verifies that the device select dropdown appears when multiple devices are present and triggers the correct callback on selection.

```jsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it, vi } from "vitest";
import { UsageOverview } from "./UsageOverview";

const baseProps = {
  period: "month", periods: ["day", "month"], onPeriodChange: () => {},
  summaryValue: "0", summaryLabel: "Total", fleetData: [],
  from: "2026-06-01", to: "2026-06-30",
};

describe("UsageOverview device dropdown", () => {
  it("renders the device select when 2+ devices and fires onDeviceChange", async () => {
    const onDeviceChange = vi.fn();
    render(
      <UsageOverview
        {...baseProps}
        deviceOptions={[
          { value: "", label: "All devices" },
          { value: "d1", label: "MacBook" },
          { value: "d2", label: "Mac mini" },
        ]}
        selectedDevice=""
        onDeviceChange={onDeviceChange}
      />,
    );
    const trigger = screen.getByLabelText("Filter by device");
    expect(trigger).toBeTruthy();
    await userEvent.click(trigger);
    await userEvent.click(await screen.findByText("Mac mini"));
    expect(onDeviceChange).toHaveBeenCalledWith("d2");
  });

  it("hides the device select with fewer than 2 devices", () => {
    render(
      <UsageOverview {...baseProps} deviceOptions={[{ value: "", label: "All devices" }]} selectedDevice="" onDeviceChange={() => {}} />,
    );
    expect(screen.queryByLabelText("Filter by device")).toBeNull();
  });
});
```

--------------------------------

### Commit Changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Command to stage and commit the updated edge patches and test file.

```bash
git add dashboard/edge-patches/tokentracker-account-*.ts test/account-device-filter.test.js
git commit -m "feat(edge): narrow account-* endpoints by optional device_id"
```

--------------------------------

### Update TokenTracker CLI via npm

Source: https://github.com/xiufengsun/tokentracker/wiki/FAQ

Use this command to update the global npm package for the TokenTracker CLI.

```bash
npm update -g tokentracker-cli
```

--------------------------------

### Uninstall TokenTracker

Source: https://github.com/xiufengsun/tokentracker/wiki/FAQ

Removes all hooks and the local configuration directory.

```bash
tokentracker uninstall
```

--------------------------------

### Query OpenCode Go usage API

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/opencode-go-limits.md

Use a Bearer token to authenticate requests to the official OpenCode Go usage endpoint.

```bash
curl -sS https://opencode.ai/zen/go/v1/usage \
  -H "Authorization: Bearer $OPENCODE_GO_API_KEY"
```

--------------------------------

### Typecheck and commit changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Run the TypeScript compiler to verify types and commit the updated hook files.

```bash
cd dashboard && npx tsc --noEmit && cd ..
git add dashboard/src/hooks/use-usage-data.ts dashboard/src/hooks/use-usage-model-breakdown.ts dashboard/src/hooks/use-trend-data.ts dashboard/src/hooks/use-activity-heatmap.ts dashboard/src/hooks/use-usage-data.device.test.tsx
git commit -m "feat(dashboard): forward deviceId through usage hooks + cache scoping"
```

--------------------------------

### Commit changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Stage and commit the updated copy and translation files.

```bash
git add dashboard/src/content/copy.csv dashboard/src/content/i18n/*/dashboard.json
git commit -m "feat(dashboard): copy for device filter + per-device card"
```

--------------------------------

### Native-to-Web Bridge Communication

Source: https://github.com/xiufengsun/tokentracker/blob/main/CLAUDE.md

Communication patterns between JavaScript and Swift via the native bridge.

```text
JS → window.webkit.messageHandlers.nativeBridge.postMessage({ type, key?, value?, name? })
Swift → NativeBridge.shared.handle(message:) via WKScriptMessageHandler
Swift → JS: webView.evaluateJavaScript("window.dispatchEvent(new CustomEvent('native:settings', { detail }))")
React → useNativeSettings() subscribes
```

--------------------------------

### Generate SCIP index

Source: https://github.com/xiufengsun/tokentracker/blob/main/scripts/graph/README.md

Executes the SCIP generation script, which uses tsconfig.scip.json for configuration.

```bash
npm run graph:scip
```

--------------------------------

### Commit Dashboard Changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Commands to validate types and commit the new DeviceUsageCard component.

```bash
cd dashboard && npx tsc --noEmit && cd ..
git add dashboard/src/ui/dashboard/components/DeviceUsageCard.jsx dashboard/src/ui/dashboard/components/DeviceUsageCard.test.jsx
git commit -m "feat(dashboard): DeviceUsageCard component"
```

--------------------------------

### Apply graph auto-index

Source: https://github.com/xiufengsun/tokentracker/blob/main/scripts/graph/README.md

Executes the auto-indexing process and applies the changes to generate index files.

```bash
npm run graph:auto-index -- --apply
```

--------------------------------

### Configure UsageOverview Props

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Passing device-related props to the UsageOverview component.

```jsx
                    deviceOptions={deviceOptions}
                    selectedDevice={selectedDevice}
                    onDeviceChange={onDeviceChange}
```

--------------------------------

### Test Account Device Endpoint

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Verifies the existence of the endpoint, JWT authentication, and required database fields.

```javascript
test("account-devices endpoint exists, verifies JWT, queries devices, sums per-device", () => {
  const src = readEdge("tokentracker-account-devices.ts");
  assert.ok(src.includes("verifiedUserIdFromJwt"), "missing JWT verification");
  assert.ok(
    src.includes('.from("tokentracker_devices")'),
    "does not query tokentracker_devices",
  );
  assert.ok(src.includes('"device_name"') || src.includes("device_name"), "no device_name field");
  assert.ok(src.includes("account_usage_grouped"), "does not sum usage via the RPC");
  assert.ok(src.includes("total_tokens"), "does not return per-device total_tokens");
});

test("account-devices is NOT in the pricing-parity mirror set (no MODEL_PRICING block)", () => {
  const src = readEdge("tokentracker-account-devices.ts");
  assert.ok(!src.includes("const MODEL_PRICING"), "account-devices must not embed a pricing block");
});
```

--------------------------------

### Diagnose provider and tool status

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Commands to inspect the health and state of detected providers and tools.

```bash
tokentracker status       # See per-tool state
tokentracker doctor       # Deeper health check
tokentracker activate-if-needed  # Re-run detection
```

--------------------------------

### Implement useAccountDevices hook

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Custom React hook that fetches device usage data when in account view. Requires accountAccessToken and accountView flags to trigger data fetching.

```ts
import { useCallback, useEffect, useState } from "react";
import { resolveAuthAccessToken } from "../lib/auth-token";
import { fetchAccountDevices } from "../lib/api";

/**
 * Lists the signed-in account's active devices with per-device usage totals
 * for [from, to]. Only fetches in account view (cross-device cloud reads);
 * outside it the dashboard is single-device and there is nothing to compare.
 */
export function useAccountDevices({
  from,
  to,
  timeZone,
  tzOffsetMinutes,
  accountView = false,
  accountAccessToken = null,
  accountRevision = 0,
}: any = {}) {
  const enabled = Boolean(accountView && accountAccessToken);
  const [devices, setDevices] = useState<any[]>([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const refresh = useCallback(async () => {
    if (!enabled) {
      setDevices([]);
      setLoading(false);
      setError(null);
      return;
    }
    setLoading(true);
    setError(null);
    try {
      const token = await resolveAuthAccessToken(accountAccessToken);
      const res = await fetchAccountDevices({ from, to, timeZone, tzOffsetMinutes, accessToken: token });
      setDevices(Array.isArray(res?.devices) ? res.devices : []);
    } catch (e: any) {
      setError(e?.message || String(e));
      setDevices([]);
    } finally {
      setLoading(false);
    }
  }, [enabled, accountAccessToken, from, to, timeZone, tzOffsetMinutes, accountRevision]);

  useEffect(() => {
    refresh();
  }, [refresh]);

  return { devices, loading, error, refresh };
}
```

--------------------------------

### Inject Device ID into Usage Hooks

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Configuration object addition for account-scoped usage hooks.

```jsx
    deviceId: selectedDevice,
```

--------------------------------

### Test DeviceUsageCard component

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Unit tests for verifying device rendering and selection interaction logic.

```jsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it, vi } from "vitest";
import { DeviceUsageCard } from "./DeviceUsageCard";

const devices = [
  { id: "d1", device_name: "MacBook Pro", platform: "darwin", total_tokens: 600 },
  { id: "d2", device_name: "Mac mini", platform: "darwin", total_tokens: 400 },
];

describe("DeviceUsageCard", () => {
  it("shows each device with its share of total tokens", () => {
    render(<DeviceUsageCard devices={devices} selectedDeviceId="" onSelectDevice={() => {}} />);
    expect(screen.getByText("MacBook Pro")).toBeTruthy();
    expect(screen.getByText("60.0%")).toBeTruthy();
    expect(screen.getByText("40.0%")).toBeTruthy();
  });

  it("selects a device on click and clears it when re-clicked", async () => {
    const onSelectDevice = vi.fn();
    const { rerender } = render(
      <DeviceUsageCard devices={devices} selectedDeviceId="" onSelectDevice={onSelectDevice} />,
    );
    await userEvent.click(screen.getByText("MacBook Pro"));
    expect(onSelectDevice).toHaveBeenCalledWith("d1");

    rerender(<DeviceUsageCard devices={devices} selectedDeviceId="d1" onSelectDevice={onSelectDevice} />);
    await userEvent.click(screen.getByText("MacBook Pro"));
    expect(onSelectDevice).toHaveBeenLastCalledWith("");
  });
});
```

--------------------------------

### Implement UsageOverview changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Code modifications required to integrate the Select component into UsageOverview.

```jsx
import { Select } from "../../components/Select.jsx";
```

```jsx
  deviceOptions = [],
  selectedDevice = "",
  onDeviceChange,
```

```jsx
            {deviceOptions.length > 1 ? (
              <Select
                value={selectedDevice}
                onValueChange={onDeviceChange}
                options={deviceOptions}
                ariaLabel={copy("dashboard.device_filter.aria")}
                matchTriggerWidth
                className="h-8 px-2.5 text-xs"
              />
            ) : null}
```

--------------------------------

### Import Dashboard Components

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Required imports for the device usage functionality in DashboardPage.

```jsx
import { useAccountDevices } from "../hooks/use-account-devices.js";
import { DeviceUsageCard } from "../ui/dashboard/components/DeviceUsageCard.jsx";
```

--------------------------------

### Commit Version Bump

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Use this command to commit version changes across project files after a successful release preparation.

```bash
git add package.json TokenTrackerBar/project.yml TokenTrackerWin/TokenTrackerWin.csproj
git commit -m "chore: bump version for per-device usage breakdown"
```

--------------------------------

### Queue Entry JSON Schema

Source: https://github.com/xiufengsun/tokentracker/blob/main/CLAUDE.md

The required structure for queue entries, which are stored in UTC half-hour buckets.

```json
{
  "hour_start": "2026-04-05T14:00:00Z",
  "source": "claude|codex|cursor|gemini|...",
  "model": "claude-opus-4-6|gpt-5.4|...",
  "input_tokens": 0, "output_tokens": 0,
  "cached_input_tokens": 0, "cache_creation_input_tokens": 0,
  "reasoning_output_tokens": 0,
  "total_tokens": 0, "conversation_count": 1
}
```

--------------------------------

### Implement account-devices edge function

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

This function handles requests to fetch token usage totals per device within a specified date range, including timezone adjustments.

```typescript
export default async function (req: Request): Promise<Response> {
  if (req.method === "OPTIONS")
    return new Response(null, { status: 204, headers: corsHeaders });
  if (req.method !== "GET") return json({ error: "Method not allowed" }, 405);

  const url = new URL(req.url);
  const from = url.searchParams.get("from") || "";
  const to = url.searchParams.get("to") || "";
  if (!from || !to) return json({ error: "Missing from/to" }, 400);
  const tz = url.searchParams.get("tz") || null;
  const tzOffsetRaw = url.searchParams.get("tz_offset_minutes");
  const tzOffsetMinutes = tzOffsetRaw != null && tzOffsetRaw !== "" ? Number(tzOffsetRaw) : null;

  const baseUrl = Deno.env.get("INSFORGE_BASE_URL")!;
  const incomingApiKey =
    req.headers.get("apikey") ?? req.headers.get("Apikey") ?? req.headers.get("x-api-key") ?? undefined;
  const anonKey =
    Deno.env.get("INSFORGE_ANON_KEY") ?? Deno.env.get("ANON_KEY") ?? incomingApiKey ?? undefined;
  const serviceRoleKey = Deno.env.get("INSFORGE_SERVICE_ROLE_KEY");
  if (!serviceRoleKey) return json({ error: "server misconfigured" }, 500);

  const client = createClient({
    baseUrl,
    edgeFunctionToken: serviceRoleKey,
    anonKey,
    ...(anonKey ? { headers: { apikey: anonKey } } : {}),
  });

  const userId = await verifiedUserIdFromJwt(req.headers.get("Authorization"));
  if (!userId) return json({ error: "Unauthorized" }, 401);

  let devices: DeviceRow[];
  try {
    const { data, error } = await client.database
      .from("tokentracker_devices")
      .select("id, device_name, platform, created_at")
      .eq("user_id", userId)
      .is("revoked_at", null);
    if (error) throw new Error(error.message);
    devices = (data ?? []) as DeviceRow[];
  } catch (e) {
    return json({ error: (e as Error).message }, 500);
  }

  // Widen the UTC window ±1 day so TZ-shifted edge hours are captured (mirrors
  // account-summary). The RPC handles per-device isolation + source-class
  // dedup; a single-device query needs no extra dedup.
  const startDate = new Date(`${from}T00:00:00Z`);
  startDate.setUTCDate(startDate.getUTCDate() - 1);
  const endDate = new Date(`${to}T00:00:00Z`);
  endDate.setUTCDate(endDate.getUTCDate() + 2);
  const rangeStart = startDate.toISOString();
  const rangeEnd = endDate.toISOString();

  let withTotals: Array<DeviceRow & { total_tokens: number }>;
  try {
    withTotals = await Promise.all(
      devices.map(async (d) => ({
        ...d,
        total_tokens: await sumDeviceTokens(client, userId, d.id, rangeStart, rangeEnd, tz, tzOffsetMinutes),
      })),
    );
  } catch (e) {
    return json({ error: (e as Error).message }, 500);
  }

  withTotals.sort((a, b) => b.total_tokens - a.total_tokens);
  return json({ from, to, devices: withTotals });
}
```

--------------------------------

### Token Normalization Definitions

Source: https://github.com/xiufengsun/tokentracker/blob/main/CLAUDE.md

Definitions for various token categories used in cost calculation.

```text
input_tokens                  = non-cached input only (no cache reads/writes)
cached_input_tokens           = cache reads
cache_creation_input_tokens   = cache writes
reasoning_output_tokens       = reasoning tokens (Codex/every-code fold them into output_tokens for cost)
total_tokens                  = input + output + cache_creation + cache_read + reasoning_output (sum of all columns; Gemini-style rows that omit reasoning still pass invariants if you set the column to 0)
```

--------------------------------

### Static Test for Device ID Filtering

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

A Node.js test script that verifies all six account endpoints correctly read the device_id query parameter and implement the required security guard using includes().

```javascript
"use strict";

// The six account-* edge endpoints must each honor an optional ?device_id=
// query param by narrowing activeDeviceIds to that one device — but ONLY when
// the id belongs to the JWT-verified user (the includes() guard). This is a
// static source check (the endpoints are Deno + InsForge SDK and can't run
// under node --test); it guarantees all six got the identical guarded narrow.

const fs = require("node:fs");
const path = require("node:path");
const { test } = require("node:test");
const assert = require("node:assert");

const ROOT = path.join(__dirname, "..");
const EDGE_DIR = "dashboard/edge-patches";

const ENDPOINTS = [
  "tokentracker-account-daily.ts",
  "tokentracker-account-summary.ts",
  "tokentracker-account-hourly.ts",
  "tokentracker-account-monthly.ts",
  "tokentracker-account-heatmap.ts",
  "tokentracker-account-model-breakdown.ts",
];

function readEdge(name) {
  return fs.readFileSync(path.join(ROOT, EDGE_DIR, name), "utf8");
}

test("every account-* endpoint reads device_id and guards it with includes()", () => {
  for (const name of ENDPOINTS) {
    const src = readEdge(name);
    assert.ok(
      src.includes('url.searchParams.get("device_id")'),
      `${name}: does not read the device_id query param`,
    );
    assert.ok(
      /activeDeviceIds\.includes\(\s*requestedDeviceId\s*\)/.test(src),
      `${name}: missing the includes(requestedDeviceId) ownership guard`,
    );
    assert.ok(
      /activeDeviceIds\s*=\s*\[\s*requestedDeviceId\s*\]/.test(src),
      `${name}: does not narrow activeDeviceIds to [requestedDeviceId]`,
    );
  }
});
```

--------------------------------

### View OpenClaw Gateway Status

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/openclaw-integration.md

Use these commands to verify the OpenClaw gateway status and version when troubleshooting usage reporting issues on Windows.

```bash
openclaw gateway status --json
openclaw --version
```

--------------------------------

### Run AppImage without FUSE

Source: https://github.com/xiufengsun/tokentracker/blob/main/TokenTrackerLinux/README.md

Extract the AppImage contents and run the application directly if FUSE is unavailable.

```bash
./TokenTracker-linux-x86_64.AppImage --appimage-extract
./squashfs-root/AppRun
```

--------------------------------

### Endpoint Fetch Pattern

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

The existing pattern for fetching active device IDs that requires modification to support narrowing.

```typescript
  let activeDeviceIds: string[];
  try {
    activeDeviceIds = await fetchActiveDeviceIds(client, userId);
  } catch (e) {
    return json({ error: (e as Error).message }, 500);
  }
```

--------------------------------

### Render DeviceUsageCard in DashboardView

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Conditional rendering logic for the device usage card in the dashboard layout.

```jsx
                {deviceUsageBlock ? (
                  <FadeIn delay={nextLeft()}>
                    {deviceUsageBlock}
                  </FadeIn>
                ) : null}
```

--------------------------------

### Manage dashboard server port

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Force a specific port for the dashboard server or identify processes currently using the default port.

```bash
PORT=7700 tokentracker serve
```

```bash
lsof -i :7680
```

--------------------------------

### Create Edge Endpoint Implementation

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Defines the edge function for listing user devices and calculating usage totals. Includes JWT verification and RPC integration.

```typescript
/**
 * InsForge Edge: list the signed-in user's active devices with per-device
 * usage totals for [from, to]. Powers the dashboard device filter dropdown
 * and the per-device usage card. Reuses account_usage_grouped (no DB change):
 * one RPC per device with p_device_ids=[id] gives that device's isolated sum.
 *
 * Auth: HS256 JWT_SECRET signature verification (same template as
 * tokentracker-account-summary). InsForge does NOT validate JWTs at the
 * gateway, so we verify the signature ourselves before returning per-user data.
 */
import { createClient } from "npm:@insforge/sdk";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, apikey",
};

function json(data: unknown, status = 200) {
  return new Response(JSON.stringify(data), {
    status,
    headers: { ...corsHeaders, "Content-Type": "application/json" },
  });
}

function b64urlToBytes(s: string): Uint8Array {
  const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
  const pad = (4 - (b64.length % 4)) % 4;
  const raw = atob(b64 + "=".repeat(pad));
  const out = new Uint8Array(raw.length);
  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
  return out;
}

async function verifiedUserIdFromJwt(authHeader: string | null): Promise<string | null> {
  if (!authHeader) return null;
  const token = authHeader.replace(/^Bearer\s+/i, "").trim();
  if (!token) return null;
  const secret = Deno.env.get("JWT_SECRET");
  if (!secret) return null;
  const parts = token.split(".");
  if (parts.length !== 3) return null;
  try {
    const key = await crypto.subtle.importKey(
      "raw",
      new TextEncoder().encode(secret),
      { name: "HMAC", hash: "SHA-256" },
      false,
      ["verify"],
    );
    const data = new TextEncoder().encode(`${parts[0]}.${parts[1]}`);
    const sig = b64urlToBytes(parts[2]);
    const ok = await crypto.subtle.verify("HMAC", key, sig, data);
    if (!ok) return null;
    const payload = JSON.parse(new TextDecoder().decode(b64urlToBytes(parts[1]))) as Record<string, unknown>;
    if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) return null;
    const sub = payload.sub;
    if (typeof sub === "string" && sub.length > 0) return sub;
    const uid = payload.user_id;
    if (typeof uid === "string" && uid.length > 0) return uid;
  } catch { /* ignore */ }
  return null;
}

interface DeviceRow {
  id: string;
  device_name: string | null;
  platform: string | null;
  created_at: string | null;
}

interface GroupedRow {
  total_tokens: number | null;
}

async function sumDeviceTokens(
  client: ReturnType<typeof createClient>,
  userId: string,
  deviceId: string,
  fromIso: string,
  toIso: string,
  tz: string | null,
  tzOffsetMinutes: number | null,
): Promise<number> {
  const { data, error } = await client.database.rpc("account_usage_grouped", {
    p_user_id: userId,
    p_device_ids: [deviceId],
    p_from: fromIso,
    p_to: toIso,
    p_trunc: "day",
    p_tz: tz,
    p_offset_min: tzOffsetMinutes,
  });
  if (error) throw new Error(error.message);
  const rows = (Array.isArray(data) ? data : []) as GroupedRow[];
  let sum = 0;
  for (const r of rows) sum += Number(r.total_tokens) || 0;
  return sum;
}
```

--------------------------------

### Terminate application processes

Source: https://github.com/xiufengsun/tokentracker/wiki/Troubleshooting

Forcefully terminates running instances of the application to resolve port conflicts.

```bash
pkill -f TokenTrackerBar
```

--------------------------------

### Remove OpenClaw Plugin

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/openclaw-integration.md

Commands to disable and uninstall the openclaw-session-sync plugin via the CLI.

```bash
openclaw plugins disable openclaw-session-sync
openclaw plugins uninstall openclaw-session-sync
```

--------------------------------

### Disable Telemetry via Environment Variables

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/PRIVACY.md

Use these environment variables to opt out of telemetry tracking.

```bash
export TOKENTRACKER_NO_TELEMETRY=1     # or DO_NOT_TRACK=1
```

--------------------------------

### Commit Dashboard Device Filter Changes

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/superpowers/plans/2026-06-25-per-device-usage-breakdown.md

Use this command to stage and commit the dashboard UI changes for the device filter feature.

```bash
git add dashboard/src/pages/DashboardPage.jsx dashboard/src/ui/dashboard/views/DashboardView.jsx
git commit -m "feat(dashboard): wire device filter (dropdown + card) into dashboard"
```

--------------------------------

### OpenCode Go provider-panel JSON contract

Source: https://github.com/xiufengsun/tokentracker/blob/main/docs/opencode-go-limits.md

The standardized JSON structure used by the provider panel after mapping API or scraper data.

```json
{
  "configured": true,
  "source": "api",
  "subscription_status": "active",
  "primary_window": { "used_percent": 42, "reset_at": "2026-01-01T00:00:00.000Z" },
  "secondary_window": { "used_percent": 18, "reset_at": "2026-01-01T00:00:00.000Z" },
  "tertiary_window": { "used_percent": 7, "reset_at": "2026-01-01T00:00:00.000Z" }
}
```