Skip to content

README.md

Latest commit

 

History

History
149 lines (111 loc) · 5.98 KB

README.md

File metadata and controls

149 lines (111 loc) · 5.98 KB

OpenCode Token Meter

Project Logo

OpenCode Token Meter is a lightweight macOS/Windows/Linux tray app built with Python and pywebview to monitor OpenCode token usage, costs, and analytics.

Dashboard Screenshot

Note: This project was developed entirely using OpenCode. This project is not built by the OpenCode team and is not affiliated with them in any way.

🚀 Features

  • 📊 Real-time Token Tracking - Monitors token usage from AI interactions by scanning both local message files and the new opencode.db.
  • 💰 Cost Calculation - Automatic cost computation based on model-specific pricing (Anthropic, Google, GitHub Copilot, NVIDIA, etc.).
  • 📈 Detailed Analytics - View token usage by provider, model, and time range with bold, high-contrast charts (Chart.js).
  • ⚙️ Customizable Settings - Set cost thresholds, manage custom model pricing, and configure notification preferences.
  • 📥 Data Export - Export usage data for custom date ranges to CSV or Clipboard.
  • 🔄 Modern Architecture - Background agent and stats worker run as embedded threads within a single process.
  • 🔐 Privacy-Focused - All data stored locally in a SQLite database with robust deduplication logic.
  • 💻 Cross-Platform - Native experience for macOS (Menubar), Windows (System Tray), and Linux (System Tray).

📦 Installation

Option 1: Pre-built Binaries (Recommended)

Windows

  1. Download OpenCodeTokenMeter.exe from GitHub Releases.
  2. Run the executable to start the application. The app will appear in your system tray.

macOS

  1. Download OpenCodeTokenMeter.dmg from GitHub Releases.
  2. Drag "OpenCode Token Meter.app" to your Applications folder.
  3. Security Note: Since the app is unsigned, you may need to go to System Settings → Privacy & Security and click "Open Anyway" on first launch.

Linux

  1. Download OpenCodeTokenMeter.deb from GitHub Releases.
  2. Install the .deb package. Note: On GNOME, the AppIndicator extension must be enabled for the tray icon to appear.

Option 2: Build from Source

Dependencies

  • Python 3.9+
  • Recommended: venv.
# Windows
pip install "setuptools<81" pyinstaller pywebview pystray pillow pyperclip win10toast

# macOS
pip install pyinstaller pywebview rumps pillow pyperclip pyobjc-framework-Cocoa

# Linux
pip install pyinstaller pywebview pillow pyperclip

Build Commands

This project uses a single unified spec file (packaging/OpenCodeTokenMeter.spec) with automatic platform detection.

Windows:

.\packaging\build_windows.bat

Output: dist\OpenCodeTokenMeter.exe

macOS:

./packaging/build_mac.sh

Output: dist/OpenCode Token Meter.app and .dmg

Linux:

./packaging/build_linux.sh

Output: dist/OpenCode Token Meter and dist/opencode-token-meter_<version>_<arch>.deb

🏗️ Project Architecture

Directory Structure

opencode-token-meter/
├── 📄 Root Documentation
│   ├── LICENSE                  # GPL-3.0 License
│   ├── README.md                # English Documentation
│   ├── README_CN.md             # Chinese Documentation
│   ├── CHANGELOG.md             # Version History
│   └── AGENTS.md                # Developer Guide
├── 🔨 Build System
│   └── packaging/               # Build scripts and spec
│       ├── OpenCodeTokenMeter.spec   # Unified PyInstaller configuration
│       ├── build_mac.sh             # macOS build script
│       ├── build_linux.sh           # Linux build script
│       ├── build_windows.bat        # Windows build script
│       └── create_dmg.sh            # macOS DMG script
└── 📁 App/                      # Source Code
    ├── agent/                   # Message tracking & DB logic (Agent, Stats Worker)
    └── webview_ui/              # Web-based Frontend (pywebview)
        ├── backend/             # Python-JS API Bridge & Settings
        └── web/                 # HTML/CSS/JS (Tailwind, Chart.js, Lato font)

Data Flow

  1. Scanner: Periodically checks ~/.local/share/opencode/storage/message/ (legacy) and opencode.db (new) for AI messages.
  2. Database: Parses JSON data and stores deduplicated records in a local SQLite database (index.db).
  3. Bridge: The JsApi bridge fetches data from index.db and provides it to the webview UI.
  4. UI: Displays statistics and charts using a responsive interface with bold Lato (900) typography.

⚙️ Configuration

  • Database Location:
    • macOS: ~/Library/Application Support/OpenCode Token Meter/index.db
    • Windows: %APPDATA%\OpenCode Token Meter\index.db
    • Linux: ~/.local/share/OpenCode Token Meter/index.db
  • Model Pricing: Override default pricing in Settings → Cost Meter. Supports input, output, caching, and per-request pricing.

🤝 Contributing

See AGENTS.md for full developer guidelines, including:

  • Running in development mode (python App/webview_ui/main_tray.py --debug).
  • SQL safety (always use parameterized queries).
  • Manual verification checklist before release.

📜 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Credits

  • Developed entirely with OpenCode - an AI-powered terminal interface for coding.
  • This project uses the Lato typeface, designed by Łukasz Dziedzic and licensed under the SIL Open Font License.