1---
2name: oura-api-personal-analysis
3description: Set up and reuse a persistent OAuth2 connection to the Oura API for a personal account, cache tokens locally, pull recent Oura data, and generate a local markdown analysis report. Use when the user has an Oura Ring or Oura account and wants a durable local connection instead of repeating manual browser setup.
4allowed-tools: Bash Read
5---
6 
7# Oura API Personal Analysis
8 
9Use this skill for personal Oura access and local analysis.
10It is not for shipping a public multi-user integration.
11 
12## What this skill saves
13 
14- client credentials in `~/.local/share/oura-analyzer/.env`
15- OAuth tokens in `~/.local/share/oura-analyzer/secrets/oura_tokens.json`
16- pulled data in `~/.local/share/oura-analyzer/data/raw/`
17- generated reports in `~/.local/share/oura-analyzer/reports/`
18 
19Check the exact paths any time with:
20 
21```bash
22python3 scripts/oura_analyzer.py paths
23```
24 
25## One-time setup
26 
271. Create an Oura developer app at `https://developer.ouraring.com/applications`.
282. For a personal local tool, use these values:
29 
30```text
31Website: http://localhost:8765
32Privacy Policy: http://localhost:8765/privacy
33Terms of Service: http://localhost:8765/terms
34Redirect URI: http://localhost:8765/callback
35```
36 
373. Copy `assets/env.example` to `~/.local/share/oura-analyzer/.env` and fill in `OURA_CLIENT_ID` and `OURA_CLIENT_SECRET`.
38 
39```bash
40mkdir -p ~/.local/share/oura-analyzer
41cp assets/env.example ~/.local/share/oura-analyzer/.env
42```
43 
44Important:
45 
46- 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`.
47- Keep the secret only in the local `.env` file. Do not print it in chat or commit it.
48 
49## Authorize once
50 
51Run:
52 
53```bash
54python3 scripts/oura_analyzer.py authorize --no-browser
55```
56 
57Then open the returned URL in a browser where the user is signed in to Oura.
58 
59If Oura asks for an emailed one-time code, complete that check and continue to the consent screen.
60After consent, the tool saves the tokens locally.
61 
62## Pull and analyze
63 
64Pull recent data:
65 
66```bash
67python3 scripts/oura_analyzer.py pull --days 30
68```
69 
70Generate a report:
71 
72```bash
73python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/raw/latest_api_pull.json
74```
75 
76## Reuse the saved connection
77 
78After the first authorization, the normal workflow is just:
79 
80```bash
81python3 scripts/oura_analyzer.py pull --days 7
82python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/raw/latest_api_pull.json
83```
84 
85The script refreshes the access token automatically when the refresh token is still valid.
86 
87## Export fallback
88 
89If the API is unavailable or the user prefers a one-off export:
90 
91```bash
92python3 scripts/oura_analyzer.py import-export --path /absolute/path/to/export/folder
93python3 scripts/oura_analyzer.py analyze --input ~/.local/share/oura-analyzer/data/imported/latest_export.json
94```
95 
96## What the analyzer covers
97 
98- sleep duration and sleep score
99- readiness score
100- activity score, steps, and calories
101- recent 7-day versus previous 28-day comparison
102- weekday versus weekend sleep behavior
103- simple sleep/readiness and steps/readiness correlations
104- flagged low-recovery days
105 
106## Boundaries
107 
108- Do not treat API history length as guaranteed. Some accounts only expose a short recent window.
109- Do not publish or share the user's client secret, access token, refresh token, or exported data.
110- Do not mutate the installed skill bundle with user secrets; keep all state in `~/.local/share/oura-analyzer/`.
111