| Metric | Value | Copy |
|---|---|---|
| Nights | {{ dayCount }} | |
| Sleep need | {{ formatFixed(sleepNeedValue, 2) }} h/night | |
| Total sleep needed | {{ formatFixed(sleepNeedValue * dayCount, 2) }} h | |
| Total slept (rounded) | {{ formatFixed(total_slept, 2) }} h | |
| Average per night | {{ formatFixed(avg_hours, 2) }} h | |
| Gross deficit | {{ formatFixed(gross_deficit, 2) }} h | |
| Oversleep credit applied | {{ formatFixed(oversleep_credit, 2) }} h | |
| Net sleep debt | {{ formatFixed(net_debt, 2) }} h ({{ debt_readable }}) | |
| Deficit cap | {{ deficitCapDescription }} | |
| Rounding rule | {{ roundingDescription }} | |
| Credit mode | {{ creditModeDescription }} | |
| Max extra per day | {{ formatFixed(maxExtraValue, 2) }} h | |
| Nap allowance | {{ formatFixed(napValue, 2) }} h | |
| Catch-up capacity per day | {{ formatFixed(perDayRecovery, 2) }} h | |
| Catch-up days (est.) | {{ catchup_days }} |
| Night | Slept (h) | Need (h) | Deficit (h) | Credit used (h) | Cum. debt (h) | Copy |
|---|---|---|---|---|---|---|
| {{ r.label }} | {{ formatFixed(r.slept, 2) }} | {{ formatFixed(r.need, 2) }} | {{ formatFixed(r.deficit, 2) }} | {{ formatFixed(r.creditApplied, 2) }} | {{ formatFixed(r.cumDebt, 2) }} |
| Day | Night extra (h) | Nap extra (h) | Remaining debt (h) | Copy |
|---|---|---|---|---|
| {{ r.day }} | {{ formatFixed(r.nightExtra, 2) }} | {{ formatFixed(r.napExtra, 2) }} | {{ formatFixed(r.remaining, 2) }} |
Enter your nightly log to generate sleep debt metrics, charts, and exports.
Sleep debt is the running gap between the sleep you aim to get and the sleep you actually accumulate across recent nights. The idea is simple, but the useful part is seeing how the gap behaves over time instead of reacting to one bad night in isolation. This calculator turns that rolling balance into a visible debt, a daily ledger, and a catch-up estimate.
The package starts with a personal sleep target per night, then looks across either seven or fourteen recent nights. It can round nightly entries to a chosen minute block, cap how much one bad night can count against you, and optionally let longer nights reduce existing debt. Those choices matter because the same raw sleep log can produce a harsher or gentler picture depending on how you want to treat oversleep and extreme short nights.
That makes the tool useful for more than one kind of question. Someone with a typical workweek can check whether a quiet weekend really erased the accumulated shortfall. Someone coming off a restrictive stretch can estimate how many days of extra sleep or naps are needed for recovery. Someone tracking habits can use the daily table and chart to see whether the debt is flattening, growing, or already back near zero.
The result surfaces are deliberately different. The summary table shows gross deficit, oversleep credit, net debt, and recovery assumptions. The daily table shows each night’s rounded hours, deficit, credit applied, and cumulative debt. The catch-up plan converts the remaining balance into days of extra night sleep and naps. The charts show the debt curve over time and a recovery map based on current debt and planned daily recovery capacity.
The main boundary is physiological rather than mathematical. A sleep-debt estimate can help you plan rest, but it is not a diagnosis and it does not replace individual medical advice. Chronic sleep problems, persistent daytime sleepiness, or sleep patterns driven by illness, shift work, or medication need context that a simple debt ledger cannot provide.
The first practical choice is your sleep need target. The package will use whatever nightly target you enter, so the result is only as meaningful as that assumption. If you already work from a consistent personal target, keep it steady across repeated checks. If you are just experimenting, changing the target from one run to the next can tell you more about the assumption than about your recent sleep pattern.
The second choice is the horizon. Seven nights is better for short, recent patterns such as a hard workweek or travel stretch. Fourteen nights is better when you want a smoother view of recurring sleep loss or recovery. A longer horizon will often keep old debt visible even after one or two good nights, which is useful when you want to avoid overcrediting a brief rebound.
Oversleep credit is the most important interpretive toggle. When it is enabled, longer nights can reduce the running debt up to the current balance. When it is off, the tool treats extra sleep as recovery that does not directly erase past loss. Neither approach is universally right. Credit on is better for practical recovery planning; credit off is stricter and makes it easier to see gross shortfall without any forgiveness.
The catch-up plan is best read as capacity, not obligation. Max extra per day and nap allowance tell the package how much extra sleep you think is realistically available in a recovery day. If the resulting plan says six days, that means six days at the current recovery capacity, not six guaranteed days to perfect sleep. The plan is a scheduling aid, not a biological promise.
If you are comparing scenarios, keep one rule fixed while changing another. Compare seven nights against fourteen nights. Compare credit on against credit off. Compare no cap against a two-hour nightly cap. Those one-change comparisons are much easier to interpret than changing the target, horizon, rounding, and credit rules all at once.
The package preprocesses each nightly entry before calculating debt. It optionally rounds the raw sleep duration to the nearest configured minute block, such as 15 minutes, then compares the rounded value against the nightly sleep-need target. From that comparison it derives a nightly deficit. If a deficit cap is set, the nightly deficit is limited to that maximum so one extremely short night cannot dominate the whole horizon.
Once nightly deficits are known, the script walks the nights in chronological order to build a cumulative balance. If oversleep credit is enabled, any night above target can reduce the running balance, but only up to the debt that currently exists. If oversleep credit is disabled, those surplus nights do not erase previous loss. That produces three distinct totals: gross deficit, oversleep credit applied, and final net debt.
The catch-up plan is built from the final balance, not from a generic recommendation. The package adds the allowed extra night sleep and the optional nap allowance to produce a daily recovery capacity. If net debt is positive and that daily recovery capacity is also positive, it creates day-by-day rows until the balance is cleared or until it reaches a hard 60-day planning limit. Each row shows how much extra night sleep, how much nap time, and how much debt would remain after that day.
The charts are calculated from those same ledger rows. The debt-over-time chart uses the cumulative debt after each night across the selected horizon. The recovery map uses current net debt against the available daily recovery capacity, which gives a compact visual summary of whether the plan sits in a fast, moderate, slow, or impossible recovery region under the current assumptions.
The JSON export is a full session payload. It stores inputs, rounded nightly values, summary totals, the daily debt ledger, and the generated catch-up plan. Table exports cover the summary, daily rows, and catch-up plan, while chart exports cover both the debt history and the recovery map. All of that is produced locally from the same input state, with no backend helper in the package.
| Input or rule | Package behavior | Why it matters |
|---|---|---|
| Sleep need | Sets the nightly target in hours | All deficit and credit calculations depend on it |
| Horizon | Uses the last 7 or 14 nights | Changes how quickly old loss or recovery falls out of view |
| Oversleep credit | Allows surplus nights to reduce existing debt | Controls whether recovery nights erase earlier deficit |
| Nightly deficit cap | Limits how much debt one night can add | Stops one extreme short night from dominating the horizon |
| Rounding rule | Rounds nightly sleep to a minute block before scoring | Improves consistency when logs are approximate |
| Catch-up capacity | Adds max extra sleep and nap allowance per recovery day | Turns debt hours into a day-count plan |
| Surface | What it shows | Exports available |
|---|---|---|
| Summary | Total needed sleep, total slept, gross deficit, oversleep credit, net debt, catch-up assumptions | CSV, DOCX, row copy |
| Daily ledger | Each night’s rounded hours, deficit, credit, and cumulative debt | CSV, DOCX, row copy |
| Catch-up plan | Day-by-day extra sleep and nap plan until debt clears | CSV, DOCX, row copy |
| Charts | Debt-over-time curve and recovery map | PNG, WebP, JPEG, CSV |
| JSON | Inputs, totals, daily rows, and catch-up plan | Clipboard copy and JSON download |
Gross deficit tells you how much sleep was lost before any oversleep recovery is counted. Oversleep credit tells you how much of that gross loss was erased by longer nights under the current rules. Net debt is the final balance after both are considered. Those three numbers are more informative together than the debt headline alone.
The daily ledger shows whether the current balance came from steady mild undersleep or from one or two harsh nights. That distinction matters because two people with the same net debt can arrive there in very different ways. The chart makes that pattern easier to see, especially when the debt is flattening or already being paid down by recent recovery nights.
The catch-up days estimate should be read as a schedule assumption, not as a biological certainty. If the tool says three days, that means three days under the current extra-sleep and nap assumptions. It does not guarantee how alert you will feel, how quickly recovery will happen, or whether that plan is realistic in your actual routine.
If the numbers still look implausible, the first things to check are the sleep target, credit mode, and deficit cap. Those settings change interpretation more than tiny differences in one night’s duration.
A user chooses a seven-night horizon with an 8-hour sleep target and sees several short work nights followed by two longer weekend nights. With oversleep credit enabled, the weekend reduces the balance, but the ledger still shows that the debt is not fully cleared. That is a useful correction to the common feeling that “one good weekend fixed everything.”
The same log is run again with oversleep credit disabled. Gross deficit stays the same, credit drops to zero, and the net debt remains higher. That lets the user compare a forgiving recovery view against a stricter “loss only” accounting style.
A user sees a 4-hour net debt and enters 1.5 hours of extra sleep plus a 0.5-hour nap allowance per day. The tool estimates two days of recovery capacity and lays out the remaining balance after each day. That gives a concrete schedule instead of a vague idea that more sleep is needed “soon.”
No. It uses the target you enter. That target may be informed by general guidance, but the package does not diagnose your personal need.
A cap stops one extreme night from dominating the whole horizon when you want a smoother planning view.
That hard limit keeps the plan practical and prevents unrealistic schedules from stretching indefinitely.
Not necessarily. Credit on is useful for practical recovery planning, while credit off shows a stricter gross-loss view.