Limits: energy
Every prompt burns real electricity and water in a real data center. This skill makes that cost visible — as an honest floor estimate, not a guilt trip and not a fake precision instrument.
Pairs with limits-setup, which writes the config this skill reads.
The honesty contract (binding on you, the agent)
-
Inform by default; gate only by explicit opt-in. Energy numbers inform. The one exception is a budget the user set with
ENERGY_BUDGET_MODE=restrict, chosen eyes-open in the interview — then the gate is theirs, and the honesty burden doubles: they are being governed by a floor estimate on purpose, and every refusal says so. -
Cited figures only, provenance inline. The two published anchors, with what they cover:
- ~0.24 Wh — Google's published median for a Gemini Apps text prompt (2025). Includes accelerator, host CPU/memory, backup equipment, and datacenter overhead including cooling; excludes training.
- ~0.34 Wh — OpenAI's figure for an "average" ChatGPT query (2025, from Sam Altman's blog). Not peer-reviewed; "average query" is undefined.
Both are vendor self-reported. Say so when asked.
-
Never invent a conversion. There is no published per-token energy figure — do not create one. Nobody has published figures for agentic coding sessions either; they involve far more computation per turn than a median chat prompt, which is exactly why every estimate here is a floor.
-
No shame mechanics. The footer is information; the budget is theirs; crossing it changes what you say, never what you do.
Estimating: count turns, multiply, call it a floor
A "turn" is one model call — each response, including each tool-use step in an agentic session, is one. Turns are countable; per-turn cost is not knowable, so:
estimated floor = (turns you can count) × 0.24 Wh (the conservative anchor)
The footer shows only the result (see Rendering); the method stays one
question away — when they ask "how was this measured", give the math, the
turn count, and both anchors with provenance. When you cannot count turns
on a surface, estimate the count conservatively and say you did. Never
present a result without its floor marker: a trailing + on the number
(36+ Wh), which reads naturally and stays true — the real cost is
higher, never lower.
Rendering: keep it light
One terse line, emoji that scale with the magnitude, no method talk.
End-of-session footer (only when ENERGY_FOOTER=yes in
~/.config/ai-limits/config, or on request; skip it in automated
sessions):
💡💡💡💡💡💡 6+ Wh this session · lights on for ~40 min
At bigger totals, switch units so the emoji stay meaningful:
📱📱📱 51+ Wh this week · 3 full phone charges · lights on for ~5 hours
Rules:
- The number: counted turns × 0.24 Wh, rounded, with a trailing
+carrying the floor. - 💡 one per Wh, capped at ten. 📱 one per full phone charge (~15 Wh), capped at ten — use phones once bulbs stop being legible.
- Felt equivalents: lights-on time = Wh ÷ 10 W LED; a phone charge ≈ 15 Wh. Month- and year-scale equivalences (✈️ flights and beyond) need cited energy-to-carbon conversions — that's the energy tracker's job, not this footer's.
- Nothing else on the line. Method and provenance are answers, not furniture.
Like everything text-shaped, the footer is advisory on every surface
(see the enforcement matrix in limits-setup). It works by being followed.
The weekly budget (optional, three modes)
The interview offers four paths; config records them:
| Choice | Config | Behavior |
|---|---|---|
| No thanks | ENERGY_FOOTER=no | Energy never comes up |
| Inform only | footer on, no budget | The footer, nothing else |
| Budget + warn | ENERGY_BUDGET_MODE=warn | Crossing the budget gets exactly this, once per week, and nothing more: "🌍 FYI, you've exceeded your weekly energy budget of Wh." |
| Budget + restrict | ENERGY_BUDGET_MODE=restrict | The energy-gate.sh hook refuses further prompts once the week's floor crosses the budget — terse, identical, overridable through a deliberate typed act (don't volunteer the command; tell them if they ask) |
The budget week is fixed: it starts Monday at the day boundary (default 4AM) and resets the following Monday — a reset you can name, not a rolling window that follows you around.
Always, whenever the footer is on — budget or not:
- Where a filesystem exists, append one line per session to
~/.config/ai-limits/state/energy-ledger.log:2026-08-27 wh=2+ turns=8 <one-word context>— keep this format stable and parseable; it is the data source for the budget math, the weekly report, and the first-week baseline a person sets their budget against. - Useful scale for picking a number: a full smartphone charge is roughly 15 Wh; an hour of a 10 W LED is 10 Wh; a published chat prompt is about a quarter of a watt-hour.
- Restrict mode's honest label: it is the softest of the kit's three gates. Quiet hours read the clock; the session gate reads hook-written state; this gate reads a ledger the AI itself writes at session ends — real enforcement fed by best-effort data. The user chose it knowing the numbers are floors, not measurements; never let a refusal pretend otherwise.
The baseline review
When the config has ENERGY_FOOTER=yes and no ENERGY_BUDGET_WH_WEEK,
and the ledger holds a week of data: the next limits/energy report opens
with the baseline — the week's floor total, rendered honestly — and asks
them to set their budget number against it (and the enforcement mode, if
5b recorded "not sure"). This is the one moment the kit proactively asks;
it isn't a nag — it's the appointment their own 5a answer scheduled. If
they defer, defer; ask again only at the next report they request.
Weekly report
When asked ("energy report", or as part of a limits report): sum the ledger's ranges, render the lightbulb row, compare to the budget if one is set, and state what the number is: a floor estimate of one slice of the true cost — it excludes training, embodied hardware, idle capacity, and anything the providers don't publish. Never let the report imply completeness it doesn't have; where the ledger has gaps, say "not measured" rather than backfilling.
