Monitor your Claude.ai usage limits directly from Home Assistant.
Claude Pulse is a Home Assistant custom integration that exposes your Claude.ai session (5-hour) and weekly (7-day) usage as native sensors — so you always know how much Claude you have left before hitting a limit, right from your dashboard.
- 📊 Session usage — percentage of your 5-hour window, plus a live countdown to the next reset
- 📅 Weekly usage — percentage of your 7-day window, plus reset day and time
- 📖 Fable quota — optional weekly usage sensor for the Fable model, toggleable in the options (on by default, safe to disable if the quota changes)
- 🔄 Auto-refresh — polls Claude.ai every 2 minutes by default (configurable, 30s minimum)
- 🔐 Built-in re-authentication — Home Assistant notifies you when your session key expires and guides you through renewing it
- 🧩 Fully UI-based setup — config flow with live credential validation, no YAML required
- 🛰️ Individual sensors — every data point exposed as its own Home Assistant entity, grouped under one device
Claude Pulse is available in the default HACS store.
- Click the button above, or open HACS in your Home Assistant sidebar and search for Claude Pulse
- Click Download and confirm
- Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration and search for Claude Pulse
- Enter your Session Key and Organization ID (how to get them)
- Download the latest release
- Copy the
custom_components/claude_pulsefolder into your Home Assistantconfig/custom_components/directory - Restart Home Assistant and add the integration as in steps 4–5 above
Requires Home Assistant 2024.1.0 or newer.
- Open claude.ai in your browser and log in
- Open DevTools (
F12) → Application → Cookies →https://claude.ai - Copy the value of the
sessionKeycookie
- Still in DevTools, open the Network tab and reload the page
- Find any request whose URL contains
/api/organizations/ - Copy the UUID from that URL (format:
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
⚠️ Your session key is a credential — treat it like a password. It is stored only inside your Home Assistant instance and is sent exclusively toclaude.ai.
All entities are grouped under a single Claude Pulse device:
| Entity | Description | Unit |
|---|---|---|
sensor.claude_pulse_session_usage |
Session usage (5-hour window) | % |
sensor.claude_pulse_weekly_usage |
Weekly usage (7-day window) | % |
sensor.claude_pulse_session_reset_countdown |
Time until the session resets (e.g. 2h 30m) |
— |
sensor.claude_pulse_session_reset_time |
Clock time of the next session reset | — |
sensor.claude_pulse_weekly_reset |
Weekly reset summary (e.g. Friday @ 03:45 AM) |
— |
sensor.claude_pulse_weekly_reset_weekday |
Day of the week of the weekly reset | — |
sensor.claude_pulse_weekly_reset_time |
Clock time of the weekly reset | — |
sensor.claude_pulse_session_used |
Session used (alias of session usage) | % |
sensor.claude_pulse_session_limit |
Session limit (always 100) | % |
sensor.claude_pulse_plan |
Subscription plan (diagnostic) | — |
sensor.claude_pulse_fable_usage |
Fable model usage (weekly) — only when the Fable quota option is enabled | % |
sensor.claude_pulse_fable_reset |
Fable reset summary (e.g. Friday @ 03:45 AM) — only when the Fable quota option is enabled |
— |
Exact entity IDs may vary depending on the device name Home Assistant assigns. Find yours in Developer Tools → States filtering by
claude_pulse.The Fable sensors are created only while the Enable Fable quota tracking option is on. The Fable quota is an unofficial, recently added component of the usage API and may change or disappear — if it does, turn the option off to remove the sensors. When your account exposes no Fable quota, the sensors report
unavailable.
You can monitor several Claude.ai accounts at once: add the integration once per account (Add Integration → Claude Pulse again) and give each entry its own Name, e.g. Private and Work. Each account gets its own device and entity IDs such as sensor.private_session_usage and sensor.work_session_usage.
Copy each account's session key from a separate browser profile or private window. Logging out of an account on claude.ai invalidates its session key.
Get notified before you burn through your session:
automation:
- alias: "Claude session almost exhausted"
trigger:
- platform: numeric_state
entity_id: sensor.claude_pulse_session_usage
above: 80
action:
- service: notify.mobile_app_your_phone
data:
title: "Claude Pulse ⚠️"
message: >
Claude session at {{ states('sensor.claude_pulse_session_usage') }}%.
Resets in {{ states('sensor.claude_pulse_session_reset_countdown') }}.After setup, click Configure on the integration to change:
| Option | Description | Default |
|---|---|---|
| Session Key | Your sessionKey cookie from claude.ai |
— |
| Organization ID | Your Claude organization UUID | — |
| Update interval | Polling frequency in seconds (minimum 30) | 120 |
| Enable Fable quota tracking | Expose the Fable model weekly quota as sensors (may change/disappear) | Enabled |
| Symptom | Cause & fix |
|---|---|
| Authentication failed (HTTP 401/403) | Your sessionKey cookie expired. Go to Settings → Devices & Services → Claude Pulse → Configure and enter a new one. |
| All endpoints return 404 | Wrong Organization ID. Verify it via DevTools → Network → requests to /api/organizations/. |
Sensors show unavailable after setup |
Check Settings → System → Logs for claude_pulse errors. Network errors at startup are retried automatically. |
| Repair notification for Claude Pulse | Session key expired. Click the notification to open the re-authentication form. |
Two accounts show the same data / one is unavailable |
Fixed in 1.2.0 — earlier versions shared one cookie jar between all entries. Update and reload both entries. |
Still stuck? Open an issue with your Home Assistant logs.
If you prefer not to use the integration, the original standalone files are still in the repo:
| File | Location | Description |
|---|---|---|
claude_usage.py |
/config/ |
Python script that fetches usage from claude.ai |
claude_usage.yaml |
/config/packages/ |
command_line sensor + template sensors |
See the git history for setup instructions for this approach.
Issues and pull requests are welcome! Every push runs HACS and Hassfest validation via GitHub Actions. See AGENTS.md for an overview of the codebase.
MIT — do whatever you want with it.
Claude Pulse is an unofficial project and is not affiliated with Anthropic.