Totem

Totem gives Claude (or any MCP-compatible AI) full read + write access to your wearable data. Today it speaks Whoop — every metric, through Whoop's private iOS API.

▶ 2-min demo — the full totem cloud flow: install → Whoop login → Fly deploy → Claude connector → first query.

55 tools, structured zod-validated outputs, bundled catalogs (372 exercises, 308 behaviors, 203 sports, 311 endpoints), write-safety harness, automatic Cognito token refresh, bounded in-memory read cache. TypeScript 6, Node 24, 278 tests.

Totem is becoming a universal wearables bridge. Whoop is the first adapter — every metric, fully wired. Fitbit, Apple Watch, and Garmin are in progress (contributors welcome). The MCP + projection layer is device-agnostic; an adapter just maps its source into the same shared schemas, so everything below applies to whatever you wear.

Note: this works through Whoop's private iOS API rather than the public OAuth API. That isn't what Whoop's terms allow — see the FAQ if you want the full picture before installing.

---

Table of contents

1. Get Started
2. Why this exists
3. What it does
4. Architecture
5. The 55 tools
6. Authentication
7. Write-safety harness
8. Bundled catalogs
9. Configuration
10. Remote hosting
    • Deploying to Hugging Face Spaces (free hosting)
11. The totem CLI
12. Privacy + security
13. Troubleshooting
14. Comparison to alternatives
15. FAQ
16. Disclaimers
17. Acknowledgments

Other root-level docs: TOOLS.md (full per-tool reference) · WHOOP.md (full API reference) · CHANGELOG.md · CONTRIBUTING.md · SECURITY.md · LICENSE

---

Get Started

Prerequisites: Node 24+ and a Whoop account (any membership tier).

git clone https://github.com/thebriangao/totem.git
cd totem && npm install && npx tsc && npm link

That puts totem on your PATH (the one-time npx tsc builds it; after that every workflow is a totem command — there are no npm run scripts). Now run one guided command — each handles Whoop login (SMS included), setup, and connecting to Claude from end to end. Pick how you want to run it:

★ Recommended — totem cloud

Deploys the server to a host and connects it to Claude on web, desktop, and mobile, synced across every device on your account. One command walks through: