Oura API Personal Analysis

Use this skill for personal Oura access and local analysis. It is not for shipping a public multi-user integration.

What this skill saves

• client credentials in ~/.local/share/oura-analyzer/.env
• OAuth tokens in ~/.local/share/oura-analyzer/secrets/oura_tokens.json
• pulled data in ~/.local/share/oura-analyzer/data/raw/
• generated reports in ~/.local/share/oura-analyzer/reports/

Check the exact paths any time with:

python3 scripts/oura_analyzer.py paths

One-time setup

1. Create an Oura developer app at https://developer.ouraring.com/applications.
2. For a personal local tool, use these values:

Website: http://localhost:8765
Privacy Policy: http://localhost:8765/privacy
Terms of Service: http://localhost:8765/terms
Redirect URI: http://localhost:8765/callback

1. Copy assets/env.example to ~/.local/share/oura-analyzer/.env and fill in OURA_CLIENT_ID and OURA_CLIENT_SECRET.

mkdir -p ~/.local/share/oura-analyzer
cp assets/env.example ~/.local/share/oura-analyzer/.env

Important:

• Use localhost, not 127.0.0.1, for the callback and placeholder URLs. Oura accepts plain http for localhost but may reject 127.0.0.1.
• Keep the secret only in the local .env file. Do not print it in chat or commit it.

Authorize once

Run:

python3 scripts/oura_analyzer.py authorize --no-browser

Then open the returned URL in a browser where the user is signed in to Oura.

If Oura asks for an emailed one-time code, complete that check and continue to the consent screen. After consent, the tool saves the tokens locally.

Pull and analyze

Pull recent data:

python3 scripts/oura_analyzer.py pull --days 30

Generate a report:

python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/raw/latest_api_pull.json

Reuse the saved connection

After the first authorization, the normal workflow is just:

python3 scripts/oura_analyzer.py pull --days 7
python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/raw/latest_api_pull.json

The script refreshes the access token automatically when the refresh token is still valid.

Export fallback

If the API is unavailable or the user prefers a one-off export:

python3 scripts/oura_analyzer.py import-export --path /absolute/path/to/export/folder
python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/imported/latest_export.json

What the analyzer covers

• sleep duration and sleep score
• readiness score
• activity score, steps, and calories
• recent 7-day versus previous 28-day comparison
• weekday versus weekend sleep behavior
• simple sleep/readiness and steps/readiness correlations
• flagged low-recovery days

Boundaries

• Do not treat API history length as guaranteed. Some accounts only expose a short recent window.
• Do not publish or share the user's client secret, access token, refresh token, or exported data.
• Do not mutate the installed skill bundle with user secrets; keep all state in ~/.local/share/oura-analyzer/.