name

claude-context

description

Report the current session's resource facts — context-window occupancy, 5-hour and 7-day subscription usage, session cost, and compaction count — as pure measurements with provenance (human summary + machine-readable JSON block). Use when you or the user want to know how much context, quota, or cost the session has used — and, for agents and subagents, to gate your own behavior on those numbers: checkpoint or stop as context fills up (before Claude Code's auto-compaction silently drops CLAUDE.md guidance or recent instructions), or pause before exhausting the 5h/7d limit. Reports facts only; your instructions set the policy. Makes no recommendations.

claude-context

This skill surfaces the current session's resource facts on demand, for both the user and agents (including subagents). It is an instrument, not an advisor: it reports measurements and where they came from, and nothing else. It makes no recommendations, attaches no evaluative or level labels, and prescribes no actions. What to do with the numbers is entirely the caller's decision.

When relaying this report, pass the measurements through as-is. Do not add recommendations, urgency, thresholds, or "you should…" framing of your own — even though the numbers may invite it. Report what the instrument measured and the provenance fields (source, rate_limits_status, setup_required, session_selection); let the caller decide what it means.

How to run it

Run the report engine with Bash and read its output. Resolve the runtime the same way setup/teardown do — prefer bun, fall back to node (the report is pure node: ESM and runs under either) — rather than assuming node is on PATH, since setup wires bun-only hosts:

RT=$(command -v bun 2>/dev/null || command -v node 2>/dev/null)
"$RT" "${CLAUDE_PLUGIN_ROOT}/scripts/report.mjs" --session-id "${CLAUDE_SESSION_ID}"

Pass --session-id so the report reads this session's own snapshot rather than a concurrent same-account session's. ${CLAUDE_SESSION_ID} is substituted by Claude Code; if your build doesn't expose it, the report falls back to the CLAUDE_CODE_SESSION_ID environment variable, then to the newest snapshot (see session_selection below). It prints a human-readable block and a fenced json block, and always succeeds even with no collector running.

Field reference

