AgentMon

**English** | [English](./docs/README.en.md) | [日本語](./docs/README.ja.md) # Tool List > A macOS status bar Token statistics application       ## Table of Contents - [Interface Preview](#interface-preview) - [Function Overview](#function-overview) - [System Requirements](#system-requirements) - [Installation and Download](#installation-and-download) - [Quick Start](#quick-start) - [Interface Description](#interface-description) - [Supported Data Sources](#supported-data-sources) - [Configuration and Data](#configuration-and-data) - [Project Structure](#project-structure) - [Document Entry](#document-entry) - [License](#license) ## Interface Preview <p> <img src="docs/images/tokmon-popover-light.png" alt="TokMon macOS status bar popover in light mode" width="320"> <img src="docs/images/tokmon-popover-dark.png" alt="TokMon macOS status bar popover in dark mode" width="320"> </p> Clicking the menu bar icon displays real-time statistics, copies the panel screenshot, opens the settings window, or exits the application. ## Function Overview - **Multi-source unified**: Automatically scans local logs/databases of Claude Code, Codex, Kimi Code, Qwen Code, and OpenCode. - **Indicator switching**: Total Tokens, Requests, Input Tokens, Output Tokens, Cache Created, Cache Hit, Hit Rate, Est. Cost. - **Time range**: Today / This Week / This Month / All / Custom quick ranges; Custom can directly select start and end dates in the popover. - **Trend and heatmap**: Supports trend charts, distribution by source/model, and compact activity heatmaps; hit rate and other proportional indicators dynamically adjust the vertical axis according to data distribution, balancing change amplitude and distinguishability. - **Requests and Sessions**: Request log pagination, session details, both support keyword search and filtering; session titles preferentially use session names/project folder names and the first prompt. - **Kimi Quota**: Multi-API Key management, displays weekly quota and 5-hour rolling quota, supports manual or timed refresh; does not display Quota card/tab when API Key is not configured. - **Menu bar display**: Can choose to display Total Tokens, Est. Cost, Requests, Cache Hit Rate, Kimi Weekly Quota, Kimi 5-Hour Quota in the settings. - **Cost estimation**: Supports configuring prices by model or using a global default rate to estimate Est. Cost. - **Appearance adaptation**: Supports light and dark modes, theme color, status bar icon, and text automatically follow the system appearance. - **Screenshot sharing**: Clicking the camera icon in the popover's upper right corner copies the current panel as an image; the first use requests screen recording permission. - **Automatic update**: Built-in Sparkle, can manually or automatically check for GitHub Release updates. ## System Requirements - macOS 14 or higher ## Installation and Download 1. Go to [GitHub Releases](https://github.com/xiehuacheng/TokMon/releases) to download the latest `TokMon-X.Y.Z.dmg`. 2. Open DMG, drag `TokMon.app` into **Applications**. 3. The first launch may prompt Gatekeeper. The current version uses local ad-hoc signing, not Apple notarized, follow system prompts. 4. Launch and click the TokMon icon in the menu bar to start using. For more detailed usage instructions, packaging, and development processes, see [`macos-app/README.md`](macos-app/README.md). ## Quick Start **Development and running** (requires Xcode/Swift 6.0 toolchain): ```bash cd macos-app swift run TokMon ``` **Packaging independent `.app`**: ```bash bash macos-app/scripts/build-app.sh open macos-app/release/TokMon.app ``` The packaged product is located in `macos-app/release/`, ignored by `.gitignore`, not entering Git. ## Interface Description ### Status Bar Popover The popover is divided into four tabs: - **Tokens**: Core indicator cards, trend charts, activity heatmaps, and distribution by source/model. - **Requests**: Request log pagination, displays tokens, model, session, time, and other details for each request; supports search and filtering. - **Sessions**: Statistical list aggregated by session; supports search and filtering. - **Quota**: Kimi API Key quota panel, supports adding, deleting, renaming, and switching keys; hidden when no key is configured. The toolbar buttons in the upper right corner are: refresh, copy screenshot, open settings, check updates, and exit application. ### Settings Window The settings window is divided into the following sections: - **General**: Sets whether to launch at login. - **Sources**: Multi-select data sources to display in the popover (Select All + independent switches for each source), and configure local data paths for each agent. - **Menu Bar**: Choose indicators to display in the menu bar. - **Model Pricing**: Configure input/output/cache creation/cache read unit prices for cost estimation. - **Kimi Quota**: Set the auto-refresh interval for the Kimi quota panel (default 5 minutes, optional Manual / 1 / 5 / 15 / 60 minutes). - **Maintenance**: Manually trigger **Rebuild Database**; immediate refresh button located in the popover toolbar. ## Supported Data Sources TokMon reads the following paths by default, all of which can be modified in the **Sources** section of the settings window. | Data Source | Default Path | Description | | --- | --- | --- | | Claude Code | `~/.claude/projects` | Scans local session logs | | Codex | `~/.codex` | Recursively scans `.jsonl` and `.jsonl.zst` files under `sessions/` and `archived_sessions/` | | Kimi Code | `~/.kimi-code` | Recursively finds `wire.jsonl` logs containing `agents` directories | | Qwen Code | `~/.qwen/projects` | Scans local project logs | | OpenCode | `~/.local/share/opencode` | Reads `opencode.db` SQLite database | ## Configuration and Data TokMon can run with zero configuration. When launched via `.app`, SQLite database, scan status, and local configuration are written to: ```text ~/Library/Application Support/TokMon ``` Common files under this directory: - `tokmon.db`: SQLite database - `tokmon.config.json`: Application configuration, such as source paths - `tokmon-ui-state.json`: UI state (range, indicators, menu bar display items, model prices, etc.) - `tokmon-kimi-keys.json`: Kimi API Key list - `tokmon-kimi-quota-<id>.json`: Quota cache for each key ### Migration from AgentMon On the first launch, if `~/Library/Application Support/TokMon` does not exist and the old `~/Library/Application Support/AgentMon` exists, TokMon automatically migrates the data directory and renames `agentmon.db*` to `tokmon.db*`. If the TokMon directory already exists, it will not be overwritten. ### Scan Version and Database Rebuild `TokMonScanner.scannerVersion` is currently `5`. When scanning or merging semantics change, this version number increments. If the app detects a lower version in local storage upon launch, it automatically rebuilds the database and rescans. ### Data Consistency - Usage records are written to the `usage_records` table, and incremental scan offsets are written to the `tokmon_scan_state` table. - Claude Code's assistant records contain `message_id`, used for deduplication of multiple streaming chunks for the same `message.id`: retains the latest record by `createdAt`; if time is the same, retains the record with larger total tokens. - The denominator/numerator of the hit rate only counts records with `cacheHitSupported` as true; currently, all built-in sources support this, and future additions of sources not supporting this semantic will not dilute the hit rate. ## Project Structure ```text macos-app/ Package.swift # SwiftPM manifest (macOS 14+, depends on Sparkle) Sources/TokMonApp/ # SwiftUI/AppKit status bar app source code Tests/TokMonAppTests/ # Swift tests Assets/ # App icon Packaging/Info.plist # .app bundle metadata scripts/build-app.sh # Independent .app packaging script scripts/build-dmg.sh # Signed DMG and Sparkle appcast.xml generation script README.md # App usage, packaging, and development instructions docs/ images/ # README screenshots ``` The root directory also includes: `AGENTS.md` (general agent collaboration agreement), `CLAUDE.md` (Claude Code specific usage instructions), `LICENSE`. ## Document Entry - [`README.md`](README.md) (this file): Project overview, feature introduction, installation, and quick start. - [`macos-app/README.md`](macos-app/README.md): Detailed usage, development, packaging, and release process for the independent app. - [`AGENTS.md`](AGENTS.md): General agent collaboration agreement, applicable to all AI agents entering this repository. - [`CLAUDE.md`](CLAUDE.md): Claude Code specific usage instructions. ## License [MIT](LICENSE)