Documentation
Everything you need to install pulse, import your data, control your privacy, and trust the numbers. Links to external docs (INSTALL, TROUBLESHOOTING, ROADMAP, source code) open on GitHub.
Quickstart
Download installer, click through wizard, dashboard opens in your browser. SmartScreen workaround included.
Run from source today (Python 3.12). Packaged universal2 .app planned Q3 2026 once Apple Developer ID is set up.
Run from source today on any X11 or Wayland desktop. AppImage planned Q4 2026 once community testers are confirmed.
git clone + pip install + python app.py. Works on Windows, macOS, and Linux today.
Importing your data
Pulse auto-detects ~/.claude/projects/*.jsonl on first launch. Set CLAUDE_LOG_DIR if your config is elsewhere. Manual import in Settings → AI usage.
Paste your Admin API key in Settings → Provider API keys for team-level attribution beyond a single machine. Stored locally.
Subscriptions tab → Add subscription. Pick a plan from the catalog (Claude Max / ChatGPT Plus / Cursor / …) or enter a custom price.
Settings → Preferences → Currency. 30+ currencies via daily ECB rates from frankfurter.dev (cached 24h).
Privacy & security
Opt-in only — off by default. Settings → Preferences → Privacy & activity tracking. Master toggle, store-titles toggle, blocklist, pause buttons.
If you turn activity tracking on, leave 'Also store window titles' OFF. Pulse will still log which app you used but never the title (which may contain document names, tab content, customer info).
Settings → Preferences → Privacy → Pause buttons (1 hour / until tomorrow / 1 week). The tracker picks up changes within 60 seconds without a restart.
Settings → Preferences → Privacy → Delete activity history. Tick the confirm checkbox first — deletes every row from app_activity, irreversible.
Backup, export, and data location
All data is in a single SQLite file under your user profile. See the data-location table on the Download page for the exact path per OS.
Pulse rotates SQLite backups daily and keeps the last 7. Located in pulse/backups/ inside your user profile.
Settings → Data & backup → Export. Generates a CSV of subscriptions, AI usage, and activity. Open in Excel / Sheets / your finance tool.
Settings → Data & backup → Restore. Pick a .db file from pulse/backups/ — the current DB is moved aside automatically.
Self-hosting the cloud server
Free, MIT-licensed, no rate limit. Bring your own Supabase project. Pulse Pro hosting is a convenience tier, not a feature gate.
cloud/auth.py, cloud/sync.py, cloud/crypto.py, api/server.py. Argon2id + AES-256-GCM, FastAPI server. Scaffolded today, deploys with v1.1 (Q3 2026).
Create a free project, run the schema in ROADMAP.md § 1.2, set SUPABASE_URL + SUPABASE_ANON_KEY env vars on your client.
How pulse calculates things
Plan ROI = Equivalent API Value ÷ Subscription Cost. Token counts come from your local Claude logs; prices come from Anthropic's published rates.
Most tools lump cache writes together — pulse splits 5-minute and 1-hour TTLs at their respective rates. Off by up to 60% otherwise.
Subscription cost ÷ foreground hours where the linked app was the active window (idle excluded). Activity tracking must be opted in.
monthly_cost × months_since_cancellation_date, summed across every cancelled subscription. Cumulative counter from cancellation date forward.
Security model
What pulse assumes is trusted (your machine) and what it doesn't (the cloud — once it exists). Master password is the root of trust for cloud sync.
Local SQLite is unencrypted by default — use BitLocker / FileVault. Per-row AES-256-GCM is designed for Pro cloud sync but not yet shipped.
No certifications today (MIT local app needs none). SOC 2 Type I planned for Team tier. SOC 2 Type II + ISO 27001 + HIPAA-ready architecture on the Enterprise roadmap.
Email security@mintforai.com — do not file a public issue. Acknowledgement within 24 hours, critical fixes within 7 days.
Troubleshooting
SmartScreen / Defender, dashboard didn't open, Claude logs not detected, port conflicts, FX rate fetch failure, uninstall clean.
Windows: Settings → Apps → pulse → Uninstall → choose 'No' to keep data. From-source: delete the cloned repo and pulse user-profile folder.
Pulse looks at ~/.claude/projects/*.jsonl. If you've moved your Claude config, set CLAUDE_LOG_DIR. Manual import button in Settings → AI usage.
GitHub Discussions for questions, Issues for bug reports, hi@mintforai.com for anything else. There's no Discord yet (planned with Pro).
FAQ by audience
How exact are the numbers? Where does the pricing table live? Can I rip ROI logic into my own tool? Why Python + Streamlit? Read the pricing source in sync_tokens.py.
Why MIT-licensed? Does pulse phone home? Will I lose data if I uninstall? Is the Pro plan a lock-in? What happens if you stop developing pulse?
How does pulse compare to Mint / YNAB / Vantage / Datadog? Is it ready for a 10-person team? What's the cloud cost model if we hit 1,000 employees?
What's stored on disk? What's the only outbound network call? Can I run fully air-gapped? Why is activity tracking opt-in?
Can't find what you need?
Pulse is solo-built. If a doc is missing or wrong, the fastest fix is to open a Discussion — most "missing docs" turn into a real doc within a few days. Bug reports go in Issues.