Context and limits
How Narsil draws each conversation's context bar, estimates when it fills at the pace of the last 15 minutes, suggests /compact once, and shows the 5-hour and weekly limits.
What it does
Two kinds of limits decide how long you can keep working with Claude, and Narsil shows both.
The context window is how much of the conversation the model can hold at once. When it fills, Claude Code has to compact the conversation, summarizing what came before, and details can get lost. Each conversation has its own window, so each row in Narsil’s band has its own bar and percentage:
● TRABAJANDO ▾ web ██████░░░░ 62 %
Your own conversation’s bar is blue, so it stands out; the others are green, amber past 60 % and red past 85 %. Pressing the open conversation’s percentage shows its tokens, how soon it will fill and what fills it:
- “120k / 200k · lleno en ~20 min” (“full in about 20 minutes”).
- A bar per part, as
/contextbreaks it down: messages, the system prompt, MCP tools, memory files, the compaction reserve and the free space, each with its tokens.
When the context passes 70 % and will fill within 20 minutes, or as soon as it passes 85 %, Narsil suggests once: “El contexto va al 72 % y se llenará en ~13 min: es buen momento para /compact.” (“The context is at 72 % and will fill in about 13 minutes: a good moment for /compact.”)
The account limits are the 5-hour window and the weekly window of a subscription plan. They are the same for every conversation, so they show once, at the top, with the time until each starts over:
5 horas ███░░░░░░░ 31 % reinicia en 2 h 05 min
Semana █░░░░░░░░░ 12 % reinicia en 3 d 4 h
With an API key there are no such windows, and Narsil shows none.
How it works inside
Where the numbers come from
Narsil does not count tokens itself. It reads the figures Claude Code already has, the same ones its status line shows, from two places in the mod API:
$.session.usage(), called once insession.start. It returnscontext(the live window:windowin tokens, andtokensandpercentonce a response has reported them) andrateLimits, one entry per window, each with akind(five_hour,seven_day), apercentUsedand an optionalresetsAttimestamp.- The
session.measureevent, which, as the 2.1.325 types put it, “fires when the engine measures the session and a unit moved: after each main-thread turn, and when a rate-limit window moves a whole point”. It carries the samecontextandrateLimits.
Both go through one pure function, usageOf in hooks/usage.ts, which turns them into Narsil’s own shape: context (percent, tokens, window), fiveHour and week. A window with no reading is null. The types say rateLimits is “empty off a subscription”, which is why no limits show with an API key.
Then setUsage in hooks/register.tsx stores the result in the usage atom (only when it changed), records the context reading for the estimate, refreshes the breakdown and pushes the state to the hub, so the other conversations and the floating window see this one’s bar.
The design choice is to be pushed, not to poll. The engine raises session.measure exactly when a number moved, so Narsil never asks for figures that cannot have changed.
The estimate: the pace of the last 15 minutes
“Full in about 20 minutes” is a straight-line guess from recent readings. Each time the context is measured, trackContext adds a sample, { at, percent }, to a list of at most 30. Then minutesToFull in hooks/usage.ts does the arithmetic:
- Keep only the samples of the last 15 minutes (
BURN_WINDOW_MS). - Take the first and the last. If they span less than a minute, or the context did not grow, there is no estimate.
- The pace is the growth divided by the minutes between them.
- The answer is the room left divided by the pace, rounded.
For example: 50 % at minute 0 and 60 % at minute 5 is 2 % a minute, and the 40 % left takes 20 minutes.
Each choice has a reason:
- Fifteen minutes, not the whole conversation. Work comes in bursts. A long quiet stretch followed by heavy file reading should give a near estimate, not an average that hides the burst.
- No estimate for less than a minute or a context that is not growing. Two readings seconds apart, or a context that shrank, give a pace that means nothing.
- Forget the samples when the context shrinks. A drop means
/compactor/clearran. The old pace belongs to a conversation that no longer exists, so the list starts over. - Hide estimates past two hours.
MAX_ESTIMATE_MINUTESis 120; a guess that far ahead is too far off to be worth showing, as the comment says.
The /compact suggestion, once
trackContext also decides the suggestion, with four constants:
NUDGE_AT = 70: never below 70 %.NUDGE_WITHIN_MINUTES = 20: from 70 %, only if the estimate says it fills within 20 minutes.NUDGE_ALWAYS_AT = 85: from 85 %, always, estimate or not.NUDGE_RESET_BELOW = 50: once the context drops below 50 %, a new fill may get a new suggestion.
A flag, isCompactNudged, makes it once per fill. The suggestion is one of Narsil’s tips (showTip with the kind context), so it appears where her tips appear, and it is skipped when tips are turned off (/narsil consejos off). The reasoning is the same as for every alert in Narsil: a warning that repeats on every turn soon gets ignored.
The breakdown, estimated locally
What fills the context comes from $.session.usage({ breakdown: 'summary' }). The types describe the two modes: full “sends one token-count request per tool and memory file, as /context does; summary estimates locally and sends none”. Narsil uses summary and refreshes it whenever a measurement changes the figures, so the breakdown can be opened at once, even for another conversation, whose breakdown travels through the hub.
contextDetailOf in hooks/usage.ts keeps the parts worth showing: it drops tool schemas loaded on demand (deferred, outside the window) and empty rows, sorts what is used by size, then the compaction reserve, then the free space, and gives each a color.
Drawing the bars
The pieces in hooks/usage.ts are small and pure:
levelColor(percent): green#22B573, amber#F5B400from 60 %, red#F0435Afrom 85 %.textBar(percent): ten cells of█and░, for the band’s rows.minutesLabelandresetIn: “13 min”, “2 h 05 min”, “3 d 4 h”.usageRows: the rows to draw, each with its note: tokens and the estimate for the context, “reinicia en …” for the limits.usageSvg: the same rows as one small SVG, used on the desktop, where each bar grows from empty when drawn and the text follows the light or dark theme.
Why one bar per conversation
The context belongs to a conversation, not to you. A single “context” figure for several conversations would average things that cannot be averaged. That is why the general bar was removed and every row got its own, as the next section records. The account limits are the opposite case: they belong to the account, so they show once.
How it was asked of the AI
Recorded: one bar per conversation
The per-conversation bars were asked for in odd/tasks/fleet-view.md in narsil-pet, in the same conversation that produced the fleet view (L1 is dated 2026-11-06; the later entries carry no date). L3 (excerpt):
“la barra de contexto general tambien se iria por que no existe un contexto general y se reemplazaria por las barras de contexto de cada conversacion”
In English: the general context bar would also go, because there is no general context, and it would be replaced by each conversation’s context bar. The log’s spec S5 adds: “The account limits (5 hours, week) stay, shown once.”
The breakdown was asked for in L2 (excerpt):
“el detalle de como se llena el contexto deberia aparecer cuando se de click en la palabra contexto.”
In English: the detail of how the context fills should appear when you click the word “context”. L7 records it done in the band. One day later, 250d2c6 (2026-11-07) “feat: open the context from its percent and let next steps stand alone” moved the band’s control from the word to the percentage, which is where the README and the code put it today. In the floating window, the word “Contexto” still opens it.
Reconstruction from the commit history
The bars, the estimate and the suggestion came before that log, and their requests were not recorded. From git log -- hooks/usage.ts hooks/register.tsx:
630c0d8(2026-10-30) “feat(usage): add context, 5-hour and weekly usage bars”. The first version: one context bar and the two limits.c885292(2026-10-30) “feat: estimate when the context fills, react to tests and dangerous commands, show subagents”. The 15-minute estimate and the/compactsuggestion.2bcc97c(2026-11-05) “feat: open the context breakdown from the usage bars and calm loop, steps and permission alerts”. The breakdown.49f0fd9(2026-11-06) “feat: list every open conversation in the band”. The bar moves into each conversation’s row, as L3 asked.d654e3b(2026-11-06) “feat: list this conversation first with a blue context bar”.250d2c6(2026-11-07), above.
A prompt you can use
The following prompt was written for this guide as a suggestion. It is not the author’s prompt.
In my Claude Code mod
my-pet, show the context window’s fill and the account’s 5-hour and weekly limits in theAbovePromptband. Read them once with$.session.usage()insession.startand then on everysession.measureevent, and keep them in an atom. Write the logic as pure functions inhooks/usage.ts: one that mapscontextandrateLimits(five_hour,seven_day) to my own shape, a ten-cell text bar, a color that turns amber at 60 % and red at 85 %, andminutesToFull(samples, now), which estimates when the context fills from the readings of the last 15 minutes and returns null with less than a minute of readings or no growth. Suggest/compactonce per fill when the context passes 70 % and fills within 20 minutes, or passes 85 %. Add tests for each function and check every API against the plugin-authoring types.
The minimal code
Written for this guide and checked against the 2.1.325 types ($.session.usage, session.measure, SessionContextUsage, SessionRateLimit, $.clock.now, $.ui.toast). It is adapted from hooks/usage.ts and hooks/register.tsx in narsil-pet (GPL-3.0-or-later). The usage atom is declared in types/index.d.ts as in the first guide.
The pure part, hooks/usage.ts:
import type { SessionContextUsage, SessionRateLimit } from 'claude-code'
export type Meter = { percent: number; resetsAt?: string }
export type Usage = { context: number | null; fiveHour: Meter | null; week: Meter | null }
export type Sample = { at: number; percent: number }
export function usageOf(m: {
context: SessionContextUsage
rateLimits: readonly SessionRateLimit[]
}): Usage {
const meter = (kind: string): Meter | null => {
const r = m.rateLimits.find((x) => x.kind === kind)
return r ? { percent: r.percentUsed, resetsAt: r.resetsAt } : null
}
return {
context: m.context.percent ?? null,
fiveHour: meter('five_hour'),
week: meter('seven_day'),
}
}
export const levelColor = (p: number) => (p >= 85 ? '#F0435A' : p >= 60 ? '#F5B400' : '#22B573')
export function textBar(percent: number, cells = 10): string {
const full = Math.max(0, Math.min(cells, Math.round((percent / 100) * cells)))
return '█'.repeat(full) + '░'.repeat(cells - full)
}
const WINDOW_MS = 15 * 60_000
export function minutesToFull(samples: readonly Sample[], now: number): number | null {
const recent = samples.filter((s) => now - s.at <= WINDOW_MS)
const first = recent[0]
const last = recent.at(-1)
if (!first || !last) return null
const minutes = (last.at - first.at) / 60_000
if (minutes < 1 || last.percent <= first.percent) return null
const perMinute = (last.percent - first.percent) / minutes
return Math.max(0, Math.round((100 - last.percent) / perMinute))
}
The hooks, in hooks/register.tsx:
import { atom, read, update } from 'claude-code'
import type { EngineInterface, Register } from 'claude-code'
import { levelColor, minutesToFull, textBar, usageOf } from './usage'
import type { Sample, Usage } from './usage'
const usage = atom({ plugin: 'my-pet', key: 'usage' } as const, {
context: null,
fiveHour: null,
week: null,
})
let samples: Sample[] = []
let isNudged = false
async function track($: EngineInterface, next: Usage): Promise<void> {
await update($, usage, () => next)
const percent = next.context
if (percent === null) return
const now = await $.clock.now()
const last = samples.at(-1)
if (last && percent < last.percent) samples = []
if (percent < 50) isNudged = false
samples = [...samples, { at: now, percent }].slice(-30)
const toFull = minutesToFull(samples, now)
const isNear = toFull !== null && toFull <= 20
if (isNudged || percent < 70 || !(isNear || percent >= 85)) return
isNudged = true
$.ui.toast(`Context at ${Math.round(percent)} %: a good moment for /compact.`)
}
export const register: Register = (on) => {
on('session.start', async ($, e, next) => {
const spent = await $.session.usage().catch(() => undefined)
if (spent) await track($, usageOf(spent))
return next(e)
})
on('session.measure', async ($, e, next) => {
await track($, usageOf(e))
return next(e)
})
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
if (e.props.hasSurvey) return next(e)
const u = await read($, usage)
const { Box, Text } = $.ui.resolve(e)
return (
<Box flexDirection="column" minWidth={0}>
{u.context !== null ? (
<Text
color={levelColor(u.context)}
>{`Context ${textBar(u.context)} ${Math.round(u.context)} %`}</Text>
) : null}
{u.fiveHour ? (
<Text>{`5 hours ${textBar(u.fiveHour.percent)} ${Math.round(u.fiveHour.percent)} %`}</Text>
) : null}
{u.week ? (
<Text>{`Week ${textBar(u.week.percent)} ${Math.round(u.week.percent)} %`}</Text>
) : null}
</Box>
)
})
}
Narsil shows the suggestion as one of its tips; a minimal version can use $.ui.toast, as here.
Common mistakes and how to test it
- Polling for figures. A timer that calls
$.session.usage()every few seconds does work thatsession.measurealready does for you, at the moment a number moves. - Assuming the limits exist. Off a subscription,
rateLimitsis empty. Draw nothing then, rather than a bar at 0 %. - A context with no percentage yet. Before the first response,
percentandtokensmay be absent. Narsil treats a missingpercentas “no reading”. - Keeping the old pace after
/compact. If the samples are not cleared when the context shrinks, the estimate mixes two conversations and says nonsense. - A suggestion on every turn. Without a flag that resets only when the context drops, the same
/compactadvice comes back at 71, 72 and 73 %. - Asking for the
fullbreakdown on every measurement.fullsends token-count requests;summaryis local and free.
To test, claude plugin test . runs tests/narsil.test.tsx. “the context bar tells when it will fill, and Narsil suggests /compact once when it is near” measures 50 % and, five minutes later, 60 %, then checks the text “120k / 200k · lleno en ~20 min”; it then measures 72 % at minute 10 and 74 % at minute 11 and checks that exactly one suggestion went out, “El contexto va al 72 % y se llenará en ~13 min: es buen momento para /compact.”. “a context that is not growing shows no estimate and no nudge” covers a context that shrinks. “the band shows the 5-hour window and the week once, and the context in its conversation”, “off a plan, no limits show, and the context is read when the session starts” and “a press on the open conversation percent shows what fills the context, and another goes back to the bars” cover the rest. The functions in hooks/usage.ts take plain values, so they can also be tested directly with a list of samples and a fixed now.
Going further
contextDetailOf,contextDetailRowsandcontextDetailSvginhooks/usage.tsturn the/contextbreakdown into bars.usageSummaryandcontextDetailSummarygive one sentence for places that cannot draw bars.toggleContextDetailinhooks/register.tsxreads this conversation’s breakdown afresh when you open it, and shows a toast if it cannot.shownStatesends each conversation’scontext(its percent and note) andcontextDetailto the hub, which is how another conversation’s band and the floating window draw a bar they did not measure.
Going further: how the real mod does it
These files are part of the original mods, published under the GPL v3. Code quoted on this page comes from them and keeps that license.
Did this guide help?
Every guide is free. If this one saved you time, you can buy me a coffee.
Buy me a coffee