KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

nightscout-cgm-skill

★ 57 Open GitHub ↗

GitHub Copilot Agent Skill for Nightscout CGM blood glucose analysis

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Nightscout CGM Skill

[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-Open%20Standard-blue)](https://github.com/agentskills/agentskills)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An [Agent Skill](https://github.com/agentskills/agentskills) for analyzing Continuous Glucose Monitor (CGM) data from [Nightscout](http://www.nightscout.info/). Works with GitHub Copilot CLI, Claude Code, and VS Code agent mode.

![Nightscout CGM Report with interactive charts](https://raw.githubusercontent.com/shanselman/nightscout-cgm-skill/master/images/newcharts.png)

> **⚠️ Disclaimer:** We are not doctors. This is DIY body hacking by and for the diabetes community. If you're using Nightscout, you already know the deal: **don't trust anyone or anything to make decisions about your blood sugar except yourself.** This tool is for informational purposes only and should never replace medical advice, your own judgment, or looking at your actual CGM.

## Features

- **Interactive HTML Reports** - Generate comprehensive local reports with charts (like [tally](https://github.com/davidfowl/tally) for diabetes)
- **Pump/Insulin Integration** - Reports automatically include insulin delivery data if you use Loop/OpenAPS (stacked bolus/basal charts, TDD breakdown)
- **Pump Change Ages** - CAGE/SAGE/IAGE metrics from Nightscout Site/Sensor/Insulin Change treatment events
- **Event Correlations** - Analyze glucose response around existing Nightscout meal, note, carb, and bolus events
- **AGP Reports** - Generate clinical-standard Ambulatory Glucose Profile (AGP) reports for sharing with healthcare providers
- **PDF Export** - Reports include print-friendly styling and a Print / Save PDF action for doctor visits and records
- **Goal Tracking** - Configure local goals for TIR, CV, GMI, and average glucose and see them in reports
- **Refresh-on-Query Sync** - Read-only commands auto-sync stale local data before analysis, with no daemon required
- **Current Glucose** - Real-time blood glucose with trend direction
- **Trend Alerts** - Proactive pattern detection for recurring lows/highs (e.g., "Morning lows 8-10am")
- **Period Comparison** - Compare different time periods side-by-side to track progress
- **Pattern Analysis** - Find your best/worst times, problem days, overnight patterns
- **Specific Day Analysis** - Drill into what happened on a particular date
- **Worst Days Finder** - Find your problem days ranked by peak glucose
- **Time Queries** - "What happens Tuesdays after lunch?" 
- **Terminal Visualizations** - Heatmaps, sparklines, and day charts
- **Statistics** - Time-in-range, GMI (estimated A1C), glucose variability
- **Privacy-First** - All data stored and analyzed locally on your machine

## Ambulatory Glucose Profile (AGP) Reports

Generate clinical-standard AGP reports that match the format used by Dexcom, Libre, and diabetes clinics:

```bash
python scripts/cgm.py agp --days 14 --open
```

![AGP Report Example](https://github.com/user-attachments/assets/5b3abce7-55ae-46a6-986f-dc0a76aa347e)

### AGP Features

- **Standard Percentile Bands** - Shows 5th, 25th, 50th (median), 75th, and 95th percentiles for each hour
- **Glucose Statistics** - Average glucose, GMI (estimated A1C), CV (glucose variability), total readings
- **Time in Ranges** - Visual bar chart showing distribution across all glucose ranges
- **Daily Glucose Profiles** - Last 14 days displayed for pattern recognition
- **Print-Friendly** - Optimized layout for printing and sharing with healthcare providers
- **Clinical Goals** - Displays standard AGP targets (>70% TIR, <4% below range, CV <36%)

The AGP format is recognized by endocrinologists worldwide and makes it easy to discuss your data during appointments.

## Interactive HTML Reports

Generate beautiful, self-contained HTML reports with interactive charts - similar to [tally](https://github.com/davidfowl/tally) but for diabetes/CGM data:

```bash
python scripts/cgm.py report --days 90 --open
```

![Glucose distribution, heatmap, and weekly summary](https://raw.githubusercontent.com/shanselman/nightscout-cgm-skill/master/images/heatmap2.png)

### Report Features

- **Date Range Controls** - Quick buttons for 7d/14d/30d/90d/6mo/1yr/All, plus custom date pickers
- **All charts update dynamically** - No server needed, everything recalculates in your browser
- **Executive Summary** - Deterministic status and concise bullets at the top of the report
- **Section Navigation** - Sticky anchor navigation for long reports
- **Print / Save PDF** - Use the report action button or your browser's print dialog to save a PDF
- **Key Stats Dashboard** - Time-in-Range %, GMI (estimated A1C), CV (variability), average glucose
- **Goal Tracking** - Configurable targets for TIR, CV, GMI, and average glucose
- **7 Interactive Charts:**
  - Time-in-Range pie chart
  - Modal Day (typical 24-hour profile with percentile bands and target range lines)
  - Daily trends (average glucose + TIR per day)
  - Day of week comparison
  - Glucose distribution histogram
  - Time-in-Range heatmap (day × hour) with hover tooltips
  - Weekly summary with week-over-week TIR delta, best day, and context notes
- **Insulin Delivery Section** (for Loop/OpenAPS users):
  - Avg Daily Total (bolus + basal TDD)
  - Bolus/Basal breakdown with ratio
  - Stacked bar chart showing daily insulin (bolus vs basal)
  - Total carbs tracked

### Color Scheme

Uses CGM-style colors (like Dexcom/Libre):
- 🔵 **Blue** for lows (easier to see at a glance)
- 🟢 **Green** for in-range
- 🟡 **Yellow** for highs
- 🔴 **Red** for very high

### Privacy

The report is a single self-contained HTML file. **All your data stays local** - no data is sent anywhere. Open it in any browser, share it with your doctor, or keep it for your records.

## Quick Examples

Just ask naturally:

```
"What's my current glucose?"
"Generate a report of my last 90 days"
"Compare this week to last week"
"Generate an AGP report for my doctor"
"What patterns do you see in my data?"
"What's happening on Tuesdays after lunch?"
"When do I tend to go low?"
"Show me a sparkline of my last 24 hours"
"Show me a heatmap of my glucose"
"What does Saturday look like?"
"What was my worst lunch this week?"
"Show me what happened yesterday during dinner"
"How am I doing vs 90 days ago?"
```

Or use the CLI directly:

```bash
# Generate interactive HTML report
python scripts/cgm.py report --days 90 --open
# Then click "Print / Save PDF" in the report to export a PDF

# View or set local report goals
python scripts/cgm.py goals view
python scripts/cgm.py goals set --tir 75 --cv 34 --gmi 6.8 --average 145
python scripts/cgm.py goals clear

# View or change refresh-on-query sync interval
python scripts/cgm.py auto-refresh view
python scripts/cgm.py auto-refresh set --minutes 15
python scripts/cgm.py auto-refresh off

# Current glucose
python scripts/cgm.py current

# Compare two time periods
python scripts/cgm.py compare --period1 "last 7 days" --period2 "previous 7 days"
python scripts/cgm.py compare --period1 "this week" --period2 "last week"
python scripts/cgm.py compare --period1 "January" --period2 "December"

# Get trend alerts (recurring patterns like morning lows)
python scripts/cgm.py alerts --days 30

# Find patterns (best/worst times, problem areas)
python scripts/cgm.py patterns

# What happened yesterday at lunch (11am-2pm)?
python scripts/cgm.py day yesterday --hour-start 11 --hour-end 14

# Find worst lunch days in last 3 weeks
python scripts/cgm.py worst --days 21 --hour-start 11 --hour-end 14

# Sparkline for a specific date and time window (with colors)
python scripts/cgm.py chart --date yesterday --hour-start 11 --hour-end 14 --color

# Tuesdays after lunch
python scripts/cgm.py query --day Tuesday --hour-start 12 --hour-end 15

# Sparkline of last 24 hours
python scripts/cgm.py chart --sparkline

# Weekly heatmap
python scripts/cgm.py chart --heatmap

# Site/sensor/insulin change ages from treatment events
python scripts/cgm.py ages --count 100

# Correlate existing Nightscout events/treatments with glucose response
python scripts/cgm.py events --tag pizza --days 90
```

## Report Guidance, Goals, and Event Context

The HTML report is designed to be useful without becoming a medical decision system:

- **Executive Summary** uses deterministic rules to summarize the selected date range. It highlights time in range, time below range, variability, and trend-alert context without generating medical advice.
- **Goal Tracking** compares the report period against local goals for Time in Range, CV, GMI, and average glucose. Defaults are based on common clinical targets, and you can override them with `goals set`.
- **Weekly Context** shows recent week-over-week Time in Range deltas, the best day in each week, and a short note so the weekly chart is easier to interpret.
- **Modal Day Target Lines** display the configured target-low and target-high thresholds directly on the 24-hour profile chart.
- **Print / Save PDF** uses the browser's built-in print dialog and print-friendly CSS, avoiding extra PDF dependencies.
- **Event Correlations** use existing Nightscout treatment/event entries such as meal boluses, carb entries, notes, or `foodType` values. The skill does not create or edit annotations locally or in Nightscout.

### Goal Tracking

Goals are stored locally in `config.json` and used by generated reports:

```bash
# Show active goals and defaults
python scripts/cgm.py goals
python scripts/cgm.py goals view

# Set one or more goals
python scripts/cgm.py goals set --tir 75
python scripts/cgm.py goals set --tir 75 --cv 34 --gmi 6.8 --average 145

# Return to defaults
python scripts/cgm.py goals clear
```

Goal fields:

| Option | Meaning | Direction |
|--------|---------|-----------|
| `--tir` | Time in Range percentage | Higher is better |
| `--cv` | Coefficient of variation percentage | Lower is better |
| `--gmi` | Glucose Management Indicator percentage | Lower is better |
| `--average` | Average glucose in mg/dL | Lower is better |

### Refresh-on-Query Sync

This skill does not run a daemon. Instead, read-only analysis/report commands can refresh stale local data before running:

```bash
# Show current refresh-on-query settings
python scripts/cgm.py auto-refresh
python scripts/cgm.py auto-refresh view

# Sync before queries when local data is older than 15 minutes
python scripts/cgm.py auto-refresh set --minutes 15

# Disable or re-enable automatic stale-data refresh
python scripts/cgm.py auto-refresh off
python scripts/cgm.py auto-refresh on
```

Use `refresh --days N` when you want an explicit manual sync.

### Existing Nightscout Event Correlations

If your Nightscout has treatment/event data, you can ask how glucose behaved after matching events:

```bash
python scripts/cgm.py events --tag pizza --days 90
python scripts/cgm.py events --tag workout --days 30 --window-minutes 240
```

The command matches text in Nightscout `eventType`, `notes`, `enteredBy`, `foodType`, and `reason`, compares the 30-minute baseline before the event to the post-event window, and reports average/peak/low response. It is analysis-only; it does not maintain a separate local annotation database.

### Pump Change Ages

For Loop/OpenAPS-style Nightscout instances that upload treatment events:

```bash
python scripts/cgm.py ages --count 100
```

The command reports:

| Metric | Nightscout event |
|--------|------------------|
| CAGE | `Site Change` |
| SAGE | `Sensor Change` |
| IAGE | `Insulin Change` |

CGM-only Nightscout instances return a structured "no treatment data" message instead of failing.

## Privacy & Data Architecture

**Your glucose data stays on your machine.** Here's how it works:

```
┌─────────────────────────────────────────────────────────────────────┐
│                         YOUR MACHINE                                │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────────┐  │
│  │ Copilot CLI │───>│  cgm.py     │───>│ SQLite DB (cgm_data.db) │  │
│  │ (local)     │    │  (local)    │    │ (local file)            │  │
│  └─────────────┘    └──────┬──────┘    └─────────────────────────┘  │
│                            │                                        │
└────────────────────────────┼────────────────────────────────────────┘
                             │ HTTPS (fetch only)
                             ▼
                    ┌─────────────────┐
                    │ YOUR Nightscout │
                    │ (your server)   │
                    └─────────────────┘
```

**What stays local:**
- ✅ SQLite database with your glucose readings (stored in the skill directory)
- ✅ Local `config.json` settings such as goals and refresh-on-query interval
- ✅ All analysis (statistics, time-in-range, GMI, patterns) computed locally by Python
- ✅ The script runs entirely on your machine

**What the AI sees:**
- Only the JSON output you request (e.g., `{"glucose": 152, "status": "in range"}`)
- This is just text in your conversation - same as if you typed it yourself
- The AI cannot access your Nightscout directly or read your SQLite database

**What the AI does NOT have access to:**
- ❌ Your Nightscout URL or API credentials
- ❌ Your SQLite database file
- ❌ Your historical readings (unless you explicitly ask for analysis)

The skill simply runs a local Python script and returns text output. Your health data never leaves your machine except to fetch from your own Nightscout server (which you already trust).

## Prerequisites

- Python 3.8+
- `requests` library (`pip install requests`)
- A [Nightscout](http://www.nightscout.info/) instance with API access

## Installation

### GitHub Copilot CLI / Claude Code (Personal Skill)

```bash
git clone https://github.com/shanselman/nightscout-cgm-skill ~/.copilot/skills/nightscout-cgm
```

Or for Claude Code:
```bash
git clone https://github.com/shanselman/nightscout-cgm-skill ~/.claude/skills/nightscout-cgm
```

### Project Skill (Repository-specific)

```bash
cd your-repo
git clone https://github.com/shanselman/nightscout-cgm-skill .github/skills/nightscout-cgm
```

### Install Dependencies

```bash
pip install requests
```

## Configuration

Set the `NIGHTSCOUT_URL` environment variable to your Nightscout API endpoint.

> **⚠️ Important:** Before configuring, test your Nightscout URL in a browser to ensure it returns JSON data. If your Nightscout instance requires authentication, you'll need to include your API token as a query parameter:
> ```
> https://your-nightscout-site.com/api/v1/entries.json?token=YOUR_API_SECRET
> ```
> You can find or create API tokens in your Nightscout settings under "Admin Tools" → "Subjects".

**Linux/macOS:**
```bash
export NIGHTSCOUT_URL="https://your-nightscout-site.com/api/v1/entries.json?token=YOUR_API_SECRET"
```

**Windows PowerShell:**
```powershell
$env:NIGHTSCOUT_URL = "https://your-nightscout-site.com/api/v1/entries.json?token=YOUR_API_SECRET"
```

**Windows (persistent):**
```powershell
[Environment]::SetEnvironmentVariable("NIGHTSCOUT_URL", "https://your-nightscout-site.com/api/v1/entries.json?token=YOUR_API_SECRET", "User")
```

## Getting Started

After installation and configuration, just start asking questions! The skill automatically fetches your data on first use.

```
> What's my current glucose?

No local data found. Fetching from Nightscout (this may take a moment)...
Fetched 31123 readings. Total: 31123

{"glucose": 142, "unit": "mg/dL", "trend": "Flat", "status": "in range"}
```

Data is cached locally in a SQLite database for fast queries. Run `refresh` periodically to pull in new readings, or just ask the AI to "refresh my CGM data".

## Usage

### With AI Agents

Just ask naturally:

**Basic queries:**
- "What's my current glucose?"
- "Analyze my blood sugar for the last 30 days"
- "What's my estimated A1C?"
- "Show me my time in range"

**Pattern analysis:**
- "What patterns do you see in my data?"
- "What's happening on Tuesdays after lunch?"
- "When are my worst times for blood sugar control?"
- "How are my overnight numbers?"
- "When do I tend to go low?"
- "What day of the week is my best for time-in-range?"
- "Show me my morning patterns"

**Specific day analysis:**
- "What was my worst lunch this week?" (you'll be asked what hours you eat lunch)
- "Show me what happened yesterday during dinner"
- "What were my worst breakfast days the last two weeks?"
- "What did my blood sugar do on January 16th between 11am and 3pm?"

**Visualizations:**
- "Show me a sparkline of my last 24 hours"
- "Show me a heatmap of my glucose"
- "What does Saturday look like?"

**Period comparison:**
- "Compare this week to last week"
- "How does January compare to December?"
- "How am I doing vs 90 days ago?"

### Direct CLI Usage

```bash
# Generate interactive HTML report (opens in browser)
python scripts/cgm.py report --days 90 --open

# Generate report for custom period
python scripts/cgm.py report --days 30 --output my_report.html

# Get current glucose reading
python scripts/cgm.py current

# Analyze last 90 days (default)
python scripts/cgm.py analyze

# Analyze last 30 days
python scripts/cgm.py analyze --days 30

# Get trend alerts (recurring patterns)
python scripts/cgm.py alerts --days 30

# Find patterns automatically (best/worst times, problem areas)
python scripts/cgm.py patterns

# View all readings for a specific date
python scripts/cgm.py day yesterday
python scripts/cgm.py day 2026-01-16 --hour-start 11 --hour-end 14

# Find your worst days (ranked by peak glucose)
python scripts/cgm.py worst --days 21 --hour-start 11 --hour-end 14

# What happens on Tuesdays after lunch?
python scripts/cgm.py query --day Tuesday --hour-start 12 --hour-end 15

# How are my overnight numbers on weekends?
python scripts/cgm.py query --day Saturday --hour-start 22 --hour-end 6

# Morning analysis across all days
python scripts/cgm.py query --hour-start 6 --hour-end 10

# Show sparkline of last 24 hours (compact visual trend)
python scripts/cgm.py chart --sparkline

# Show sparkline of last 6 hours
python scripts/cgm.py chart --sparkline --hours 6

# Show sparkline for a specific date and time range
python scripts/cgm.py chart --date yesterday --hour-start 11 --hour-end 14 --color

# Show week view (one sparkline per day - great for terminals!)
python scripts/cgm.py chart --week --days 14 --color

# Show ASCII heatmap (works inside Copilot)
python scripts/cgm.py chart --heatmap

# Show day chart with colors (direct terminal)
python scripts/cgm.py chart --day Saturday --color

# Generate interactive HTML report (like tally for diabetes)
python scripts/cgm.py report --days 90

# Generate report and open in browser
python scripts/cgm.py report --days 30 --open

# Save report to specific location
python scripts/cgm.py report --days 90 --output ~/my_glucose_report.html

# Generate AGP (Ambulatory Glucose Profile) report - clinical standard format
python scripts/cgm.py agp --days 14 --open

# Generate AGP report with custom period
python scripts/cgm.py agp --days 30 --output ~/agp_report.html

# Configure local report goals
python scripts/cgm.py goals view
python scripts/cgm.py goals set --tir 75 --cv 34 --gmi 6.8 --average 145

# Configure refresh-on-query sync
python scripts/cgm.py auto-refresh view
python scripts/cgm.py auto-refresh set --minutes 15

# Correlate existing Nightscout events/treatments with glucose response
python scripts/cgm.py events --tag pizza --days 90

# Site/sensor/insulin change ages from treatment events
python scripts/cgm.py ages --count 100

# Refresh data from Nightscout
python scripts/cgm.py refresh --days 90
```

### Standalone Terminal Usage

You don't need an AI agent to use this tool! The Python script works great on its own with colorful ANSI output:

```bash
cd ~/.copilot/skills/nightscout-cgm
python scripts/cgm.py chart --week --days 7 --color
```

There's also a PowerShell script that generates a full report:

```powershell
cd ~/.copilot/skills/nightscout-cgm
.\show-all-charts.ps1
```

This outputs:
- 📈 14-day sparklines (one line per day)
- 🗓️ Weekly heatmap
- 📊 Hourly breakdown for each day of the week
- 🔍 Pattern analysis (best/worst times)
- 📋 Full statistics

### Interactive HTML Report

Generate a comprehensive, self-contained HTML report with interactive charts - similar to [tally](https://github.com/davidfowl/tally) but for diabetes data:

```bash
python scripts/cgm.py report --days 90 --open
```

The report includes:
- 🧭 **Section navigation** - Sticky links for jumping through long reports
- 📝 **Executive summary** - Deterministic status and concise report highlights
- 🎯 **Goal tracking** - Configurable TIR, CV, GMI, and average glucose goals
- 📊 **Time-in-Range pie chart** - Visual breakdown of glucose distribution
- 📈 **Modal Day chart** - Your typical 24-hour glucose profile with percentile bands and target range lines
- 📅 **Daily trends** - Day-by-day average glucose and time-in-range
- 🗓️ **Day of week comparison** - Which days are your best/worst
- 📉 **Glucose distribution histogram** - See your glucose spread
- 🔥 **Time-in-Range heatmap** - Identify problem times at a glance
- 📆 **Weekly summary** - Track progress over weeks with TIR delta, best day, and context notes
- 🖨️ **Print / Save PDF** - Browser-based PDF export path for sharing or records

The report is:
- **Self-contained** - Single HTML file with embedded Chart.js
- **Privacy-first** - All data stays local, no external servers
- **Interactive** - Hover for details, responsive design
- **Shareable** - Open in any browser, send to your doctor
- **Print-friendly** - Report actions hide in print and layout avoids floating control overlap

## Output Examples

### Current Glucose
```json
{
  "glucose_mg_dl": 142,
  "trend": "Flat",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "status": "in range"
}
```

### Analysis
```json
{
  "date_range": {"from": "2024-10-17", "to": "2025-01-15", "days_analyzed": 90},
  "readings": 25920,
  "statistics": {"count": 25920, "mean": 138.5, "std": 42.1, "min": 45, "max": 320, "median": 132},
  "time_in_range": {
    "very_low_pct": 0.5,
    "low_pct": 2.1,
    "in_range_pct": 72.3,
    "high_pct": 18.6,
    "very_high_pct": 6.5
  },
  "gmi_estimated_a1c": 6.6,
  "cv_variability": 30.4,
  "cv_status": "stable"
}
```

### Period Comparison
```json
{
  "comparison": {
    "period1": {
      "date_range": {"from": "2026-01-14", "to": "2026-01-21", "description": "Last 7 days"},
      "readings": 2016,
      "statistics": {"count": 2016, "mean": 125.3, "std": 35.2, "median": 118},
      "time_in_range": {
        "very_low_pct": 0.3,
        "low_pct": 1.8,
        "in_range_pct": 78.5,
        "high_pct": 15.2,
        "very_high_pct": 4.2
      },
      "gmi_estimated_a1c": 6.3,
      "cv_variability": 28.1,
      "cv_status": "stable"
    },
    "period2": {
      "date_range": {"from": "2026-01-07", "to": "2026-01-14", "description": "Previous 7 days"},
      "readings": 2016,
      "statistics": {"count": 2016, "mean": 145.8, "std": 42.6, "median": 138},
      "time_in_range": {
        "very_low_pct": 0.8,
        "low_pct": 2.5,
        "in_range_pct": 68.2,
        "high_pct": 21.3,
        "very_high_pct": 7.2
      },
      "gmi_estimated_a1c": 6.8,
      "cv_variability": 29.2,
      "cv_status": "stable"
    }
  },
  "deltas": {
    "average_glucose": {"value": -20.5, "change": "improved", "percentage_change": -14.1},
    "time_in_range": {"value": 10.3, "change": "improved", "percentage_points": 10.3},
    "gmi_estimated_a1c": {"value": -0.5, "change": "improved", "percentage_change": -7.4},
    "cv_variability": {"value": -1.1, "change": "improved", "percentage_change": -3.8}
  },
  "summary": {
    "period1_description": "Last 7 days",
    "period2_description": "Previous 7 days",
    "key_improvements": [
      "Time in range increased by 10.3 percentage points",
      "GMI (estimated A1C) decreased by 0.5",
      "Glucose variability (CV) decreased by 1.1%"
    ],
    "key_regressions": ["No significant regressions"]
  }
}
```

## Glucose Ranges

This skill uses your **Nightscout configuration**:
- **Units**: Automatically detected from your `DISPLAY_UNITS` setting (mg/dL or mmol/L)
- **Thresholds**: Uses your configured `bgLow`, `bgTargetBottom`, `bgTargetTop`, and `bgHigh` values

Default thresholds (if not configured in Nightscout):

| Range | mg/dL | mmol/L | Status |
|-------|-------|--------|--------|
| Very Low | <55 | <3.0 | Dangerous hypoglycemia |
| Low | 55-69 | 3.0-3.8 | Hypoglycemia |
| In Range | 70-180 | 3.9-10.0 | Target range |
| High | 181-250 | 10.1-13.9 | Hyperglycemia |
| Very High | >250 | >13.9 | Significant hyperglycemia |

## Key Metrics

- **GMI (Glucose Management Indicator)**: Estimated A1C calculated from average glucose
- **CV (Coefficient of Variation)**: Glucose variability measure. <36% is considered stable
- **Time in Range**: Percentage of readings in each glucose range

## License

MIT License - see [LICENSE](LICENSE) file.

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## Appendix: How Nightscout Units Work

If you're wondering why we need to convert units when Nightscout already has a `DISPLAY_UNITS` setting - here's the quirk:

**The Nightscout API always returns glucose values in mg/dL**, regardless of your display settings. This is a deliberate design decision:

- **Database storage**: Always mg/dL (integers are easier to store and compare)
- **API responses**: Always mg/dL (the `sgv` field is always in mg/dL)
- **`DISPLAY_UNITS` setting**: Only affects the Nightscout web UI, not the API

So a European user with `DISPLAY_UNITS=mmol` will see `8.4 mmol/L` on their Nightscout dashboard, but the API still returns `"sgv": 152` (mg/dL). Every Nightscout client app (including this skill) must convert values for display if the user prefers mmol/L.

This skill reads your `DISPLAY_UNITS` setting and converts automatically - you don't need to configure anything extra.

## Related

- [Nightscout](http://www.nightscout.info/) - Open source CGM data platform
- [Agent Skills](https://github.com/agentskills/agentskills) - Open standard for AI agent skills
- [GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli) - AI-powered terminal assistant

## Development

### Running Tests

The skill has 281+ tests covering all functionality:

```bash
cd ~/.copilot/skills/nightscout-cgm

# Run all tests
python -m pytest tests/ -v

# Quick run (just pass/fail)
python -m pytest tests/ -q

# With coverage report
python -m pytest tests/ --cov=scripts --cov-report=term-missing

# Run specific test file
python -m pytest tests/test_real_data.py -v
```

**Always run tests before and after modifying cgm.py.**

### Test Structure

| File | Description |
|------|-------------|
| test_pure_functions.py | Unit conversion, stats, sparklines |
| test_database.py | SQLite storage operations |
| test_analysis.py | Pattern analysis, worst days |
| test_charts.py | Chart rendering output |
| test_cli.py | Command-line argument parsing |
| test_edge_cases.py | Error handling, boundaries |
| test_real_data.py | Tests using real Nightscout API responses |
| test_pump.py | Pump commands, treatments, profile, event correlations, change ages |
| test_report.py | HTML/AGP reports, report UX, goal tracking |
| test_coverage_gaps.py | Error handling edge cases |

nightscout-cgm-skill

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README