GeezerVison

Your coffee, your sleep, your body. Free, no login, runs in your browser.

CaffeineSense is a prototype calculator for one question: when should my last coffee be? It runs a one-compartment pharmacokinetic model on your age, weight, smoking, pregnancy, hormonal contraception and CYP1A2 genotype, and works out your personal caffeine half-life, how much caffeine is still in your body at bedtime, and the latest time one more drink keeps that residual under 50 mg (half the Drake 2013 sleep threshold the model uses). For one 8 oz coffee and an 11 p.m. bedtime, that latest time runs from 9:35 a.m. (third-trimester pregnancy) to 9:00 p.m. (a smoker with fast CYP1A2) across the profiles in results/cutoff_grid.json.

▶ See this project in the film Show Its Work: https://youtu.be/pefnyZ-oCcM?t=2425

About 85% of US adults consume caffeine daily, and about 35% report a sleep complaint (Mitchell 2014; CDC 2024, cited in the paper). The standard public advice, "no coffee after 2 PM", is uncalibrated folklore: the documented half-life of caffeine varies from 2 h (smoker, fast CYP1A2) to 15 h (third-trimester pregnancy), a 7x difference that no popular calculator surfaces.

CaffeineSense takes your personal covariates and your day's caffeine schedule, and tells you:

• Your personal caffeine half-life
• The body-caffeine trajectory over the next 36 hours
• The predicted sleep-onset delay at your target bedtime
• The latest time you can have one more coffee for clean sleep
• Four ranked interventions if your current schedule will hurt your sleep

The same model ships twice: as a Python library and as a static web page that keeps everything in your browser.

The frontend is static; no build step.

cd frontend
python3 -m http.server 8000     # or, from the repo root: make frontend
# open http://127.0.0.1:8000/

The four files (index.html + app.js + styles.css + about.html) total about 30 KB raw, about 10 KB gzipped. Drop them on any static host (GitHub Pages, S3, Cloudflare Pages, Netlify) and they work. $0 operating cost.

pip install -e .        # Python 3.9+, pulls in numpy and matplotlib

from caffeinesense import (
    Person, BEVERAGES, simulate_day, latest_safe_dose_time,
)

me = Person(age=35, weight_kg=70, smoker=False, pregnant=False,
            hormonal_contraception=False, cyp1a2="intermediate")
schedule = [(7.0,  BEVERAGES["coffee_drip_12oz"]),
            (10.5, BEVERAGES["espresso_double"]),
            (14.0, BEVERAGES["coffee_drip_8oz"])]
sim = simulate_day(me, schedule, bedtime_h=23.0)
print(f"At bedtime: {sim.body_burden_at_bedtime_mg:.1f} mg remaining")
print(f"Sleep onset delay: +{sim.sleep_onset_delay_min:.0f} min")
print(f"Half-life: {sim.person_half_life_h:.1f} h")

cutoff = latest_safe_dose_time(me, dose_mg=96.0, bedtime_h=23.0)
print(f"Latest 8 oz coffee for clean sleep: {cutoff:.2f} h")

Times are decimal hours on the same clock as the schedule (23.0 is 11 p.m.).

pip install pytest  # needed for make test; not a package dependency
make experiments    # validation, scenarios, cutoff grid -> results/*.json
make figures        # paper/figures/*.pdf (re-runs the experiments first)
make paper          # paper/caffeinesense.pdf (needs pdflatex and bibtex)
make test           # 17 unit tests

The Makefile calls python3 with PYTHONPATH=., so it expects a Unix-style shell (Linux, macOS, or Git Bash/WSL on Windows).

caffeinesense/   Python library: PK model, sleep impact, scheduler, interventions
frontend/        static web app (no build step, no dependencies)
experiments/     validation, scenario, and cutoff-grid scripts
results/         JSON outputs of the experiments
paper/           LaTeX source and compiled PDF
tests/           unit tests

All 11 documented covariate combinations (baseline, smoker, pregnant T1/T2/T3, hormonal contraception, elderly, child, CYP1A2 fast/slow, contraception + slow CYP1A2) reproduce published caffeine half-life within published ranges (Carrillo & Benitez 2000, Anderson 2015, Pollock 1999, Blanchard & Sawers 1983, EFSA 2015, Sachse 1999; the contraception + slow CYP1A2 band comes from case reports). See results/validation.json (11/11 within range) and the paper.

This checks the half-life part of the model. The sleep-impact step is calibrated to Drake 2013 rather than validated separately; see What CaffeineSense is not below.

CaffeineSense does not phone home. No network calls, no analytics, no cookies. Your body profile is stored only in your browser localStorage.

Public domain (CC0 1.0). See LICENSE.

• Not a medical device. If you have a relevant condition (anxiety, palpitations, pregnancy, paediatric use), consult a physician.
• Not a tolerance model. Daily users adapt; the Drake 2013 sleep impact was measured in caffeine-naive sleepers, so chronic drinkers may experience smaller effects at the same residual.
• Not a drug-interaction database. We don't model co-administered drugs that induce/inhibit CYP1A2 (ciprofloxacin, fluvoxamine, etc.).