context.used_percentage — percent of the context window in use (0–100).
context.used_tokens / window_size / headroom_tokens — tokens in use, the window size, and tokens remaining. used_tokens = input + cache-read + cache-creation.
context.input_tokens / cache_read_tokens / cache_creation_tokens / output_tokens — the token breakdown for the last measured turn.
rate_limits.five_hour / seven_day — subscription usage windows, each with used_percentage, resets_at (ISO), and resets_in_seconds. Present only for Pro/Max accounts after the first API response; otherwise null.
cost_usd — session cost in USD, or null when unavailable.
compactions — number of compaction boundaries in the transcript.
source — collector (a fresh snapshot, or — while idle — the stale snapshot's own context field), transcript (collector idle: context recomputed from the transcript against the stale snapshot's real window size), or unavailable (no snapshot has ever been written; compactions is also null in this state, since it is unknown rather than zero).
rate_limits_status — available; unavailable_plan (collector on, account reports no subscription usage — either an API-key account or before the first Pro/Max response); unavailable_provider (Bedrock/Vertex, which don't report subscription usage); unavailable_stale (a snapshot exists but is past the freshness window — collector on but idle); or unavailable_collector (no snapshot has ever been written).
setup_required — true only when no collector snapshot has ever been written (the not-set-up state): 5h/7d, cost, context, and compactions are all null and the human block explains how to run /claude-context:setup. false in every other state. Gate on this one field instead of inferring setup status from source/rate_limits_status.
session_selection — how the report decided whose numbers these are: session_id (matched this session's own id — the snapshot and its transcript are definitively yours) or unverified-snapshot (this Claude Code build exposed no session id, so the newest snapshot was used and may belong to another concurrent same-account session). Omitted from the JSON in the not-set-up state, where there are no numbers to attribute. Gate on this when it matters that the context figures are your session's and not a neighbor's.
snapshot_age_seconds — how old the snapshot is (collector mode, or the age of a stale snapshot reused in fallback).
model — the reporting session's model as { id, display_name }. From the collector, id carries the [1m] marker on a 1M-context session; from the transcript fallback it is the base id (no marker) and display_name is empty.
generated_at — ISO-8601 time the report itself was produced. Distinct from snapshot_age_seconds (the snapshot's age): use generated_at to tell how fresh the report is, e.g. to ignore a cached copy.

Whose numbers are these?

The context figures describe the session — the main agent's context window (the view Claude Code sends to the statusline). Subscription usage (5h/7d) and cost are account-wide, shared by the main agent and every subagent.

Because several Claude Code sessions can run under one account at once, the collector keys its snapshot by session id and the report reads the one matching your session (session_selection: "session_id"). If your Claude Code build exposes no session id, the report falls back to the newest snapshot and flags it unverified-snapshot — in that state the context/compaction figures may be a neighbouring session's, while the account-wide 5h/7d/cost figures are identical across sessions and stay correct.

If you are a subagent, the context percentage is the session's, not your own private window. Use it to judge whether the parent session is filling up — for example, to checkpoint results to a file before it auto-compacts — not as a gauge of your own subagent context, which this report does not measure.

Sources and reliability

The report resolves to exactly three states, keyed on whether a collector snapshot has ever been written:

Collector — a fresh snapshot exists. Full numbers: context, 5h/7d usage, cost, and compactions, all source: "collector", rate_limits_status: "available" (or one of the unavailable_plan / unavailable_provider variants when the account doesn't report subscription usage).
Collector idle — a snapshot exists but is past the freshness window. Context is still accurate: recomputed from the transcript's latest usage against the stale snapshot's real window size (source: "transcript"), or, when the transcript has no usage to read, reported straight from the stale snapshot's own context field (source: "collector"). Either way rate_limits_status: "unavailable_stale" and 5h/7d/cost are null — the collector is on, just not fresh, so it is never mistaken for "collector not installed."
Not set up — no snapshot has ever been written. The report performs no transcript I/O and returns everything null (including compactions, which is unknown rather than zero), source: "unavailable", rate_limits_status: "unavailable_collector", and setup_required: true; the human block explains how to run /claude-context:setup.

Use the source, rate_limits_status, setup_required, and session_selection fields to judge how much to trust each number.

claude-context

How to run it

RT=$(command -v bun 2>/dev/null || command -v node 2>/dev/null) "$RT" "${CLAUDE_PLUGIN_ROOT}/scripts/report.mjs" --session-id "${CLAUDE_SESSION_ID}"

Field reference

context.used_percentage — percent of the context window in use (0–100).

context.used_tokens / window_size / headroom_tokens — tokens in use, the window size, and tokens remaining. used_tokens = input + cache-read + cache-creation.

context.input_tokens / cache_read_tokens / cache_creation_tokens / output_tokens — the token breakdown for the last measured turn.

rate_limits.five_hour / seven_day — subscription usage windows, each with used_percentage, resets_at (ISO), and resets_in_seconds. Present only for Pro/Max accounts after the first API response; otherwise null.

cost_usd — session cost in USD, or null when unavailable.

compactions — number of compaction boundaries in the transcript.

source — collector (a fresh snapshot, or — while idle — the stale snapshot's own context field), transcript (collector idle: context recomputed from the transcript against the stale snapshot's real window size), or unavailable (no snapshot has ever been written; compactions is also null in this state, since it is unknown rather than zero).

rate_limits_status — available; unavailable_plan (collector on, account reports no subscription usage — either an API-key account or before the first Pro/Max response); unavailable_provider (Bedrock/Vertex, which don't report subscription usage); unavailable_stale (a snapshot exists but is past the freshness window — collector on but idle); or unavailable_collector (no snapshot has ever been written).

setup_required — true only when no collector snapshot has ever been written (the not-set-up state): 5h/7d, cost, context, and compactions are all null and the human block explains how to run /claude-context:setup. false in every other state. Gate on this one field instead of inferring setup status from source/rate_limits_status.

session_selection — how the report decided whose numbers these are: session_id (matched this session's own id — the snapshot and its transcript are definitively yours) or unverified-snapshot (this Claude Code build exposed no session id, so the newest snapshot was used and may belong to another concurrent same-account session). Omitted from the JSON in the not-set-up state, where there are no numbers to attribute. Gate on this when it matters that the context figures are your session's and not a neighbor's.

snapshot_age_seconds — how old the snapshot is (collector mode, or the age of a stale snapshot reused in fallback).

model — the reporting session's model as { id, display_name }. From the collector, id carries the [1m] marker on a 1M-context session; from the transcript fallback it is the base id (no marker) and display_name is empty.

generated_at — ISO-8601 time the report itself was produced. Distinct from snapshot_age_seconds (the snapshot's age): use generated_at to tell how fresh the report is, e.g. to ignore a cached copy.

Whose numbers are these?

Sources and reliability

The report resolves to exactly three states, keyed on whether a collector snapshot has ever been written:

Collector — a fresh snapshot exists. Full numbers: context, 5h/7d usage, cost, and compactions, all source: "collector", rate_limits_status: "available" (or one of the unavailable_plan / unavailable_provider variants when the account doesn't report subscription usage).

Collector idle — a snapshot exists but is past the freshness window. Context is still accurate: recomputed from the transcript's latest usage against the stale snapshot's real window size (source: "transcript"), or, when the transcript has no usage to read, reported straight from the stale snapshot's own context field (source: "collector"). Either way rate_limits_status: "unavailable_stale" and 5h/7d/cost are null — the collector is on, just not fresh, so it is never mistaken for "collector not installed."

Not set up — no snapshot has ever been written. The report performs no transcript I/O and returns everything null (including compactions, which is unknown rather than zero), source: "unavailable", rate_limits_status: "unavailable_collector", and setup_required: true; the human block explains how to run /claude-context:setup.

Use the source, rate_limits_status, setup_required, and session_selection fields to judge how much to trust each number.