Introduction
What the Energy System is, the wh/ph/sd model behind it, and the five energy levels your app can adapt to.
@kumbatio/energy-system is a framework-agnostic TypeScript SDK for building energy-aware applications - software that adapts to the user's current cognitive capacity instead of assuming a constant one. The user declares their energy level; your app resolves behavior from it.
No biometrics, no inference from typing speed. Self-reported, explicit state that any layer of your app can read.
The model: energy ≠ time
Most software assumes equal capacity across a day. Real cognitive energy is variable and non-linear. Three metrics tell the story:
- Work Hours (wh) - total time present
- Productive Hours (ph) - the focused subset of that time
- Stuff Done (sd) - measurable output
The constraint is always ph ≤ wh. Extending time does not linearly increase productive output - forcing 160wh doesn't produce 160ph, it produces 80–100ph stretched across more calendar, with worse quality from fatigue and context switching.
The goal isn't working more or less. It's working when you're actually capable of producing results - and having software that cooperates. Read the full argument in Energy over Time.
The five levels
Energy is modeled as five discrete levels, not a slider. Fewer choices mean less decision fatigue (critical exactly when energy is low), and clear boundaries make adaptation rules predictable.
| Level | Key | What it means |
|---|---|---|
100 | peak | High capacity. Planning, complex decisions, creative work. |
75 | active | Good capacity. Focused execution, problem-solving. |
50 | steady | Moderate capacity. Routine tasks, familiar work. |
25 | low | Limited capacity. Simple tasks, review, light work. |
0 | rest | Recovery. Consumption only - reading, reflecting. |
Each level carries a cognitive profile - what kind of decisions, focus, and interruptions the brain can handle there - so strategies adapt to capability, not just to a number.
What the SDK gives you
- A core engine - immutable, revisioned energy state with subscriptions, persistence, and deterministic cross-context reconciliation
- Strategies - pure
(level) => configmappings; seven built-ins cover UI visibility, notifications, task complexity, interaction forgiveness, deferral ordering, agent autonomy, and inbound-demand admission - Presence annotation - declare which levels a component belongs to (
defineEnergyPresence,<EnergyGate>, or plaindata-energy-minattributes) - A behavioral runtime - a notification gate that enforces the notification config (defer, never drop) and focus sessions that always end on time
- Adapters - React provider and hooks, a DOM adapter, a reference stylesheet, and pluggable persistence
When to use it
Use the Energy System when your app has anything worth adapting: chrome that could get out of the way, notifications that could wait, tasks that could be re-ordered, or destructive actions that deserve a bigger undo window at low capacity.
It works anywhere TypeScript runs - web, desktop, CLI. The core has zero dependencies; React is an optional peer.
This package is in production in three apps: kumbat.io runs its entire interface on it - move the energy control on the site and watch the UI adapt - Anasa (public alpha) builds its adaptive writing workspace on it, and Meltemi, an email client from entro314 labs built outside the Kumbatio product line, runs its notification deferral and focus sessions on it. Two further entro314 labs apps are integrated pre-release: Entromail (webmail) and Equidock (desktop canvas). See Production Patterns for what real integrations look like.
Where to go next
Getting started
Install the package and run your first engine in two minutes.
Core quickstart
Create an engine, set levels, subscribe, resolve strategies.
React quickstart
Provider, hooks, and the EnergyGate component.
Strategies
The adaptation model and the built-in strategies.
energy-system supports self-management and workflow adaptation. It is not a medical device, diagnosis tool, or treatment.