pi-plus 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bing Tong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# pi-plus
+
+Claude Code-exact context usage detection for [pi](https://github.com/earendil-works/pi).
+
+This extension measures pi's context usage with the **same arithmetic as Claude Code** —
+usage-based prefix counting plus rough tail estimation, CC's context-window resolution,
+and CC's warning thresholds — and renders CC's `TokenWarning` indicator as a footer
+status line. Optionally, it can also take over auto-compaction and fire `ctx.compact()`
+at CC's auto-compact threshold.
+
+## What it replicates (from Claude Code's source)
+
+| Behavior | CC source | Here |
+|---|---|---|
+| Context window resolution (env override → `[1m]` suffix → capability ≥100k → 200k default) | `utils/context.ts` | `src/model-config.ts` |
+| Max output tokens per model + 8k slot-reservation cap + env override | `utils/context.ts`, `services/api/claude.ts` | `src/model-config.ts` |
+| Effective window = window − min(maxOutput, 20k) | `services/compact/autoCompact.ts` | `src/model-config.ts` |
+| Auto-compact threshold = effective − 13,000 | `services/compact/autoCompact.ts` | `src/model-config.ts` |
+| Context measurement: last API usage (input+cacheWrite+cacheRead+output) + chars/4 tail estimate; images/PDFs flat 2000 | `utils/tokens.ts`, `services/tokenEstimation.ts` | `src/usage.ts` |
+| Statusline percentage excludes output tokens; raw window denominator | `utils/context.ts` | `src/percentages.ts` |
+| Warning/error/blocking thresholds (20k/20k/3k buffers) | `services/compact/autoCompact.ts` | `src/percentages.ts` |
+| Indicator text: dim `N% until auto-compact`, `Context low (N% remaining) · Run /compact to compact & continue` | `components/TokenWarning.tsx` | `src/indicator.ts` |
+
+On a real session the plugin's token count matches pi's own `ctx.getContextUsage().tokens`
+exactly for the Anthropic-style usage shape (pi's `cacheWrite` already includes the 1h
+cache subset and `reasoning` ⊂ `output`, so the field-for-field sums coincide).
+
+## Install
+
+```bash
+# quick try
+pi -e ./src/index.ts
+
+# permanent: symlink into pi's extension directory
+ln -s "$PWD/src" ~/.pi/agent/extensions/pi-plus
+# (or copy src/ there)
+```
+
+## Auto-compact takeover (optional)
+
+pi's built-in auto-compaction fires at `contextWindow − 16,384` tokens, which is
+*earlier* than CC's threshold (`effective window − 13,000`, i.e. `window − 21,000`
+with the 8k output cap). For the CC threshold to actually govern, disable pi's
+built-in trigger in `~/.pi/agent/settings.json`:
+
+```json
+{ "compaction": { "enabled": false } }
+```
+
+The plugin checks the overflow against CC's threshold on **every tool task
+finish** (`tool_execution_end`) and calls `ctx.compact()` the moment the
+threshold is crossed — pi performs the compaction between agent steps and
+continues the turn with the compacted context (the same window pi's own
+auto-compact and CC's autocompact use). The trigger is edge-triggered: it
+fires once per crossing and re-arms after post-compact usage drops below the
+threshold. Manual `/compact` keeps working.
+
+Set `PI_CC_CONTEXT_NO_AUTO_COMPACT=1` to disable the plugin's trigger (indicator only).
+
+## Environment variables
+
+All CC variables are honored with CC's semantics:
+
+| Variable | Effect |
+|---|---|
+| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | Hard context-window override (highest precedence) |
+| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Clamp windows >200k to 200k; ignore `[1m]` |
+| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Cap the window before threshold math |
+| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Override max output tokens (bounded by model's limit) |
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Auto-compact threshold as % of effective window (testing) |
+| `CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE` | Override the blocking limit |
+| `DISABLE_COMPACT` / `DISABLE_AUTO_COMPACT` | CC-style auto-compact off (switches indicator to "Context low … Run /compact") |
+
+Plugin-specific:
+
+| Variable | Effect |
+|---|---|
+| `PI_CC_CONTEXT_DISABLE_OTK_CAP` | Disable the 8k slot-reservation cap on max output tokens |
+| `PI_CC_CONTEXT_NO_AUTO_COMPACT` | Never call `ctx.compact()` from the plugin |
+
+## Known limits
+
+- pi's built-in footer keeps showing its own `percent%` (different math: includes
+  output tokens). This plugin adds its own status line; it does not replace the footer.
+- pi core owns the compaction cut point (keeps last ~20k tokens) — only the trigger
+  threshold is CC-exact.
+- Exactness is guaranteed for Anthropic-style usage fields; other providers may map
+  usage differently.
+- CC's `percentLeft` is not clamped to 100; neither is this port.
+
+## Development
+
+```bash
+npm install
+npm test        # vitest — pure-function ports against CC fixtures
+npm run typecheck
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "pi-plus",
+	"version": "0.1.1",
+	"description": "Claude Code-exact context usage detection for pi (extension)",
+	"type": "module",
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "0.85.1",
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"typescript": "^5.6.0",
+		"vitest": "^2.1.9"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/sherocktong/pi-plus.git"
+	},
+	"homepage": "https://github.com/sherocktong/pi-plus#readme",
+	"bugs": {
+		"url": "https://github.com/sherocktong/pi-plus/issues"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"claude-code",
+		"context-usage",
+		"context-window"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	}
+}

package/src/auto-compact.ts

@@ -0,0 +1,43 @@
+/**
+ * Edge-triggered auto-compact firing.
+ *
+ * pi's built-in auto-compaction uses its own threshold (contextWindow −
+ * reserveTokens, default reserve 16384). To make Claude Code's threshold
+ * (effective window − 13000) govern, disable pi's built-in trigger in
+ * settings.json (`"compaction": { "enabled": false }`) and let this plugin
+ * call ctx.compact() at the CC threshold instead.
+ *
+ * Trigger policy: the overflow check runs on every tool task finish
+ * (tool_execution_end). When the CC threshold is crossed, ctx.compact() fires
+ * immediately — pi inserts the compaction between agent steps and continues
+ * the turn with the compacted context (the same window pi's own auto-compact
+ * and CC's autocompact use), so no work is deferred until idle.
+ *
+ * Edge-triggered: fires once per threshold crossing, re-arms after the
+ * post-compaction count drops below the threshold.
+ */
+
+export interface AutoCompactTriggerState {
+	/** True while usage is below the threshold (re-armed after compaction). */
+	below: boolean;
+}
+
+export function initialTriggerState(): AutoCompactTriggerState {
+	return { below: true };
+}
+
+/**
+ * Edge trigger: fires exactly once per threshold crossing. After firing, stays
+ * disarmed until the token count drops below the threshold again (the
+ * post-compaction count is small, so this re-arms naturally).
+ */
+export function shouldFireAutoCompact(
+	state: AutoCompactTriggerState,
+	tokenCount: number,
+	threshold: number,
+): boolean {
+	const below = tokenCount < threshold;
+	const fire = !below && state.below;
+	state.below = below;
+	return fire;
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * pi-plus: Claude Code-exact context usage detection.
+ *
+ * A pi extension that measures context usage with the same arithmetic as
+ * Claude Code (usage-based prefix count + rough tail estimation, CC's context
+ * window resolution and warning thresholds) and renders CC's TokenWarning
+ * indicator as a footer status line. When pi's built-in auto-compaction is
+ * disabled, the plugin takes over and calls ctx.compact() at CC's
+ * auto-compact threshold (effective window − 13,000 tokens).
+ *
+ * Install: copy/symlink this repo's src into ~/.pi/agent/extensions/pi-plus/
+ * or run `pi -e ./src/index.ts`.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { initialTriggerState, shouldFireAutoCompact, type AutoCompactTriggerState } from "./auto-compact.ts";
+import { getAutoCompactThreshold } from "./model-config.ts";
+import { isAutoCompactEnabled, calculateTokenWarningState } from "./percentages.ts";
+import { renderTokenWarning } from "./indicator.ts";
+import { tokenCountWithEstimation, type RoughMessage } from "./usage.ts";
+
+const STATUS_KEY = "cc-context";
+
+function branchMessages(ctx: ExtensionContext): RoughMessage[] {
+	return ctx.sessionManager
+		.getBranch()
+		.filter((entry) => entry.type === "message")
+		.map((entry) => entry.message as unknown as RoughMessage);
+}
+
+export default function (pi: ExtensionAPI) {
+	// Edge-trigger state for the CC-threshold auto-compact. Reset per session;
+	// re-arms automatically once post-compact usage drops below the threshold.
+	let compactTrigger: AutoCompactTriggerState = initialTriggerState();
+
+	function updateIndicator(ctx: ExtensionContext): void {
+		if (!ctx.hasUI) return;
+		const model = ctx.model;
+		if (!model) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		const tokenCount = tokenCountWithEstimation(branchMessages(ctx));
+		const state = calculateTokenWarningState(tokenCount, model.id, model.contextWindow, model.maxTokens);
+		ctx.ui.setStatus(STATUS_KEY, renderTokenWarning(state, isAutoCompactEnabled(), ctx.ui.theme));
+	}
+
+	/**
+	 * Check the token overflow against CC's auto-compact threshold and fire
+	 * ctx.compact() on a fresh crossing. Called on every tool task finish
+	 * (tool_execution_end) — pi performs the compaction between agent steps
+	 * and continues the turn with the compacted context.
+	 *
+	 * Set PI_CC_CONTEXT_NO_AUTO_COMPACT=1 to disable, and disable pi's
+	 * built-in auto-compaction (settings.json "compaction": {"enabled": false})
+	 * so this threshold governs instead of pi's window − 16,384.
+	 */
+	function maybeAutoCompact(ctx: ExtensionContext): void {
+		const model = ctx.model;
+		if (!model) return;
+		if (!isAutoCompactEnabled()) return;
+		if (process.env.PI_CC_CONTEXT_NO_AUTO_COMPACT !== undefined) return;
+		const tokenCount = tokenCountWithEstimation(branchMessages(ctx));
+		const threshold = getAutoCompactThreshold(model.id, model.contextWindow, model.maxTokens);
+		if (!shouldFireAutoCompact(compactTrigger, tokenCount, threshold)) return;
+		try {
+			ctx.compact();
+		} catch (error) {
+			ctx.ui.notify?.(`pi-plus: auto-compact failed to start: ${String(error)}`, "warning");
+		}
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		compactTrigger = initialTriggerState();
+		updateIndicator(ctx);
+		maybeAutoCompact(ctx);
+	});
+	pi.on("turn_end", (_event, ctx) => updateIndicator(ctx));
+	pi.on("agent_settled", (_event, ctx) => updateIndicator(ctx));
+	// Check token overflow on every tool task finish.
+	pi.on("tool_execution_end", (_event, ctx) => {
+		updateIndicator(ctx);
+		maybeAutoCompact(ctx);
+	});
+	pi.on("message_end", (_event, ctx) => updateIndicator(ctx));
+	pi.on("model_select", (_event, ctx) => updateIndicator(ctx));
+	pi.on("session_compact", (_event, ctx) => updateIndicator(ctx));
+}

package/src/indicator.ts

@@ -0,0 +1,30 @@
+/**
+ * Port of Claude Code's TokenWarning indicator (src/components/TokenWarning.tsx).
+ *
+ * Rendering rules (auto-compact reactive/collapse modes omitted — ant-only):
+ *  - below the warning threshold: render nothing
+ *  - auto-compact on:  dim "N% until auto-compact"
+ *  - auto-compact off: "Context low (N% remaining) · Run /compact to compact & continue",
+ *    warning color, or error color once past the error threshold / blocking limit
+ */
+
+import type { TokenWarningState } from "./percentages.ts";
+
+/** Structural subset of pi's Theme — avoids a hard pi-tui dependency. */
+export interface ThemeLike {
+	fg(color: string, text: string): string;
+}
+
+export function renderTokenWarning(
+	state: TokenWarningState,
+	autoCompactEnabled: boolean,
+	theme: ThemeLike,
+): string | undefined {
+	if (!state.isAboveWarningThreshold) return undefined;
+
+	if (autoCompactEnabled) {
+		return theme.fg("dim", `${state.percentLeft}% until auto-compact`);
+	}
+	const color = state.isAboveErrorThreshold || state.isAtBlockingLimit ? "error" : "warning";
+	return theme.fg(color, `Context low (${state.percentLeft}% remaining) · Run /compact to compact & continue`);
+}

package/src/model-config.ts

@@ -0,0 +1,176 @@
+/**
+ * Ports of Claude Code's context-window and max-output-token resolution.
+ *
+ * Sources (claude-code repo):
+ *  - src/utils/context.ts          — getContextWindowForModel, getModelMaxOutputTokens
+ *  - src/services/api/claude.ts    — getMaxOutputTokensForModel (slot-reservation cap)
+ *  - src/services/compact/autoCompact.ts — getEffectiveContextWindowSize, getAutoCompactThreshold
+ */
+
+export const MODEL_CONTEXT_WINDOW_DEFAULT = 200_000;
+export const COMPACT_MAX_OUTPUT_TOKENS = 20_000;
+export const CAPPED_DEFAULT_MAX_TOKENS = 8_000;
+export const AUTOCOMPACT_BUFFER_TOKENS = 13_000;
+
+const MAX_OUTPUT_TOKENS_DEFAULT = 32_000;
+const MAX_OUTPUT_TOKENS_UPPER_LIMIT = 64_000;
+
+const ONE_MILLION = 1_000_000;
+
+function isEnvTruthy(value: string | undefined): boolean {
+	return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+
+function parsePositiveInt(raw: string | undefined): number | undefined {
+	if (raw === undefined || raw === "") return undefined;
+	const parsed = parseInt(raw, 10);
+	return !Number.isNaN(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+export function is1mContextDisabled(): boolean {
+	return isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_1M_CONTEXT);
+}
+
+/** CC: has1mContext — explicit `[1m]` model suffix opt-in. */
+export function has1mContext(modelId: string): boolean {
+	return !is1mContextDisabled() && /\[1m\]/i.test(modelId);
+}
+
+/**
+ * CC: getContextWindowForModel.
+ * Resolution order: CLAUDE_CODE_MAX_CONTEXT_TOKENS env override → `[1m]` suffix →
+ * model capability (pi's registry `contextWindow` plays the role of CC's
+ * `max_input_tokens` capability, with the same >= 100k gate) → 200k default.
+ */
+export function resolveContextWindow(modelId: string, modelContextWindow?: number): number {
+	const override = parsePositiveInt(process.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS);
+	if (override) return override;
+
+	if (has1mContext(modelId)) return ONE_MILLION;
+
+	if (modelContextWindow && modelContextWindow >= 100_000) {
+		if (modelContextWindow > MODEL_CONTEXT_WINDOW_DEFAULT && is1mContextDisabled()) {
+			return MODEL_CONTEXT_WINDOW_DEFAULT;
+		}
+		return modelContextWindow;
+	}
+	return MODEL_CONTEXT_WINDOW_DEFAULT;
+}
+
+/**
+ * CC: getModelMaxOutputTokens — hardcoded per-model table, overridden by the
+ * model capability's max_tokens (pi's registry `maxTokens`) when >= 4096.
+ */
+export function getModelMaxOutputTokens(
+	modelId: string,
+	modelMaxTokens?: number,
+): { default: number; upperLimit: number } {
+	const m = modelId.toLowerCase();
+	let defaultTokens: number;
+	let upperLimit: number;
+
+	if (m.includes("opus-4-6")) {
+		defaultTokens = 64_000;
+		upperLimit = 128_000;
+	} else if (m.includes("sonnet-4-6")) {
+		defaultTokens = 32_000;
+		upperLimit = 128_000;
+	} else if (m.includes("opus-4-5") || m.includes("sonnet-4") || m.includes("haiku-4")) {
+		defaultTokens = 32_000;
+		upperLimit = 64_000;
+	} else if (m.includes("opus-4-1") || m.includes("opus-4")) {
+		defaultTokens = 32_000;
+		upperLimit = 32_000;
+	} else if (m.includes("claude-3-opus")) {
+		defaultTokens = 4_096;
+		upperLimit = 4_096;
+	} else if (m.includes("claude-3-sonnet")) {
+		defaultTokens = 8_192;
+		upperLimit = 8_192;
+	} else if (m.includes("claude-3-haiku")) {
+		defaultTokens = 4_096;
+		upperLimit = 4_096;
+	} else if (m.includes("3-5-sonnet") || m.includes("3-5-haiku")) {
+		defaultTokens = 8_192;
+		upperLimit = 8_192;
+	} else if (m.includes("3-7-sonnet")) {
+		defaultTokens = 32_000;
+		upperLimit = 64_000;
+	} else {
+		defaultTokens = MAX_OUTPUT_TOKENS_DEFAULT;
+		upperLimit = MAX_OUTPUT_TOKENS_UPPER_LIMIT;
+	}
+
+	if (modelMaxTokens && modelMaxTokens >= 4_096) {
+		upperLimit = modelMaxTokens;
+		defaultTokens = Math.min(defaultTokens, upperLimit);
+	}
+
+	return { default: defaultTokens, upperLimit };
+}
+
+/**
+ * CC: getMaxOutputTokensForModel — applies the slot-reservation cap
+ * (tengu_otk_slot_v1, live in current production builds: default output
+ * dropped to 8k, over-limit requests get one clean retry at 64k), then the
+ * CLAUDE_CODE_MAX_OUTPUT_TOKENS bounded env override.
+ */
+export function getMaxOutputTokensForModel(modelId: string, modelMaxTokens?: number): number {
+	const { default: modelDefault, upperLimit } = getModelMaxOutputTokens(modelId, modelMaxTokens);
+	const capDisabled = isEnvTruthy(process.env.PI_CC_CONTEXT_DISABLE_OTK_CAP);
+	// Math.min keeps models with lower native defaults (e.g. claude-3-opus at
+	// 4k) at their native value.
+	const defaultTokens = capDisabled ? modelDefault : Math.min(modelDefault, CAPPED_DEFAULT_MAX_TOKENS);
+
+	const raw = process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS;
+	if (raw !== undefined) {
+		const parsed = parseInt(raw, 10);
+		if (!Number.isNaN(parsed) && parsed > 0) return Math.min(parsed, upperLimit);
+	}
+	return defaultTokens;
+}
+
+/**
+ * CC: getEffectiveContextWindowSize — context window minus the reserved
+ * output tokens (min(maxOutput, 20k)), optionally capped by
+ * CLAUDE_CODE_AUTO_COMPACT_WINDOW.
+ */
+export function getEffectiveContextWindowSize(
+	modelId: string,
+	modelContextWindow?: number,
+	modelMaxTokens?: number,
+): number {
+	const reservedTokensForSummary = Math.min(
+		getMaxOutputTokensForModel(modelId, modelMaxTokens),
+		COMPACT_MAX_OUTPUT_TOKENS,
+	);
+	let contextWindow = resolveContextWindow(modelId, modelContextWindow);
+	const autoCompactWindow = parsePositiveInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW);
+	if (autoCompactWindow) {
+		contextWindow = Math.min(contextWindow, autoCompactWindow);
+	}
+	return contextWindow - reservedTokensForSummary;
+}
+
+/**
+ * CC: getAutoCompactThreshold — effective window minus the 13k autocompact
+ * buffer. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (1–100) lowers it for testing.
+ */
+export function getAutoCompactThreshold(
+	modelId: string,
+	modelContextWindow?: number,
+	modelMaxTokens?: number,
+): number {
+	const effective = getEffectiveContextWindowSize(modelId, modelContextWindow, modelMaxTokens);
+	const autocompactThreshold = effective - AUTOCOMPACT_BUFFER_TOKENS;
+
+	const envPercent = process.env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE;
+	if (envPercent !== undefined) {
+		const parsed = parseFloat(envPercent);
+		if (!Number.isNaN(parsed) && parsed > 0 && parsed <= 100) {
+			const percentageThreshold = Math.floor(effective * (parsed / 100));
+			return Math.min(percentageThreshold, autocompactThreshold);
+		}
+	}
+	return autocompactThreshold;
+}

package/src/percentages.ts

@@ -0,0 +1,92 @@
+/**
+ * Ports of Claude Code's statusline percentage and token-warning thresholds.
+ *
+ * Sources (claude-code repo):
+ *  - src/utils/context.ts                   — calculateContextPercentages
+ *  - src/services/compact/autoCompact.ts    — calculateTokenWarningState, isAutoCompactEnabled
+ */
+
+import {
+	getAutoCompactThreshold,
+	getEffectiveContextWindowSize,
+} from "./model-config.ts";
+import type { UsageSnapshot } from "./usage.ts";
+
+export const WARNING_THRESHOLD_BUFFER_TOKENS = 20_000;
+export const ERROR_THRESHOLD_BUFFER_TOKENS = 20_000;
+export const MANUAL_COMPACT_BUFFER_TOKENS = 3_000;
+
+/**
+ * CC: isAutoCompactEnabled — DISABLE_COMPACT / DISABLE_AUTO_COMPACT env vars.
+ * (CC also consults a user-config flag; pi has no extension-readable
+ * equivalent, so this port is env-only and defaults to enabled.)
+ */
+export function isAutoCompactEnabled(): boolean {
+	const raw = (name: string) => process.env[name];
+	const truthy = (v: string | undefined) => v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false";
+	if (truthy(raw("DISABLE_COMPACT"))) return false;
+	if (truthy(raw("DISABLE_AUTO_COMPACT"))) return false;
+	return true;
+}
+
+/**
+ * CC: calculateContextPercentages — the statusline percentage. Numerator is
+ * input + cache creation + cache read (output EXCLUDED), denominator is the
+ * raw context window (not the effective one). pi's `cacheWrite` includes the
+ * 1h cache subset, matching CC's cache_creation_input_tokens.
+ */
+export function calculateContextPercentages(
+	currentUsage: Pick<UsageSnapshot, "input" | "cacheRead" | "cacheWrite"> | null,
+	contextWindowSize: number,
+): { used: number | null; remaining: number | null } {
+	if (!currentUsage) return { used: null, remaining: null };
+	const totalInputTokens = currentUsage.input + currentUsage.cacheWrite + currentUsage.cacheRead;
+	const usedPercentage = Math.round((totalInputTokens / contextWindowSize) * 100);
+	const clampedUsed = Math.min(100, Math.max(0, usedPercentage));
+	return { used: clampedUsed, remaining: 100 - clampedUsed };
+}
+
+export interface TokenWarningState {
+	percentLeft: number;
+	isAboveWarningThreshold: boolean;
+	isAboveErrorThreshold: boolean;
+	isAboveAutoCompactThreshold: boolean;
+	isAtBlockingLimit: boolean;
+}
+
+/**
+ * CC: calculateTokenWarningState — percent left until the (auto-compact or
+ * effective) threshold and the warning/error/blocking threshold crossings.
+ * Warning and error buffers are both 20k in CC, so the two crossings are
+ * identical unless env overrides differ.
+ */
+export function calculateTokenWarningState(
+	tokenUsage: number,
+	modelId: string,
+	modelContextWindow?: number,
+	modelMaxTokens?: number,
+): TokenWarningState {
+	const autoCompact = isAutoCompactEnabled();
+	const autoCompactThreshold = getAutoCompactThreshold(modelId, modelContextWindow, modelMaxTokens);
+	const effectiveContextWindow = getEffectiveContextWindowSize(modelId, modelContextWindow, modelMaxTokens);
+	const threshold = autoCompact ? autoCompactThreshold : effectiveContextWindow;
+
+	const percentLeft = Math.max(0, Math.round(((threshold - tokenUsage) / threshold) * 100));
+
+	const warningThreshold = threshold - WARNING_THRESHOLD_BUFFER_TOKENS;
+	const errorThreshold = threshold - ERROR_THRESHOLD_BUFFER_TOKENS;
+
+	const defaultBlockingLimit = effectiveContextWindow - MANUAL_COMPACT_BUFFER_TOKENS;
+	const parsedOverride = process.env.CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE
+		? parseInt(process.env.CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE, 10)
+		: NaN;
+	const blockingLimit = !Number.isNaN(parsedOverride) && parsedOverride > 0 ? parsedOverride : defaultBlockingLimit;
+
+	return {
+		percentLeft,
+		isAboveWarningThreshold: tokenUsage >= warningThreshold,
+		isAboveErrorThreshold: tokenUsage >= errorThreshold,
+		isAboveAutoCompactThreshold: autoCompact && tokenUsage >= autoCompactThreshold,
+		isAtBlockingLimit: tokenUsage >= blockingLimit,
+	};
+}

package/src/usage.ts

@@ -0,0 +1,201 @@
+/**
+ * Ports of Claude Code's usage-based context measurement and rough tail
+ * estimation.
+ *
+ * Sources (claude-code repo):
+ *  - src/utils/tokens.ts                — tokenCountWithEstimation, getTokenCountFromUsage
+ *  - src/services/tokenEstimation.ts    — roughTokenCountEstimationForBlock
+ *  - src/services/compact/microCompact.ts — IMAGE_MAX_TOKEN_SIZE = 2000
+ *
+ * pi's message model differs from CC's: tool results are separate
+ * `toolResult` messages (CC: `user` messages containing tool_result blocks)
+ * and assistant tool calls use the `toolCall` block type (CC: `tool_use`).
+ * The estimation below maps those 1:1 so the arithmetic matches CC.
+ */
+
+/** Structural shape of pi's Usage we rely on (pi-ai Usage). */
+export interface UsageSnapshot {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+/** Structural minimal message shape — accepts pi AgentMessage without a
+ * hard runtime dependency on pi-ai. */
+export interface RoughMessage {
+	role?: string;
+	content?: unknown;
+	usage?: Partial<UsageSnapshot> | null;
+	stopReason?: string;
+	timestamp?: number;
+	toolsAdded?: unknown[];
+	toolsRemoved?: unknown[];
+}
+
+/** CC: images and PDFs are billed ~2000 tokens after client-side resizing;
+ * a 1MB base64 PDF must NOT fall through to the stringify catch-all. */
+const IMAGE_DOCUMENT_TOKEN_ESTIMATE = 2000;
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * CC: getTokenCountFromUsage — the full context size at the time of that API
+ * call: input + cache creation (5m and 1h) + cache read + output.
+ * pi's `cacheWrite` already includes the 1h subset, and `reasoning` is a
+ * subset of `output`, so summing the four fields is exactly CC's formula.
+ */
+export function getTokenCountFromUsage(usage: UsageSnapshot): number {
+	return usage.input + usage.cacheWrite + usage.cacheRead + usage.output;
+}
+
+function hasPositiveTokenCount(usage: Partial<UsageSnapshot> | null | undefined): usage is UsageSnapshot {
+	if (!usage) return false;
+	const total = getTokenCountFromUsage({
+		input: usage.input ?? 0,
+		output: usage.output ?? 0,
+		cacheRead: usage.cacheRead ?? 0,
+		cacheWrite: usage.cacheWrite ?? 0,
+	});
+	return total > 0;
+}
+
+function safeJsonStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? "undefined";
+	} catch {
+		return "[unserializable]";
+	}
+}
+
+/** CC: roughTokenCountEstimation — characters / 4, rounded. */
+export function roughTokenCountEstimation(content: string, bytesPerToken: number = CHARS_PER_TOKEN): number {
+	return Math.round(content.length / bytesPerToken);
+}
+
+/**
+ * Find the last assistant message whose usage validly describes the current
+ * context prefix. Port of pi's getLastAssistantUsageInfo (estimate.ts), which
+ * matches CC's getTokenUsage behavior: skip aborted/error responses, skip
+ * responses older than a newer prefix message (e.g. a compaction summary
+ * inserted afterwards), skip zero-usage records.
+ */
+export function findLastUsageInfo(
+	messages: readonly RoughMessage[],
+): { usage: UsageSnapshot; index: number } | undefined {
+	let latestPrefixTimestamp = Number.NEGATIVE_INFINITY;
+	let usageInfo: { usage: UsageSnapshot; index: number } | undefined;
+
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i];
+		if (message.role === "assistant" && hasPositiveTokenCount(message.usage)) {
+			const usageAppliesToPrefix = (message.timestamp ?? 0) >= latestPrefixTimestamp;
+			if (usageAppliesToPrefix && message.stopReason !== "aborted" && message.stopReason !== "error") {
+				usageInfo = {
+					usage: {
+						input: message.usage.input ?? 0,
+						output: message.usage.output ?? 0,
+						cacheRead: message.usage.cacheRead ?? 0,
+						cacheWrite: message.usage.cacheWrite ?? 0,
+					},
+					index: i,
+				};
+			}
+		}
+		if (message.timestamp !== undefined) {
+			latestPrefixTimestamp = Math.max(latestPrefixTimestamp, message.timestamp);
+		}
+	}
+	return usageInfo;
+}
+
+/** CC: roughTokenCountEstimationForBlock — per content block. */
+function estimateBlockTokens(block: unknown): number {
+	if (typeof block === "string") return roughTokenCountEstimation(block);
+	if (!block || typeof block !== "object") return 0;
+	const b = block as Record<string, unknown>;
+	switch (b.type) {
+		case "text":
+			return roughTokenCountEstimation(String(b.text ?? ""));
+		case "thinking":
+			return roughTokenCountEstimation(String(b.thinking ?? ""));
+		case "image":
+		case "document":
+			return IMAGE_DOCUMENT_TOKEN_ESTIMATE;
+		// pi toolResult message content (CC: tool_result block inside a user message)
+		case "toolResult":
+			return estimateContentTokens(b.content);
+		// pi assistant tool call (CC: tool_use block — name + serialized input)
+		case "toolCall":
+			return roughTokenCountEstimation(String(b.name ?? "") + safeJsonStringify(b.arguments ?? {}));
+		default:
+			// server_tool_use, web_search_tool_result, mcp_tool_use, etc. — text-like
+			// payloads where the stringify length tracks the serialized form.
+			return roughTokenCountEstimation(safeJsonStringify(block));
+	}
+}
+
+function estimateContentTokens(content: unknown): number {
+	if (!content) return 0;
+	if (typeof content === "string") return roughTokenCountEstimation(content);
+	if (!Array.isArray(content)) return roughTokenCountEstimation(safeJsonStringify(content));
+	let total = 0;
+	for (const block of content) total += estimateBlockTokens(block);
+	return total;
+}
+
+/**
+ * CC: roughTokenCountEstimationForMessage — CC counts only assistant and user
+ * message content (tool results ride inside user messages there). pi carries
+ * tool results as their own `toolResult` messages, estimated via their content
+ * blocks. pi also keeps `system` messages in the branch (CC has none in the
+ * tail), so those are counted as chars/4 plus their tool definitions.
+ */
+export function estimateMessageTokens(message: RoughMessage): number {
+	if (message.role === "system") {
+		let chars = 0;
+		const content = message.content;
+		if (typeof content === "string") {
+			chars += content.length;
+		} else if (Array.isArray(content)) {
+			for (const block of content) {
+				if (block && typeof block === "object" && "text" in block) {
+					chars += String((block as { text: unknown }).text ?? "").length;
+				}
+			}
+		}
+		const toolsAdded = message.toolsAdded?.length ? safeJsonStringify(message.toolsAdded).length : 0;
+		const toolsRemoved = message.toolsRemoved?.length ? safeJsonStringify(message.toolsRemoved).length : 0;
+		chars += toolsAdded + toolsRemoved;
+		return Math.round(chars / CHARS_PER_TOKEN);
+	}
+	if (
+		(message.role === "assistant" || message.role === "user" || message.role === "toolResult") &&
+		message.content != null
+	) {
+		return estimateContentTokens(message.content);
+	}
+	return 0;
+}
+
+/**
+ * CC: tokenCountWithEstimation — THE canonical context measurement for
+ * threshold checks. Last valid API usage (exact tokens for everything up to
+ * that response) plus a rough estimate of everything appended since.
+ *
+ * Note: CC walks back past sibling assistant records split from the same API
+ * response (shared message.id, interleaved tool_results). pi does not split
+ * assistant records per content block, so no walk-back is needed.
+ */
+export function tokenCountWithEstimation(messages: readonly RoughMessage[]): number {
+	const usageInfo = findLastUsageInfo(messages);
+	if (usageInfo) {
+		let trailingTokens = 0;
+		for (let i = usageInfo.index + 1; i < messages.length; i++) {
+			trailingTokens += estimateMessageTokens(messages[i]);
+		}
+		return getTokenCountFromUsage(usageInfo.usage) + trailingTokens;
+	}
+	let tokens = 0;
+	for (const message of messages) tokens += estimateMessageTokens(message);
+	return tokens;
+}