tokenwatch-docs

Getting Started

Requirements

• Python 3.11 or higher
• macOS, Linux, or Windows
• Claude Code installed and used at least once

Install

pip install tokenwatch

Run

tokenwatch

Your browser opens automatically at http://localhost:7842.

First time setup

1. Set your daily budget — click ⚙ Settings → Daily budget
2. TokenWatch will alert you at 80% and 100% of your budget
3. Use Claude Code normally — costs appear live within 300ms

Auto-start on login

macOS:

bash install_autostart.sh

Linux:

# Create the service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/tokenwatch.service << EOF
[Unit]
Description=TokenWatch

[Service]
ExecStart=/usr/local/bin/tokenwatch --no-browser
Restart=always

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user enable tokenwatch
systemctl --user start tokenwatch

Windows: Add tokenwatch --no-browser to your startup folder. Full auto-start support coming soon.

CLI commands

tokenwatch                        # start dashboard
tokenwatch status                 # print today's cost in terminal
tokenwatch export                 # export sessions to CSV (Pro)
tokenwatch export --format json   # export as JSON (Pro)
tokenwatch seed                   # generate demo data
tokenwatch seed --clean           # remove demo data
tokenwatch config                 # show current config
tokenwatch license --key tw_...   # activate Pro license