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

---

About 85% of US adults consume caffeine daily, and 35% report sleep complaints partially attributable to caffeine. 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

Running the frontend

The frontend is static; no build step.

cd frontend
python3 -m http.server 8000
# open http://127.0.0.1:8000/

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

Running the Python library

pip install -e .

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")

Running the experiments

make experiments   # validation, scenarios, cutoff grid -> results/*.json
make figures       # paper/figures/*.pdf
make paper         # paper/caffeinesense.pdf
make test          # 17 unit tests

Project layout

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

Validation

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, Sachse 1999). See results/validation.json and the paper.

Privacy

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

License

Public domain (CC0 1.0). See LICENSE.

What CaffeineSense is not

• 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).