TokenVigil

English | 简体中文

TokenVigil is a local-first auditing system for tracking token usage and estimated cost from coding-agent sessions. It combines a native macOS dashboard with an installable CLI for project-scoped, passive monitoring. The CLI reads local Claude Code and Codex usage metadata, can observe aggregate HandoffWire activity, and exposes reports only to the configured project orchestrator.

The CLI's Angela audit contract detects session concentration, context growth, low cache reuse, excessive turns, repeated resets, model-tier mismatch, possible duplicate work, and HandoffWire routing anomalies. Model-tier, reset, and duplicate-work findings are explicitly labeled as inference when metadata cannot prove intent. Reports always retain privacy.content_captured: false.

The app is built with Swift, AppKit, and the macOS App Sandbox. TokenVigil does not send your usage data anywhere.

Screenshots

Features

• Native macOS menu bar and window experience
• Total usage, today, recent 30 days, and recent 12 months views
• Token and cost breakdowns by provider and model
• Calendar heatmap and chart views for trend scanning
• Session-level review with model, project, token, cost, and record counts
• Local parsing for Claude Code JSONL, Codex rollout JSONL, and opencode SQLite data
• Security-scoped bookmark access for sandbox-friendly local file permissions
• Embedded LiteLLM pricing snapshot with hand-tuned pricing overrides for common models

Supported Sources

TokenVigil never opens a file picker automatically at launch. In Settings, use the Data Folders section to choose only the providers you use.

Each provider stores an independent read-only security-scoped bookmark. Leaving one provider unselected does not block selected providers.

Privacy

TokenVigil is designed as a local-only utility.

• It reads a provider folder only after you explicitly choose that folder in the standard macOS open panel.
• It stores one security-scoped bookmark per selected provider in UserDefaults so it can reopen that folder later.
• It does not upload usage records, project paths, prompts, responses, or pricing data.
• It does not include analytics or telemetry.

The app may display local project paths from the agent logs because those paths are part of the source data. See the Privacy Policy.

Install

For the reusable CLI and Angela audit integration, follow INTEGRATION.md. The short path is:

./install.sh --with-codex-skill
cd /path/to/project
tokenvigil --json init --orchestrator "Michael - Orchestrator" --auditor Angela
tokenvigil --json doctor

The native dashboard can be installed separately:

Download the latest packaged app from the GitHub Releases page:

1. Download TokenVigil-macOS-universal.zip from the latest release.
2. Unzip the archive.
3. Move TokenVigil.app to /Applications.
4. Open TokenVigil. Launch does not open a file picker.
5. Open Settings and, in Data Folders, choose the folder for each provider you use.

If macOS says TokenVigil.app is damaged and can't be opened. You should move it to the Trash., confirm that the app came from the official TokenVigil release page, then go to System Settings > Privacy & Security. In the Security section, click Open Anyway for TokenVigil, then open TokenVigil again and choose Open when prompted.

To build from source instead:

1. Clone the repository.
2. Open TokenVigil.xcodeproj in Xcode.
3. Select the TokenVigil scheme.
4. Build and run on macOS.
5. Open Settings and choose provider folders in Data Folders.

First Run

TokenVigil does not request access at launch. Open Settings, find Data Folders, and choose each provider's data folder with the standard macOS folder picker. You can cancel without changing that provider's existing selection or data.

Selected providers load independently. An unselected provider shows that its folder has not been selected; an empty selected folder shows that no data was found. You can refresh manually from the window or menu bar popover, and change automatic refresh intervals in Settings.

Build

Requirements:

• macOS 15.0+
• Xcode 16.4+
• Swift 6.0

Build the app:

xcodebuild -project TokenVigil.xcodeproj -scheme TokenVigil -configuration Debug build

Run unit tests:

xcodebuild -project TokenVigil.xcodeproj -scheme TokenVigil -destination 'platform=macOS' -only-testing:TokenVigilTests test

Run all tests:

xcodebuild -project TokenVigil.xcodeproj -scheme TokenVigil -destination 'platform=macOS' test

Architecture

Each provider owns its scanner, parser, selected data-root contract, and read-only security-scoped bookmark, then emits shared ParsedUsageEntry values. PricingEngine and UsageAggregator turn those entries into summaries that are rendered by AppKit view controllers. Provider authorization and loading states remain independent in TokenStatsViewModel.

Provider scanner/parser
        |
        v
ParsedUsageEntry
        |
        v
PricingEngine + UsageAggregator
        |
        v
TokenStatsViewModel
        |
        v
AppKit sidebar, charts, menu bar popover

Key directories:

TokenVigil/
  Analytics/       Aggregation logic
  Models/          Shared usage and pricing models
  Pricing/         Pricing table, LiteLLM catalog, cost engine
  Providers/       Claude Code, Codex, and opencode adapters
  Services/        Security-scoped bookmark management
  ViewControllers/ AppKit UI
  ViewModels/      Provider state coordination

TokenVigilTests/   Swift Testing unit tests
TokenVigilUITests/ XCTest UI tests

Pricing Data

TokenVigil estimates cost from embedded pricing data. Prices can drift from upstream provider billing, so treat app totals as an estimate rather than an invoice. Unknown models fall back to upstream cost when the source provides it; otherwise their cost may be shown as zero until pricing data is updated.

Contributing

Issues and pull requests are welcome. Please keep changes focused and include tests for parser, pricing, aggregation, or UI behavior when relevant.

For local agent guidance, see AGENT_GUIDE.md.

License

TokenVigil is licensed under the GNU General Public License v3.0 or later. See LICENSE.