@howaboua/pi-codex-conversion 1.5.9 → 1.5.10-dev.41.7e2d8d2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.5.10
+
+- Added `/codex usage` and a Usage tab for OpenAI Codex subscription limits, with automatic refresh and aligned 5-hour/weekly usage columns.
+- Moved settings links into a dedicated About tab.
+
 ## 1.5.9
 
 - Fixed native Responses compaction replay when provider payloads include in-flight tail items that are not yet persisted in the session branch.

package/README.md

@@ -9,7 +9,7 @@ GPT/Codex models are strongest when the tool surface looks like the Codex CLI th
 
 The point is to give the model tools it already knows how to use well: shell-first inspection, resumable command sessions, and large one-shot patch edits instead of piecemeal read/edit/write steps.
 
-You can also opt into using the adapter on every provider/model. YMMV: Codex-tuned models are still the best fit, but the shell/patch workflow can help elsewhere too. The extension also has a small `/codex` settings UI for toggling adapter behavior, web search, image generation, fast mode, and verbosity. See [Settings](#settings).
+You can also opt into using the adapter on every provider/model. YMMV: Codex-tuned models are still the best fit, but the shell/patch workflow can help elsewhere too. The extension also has a small `/codex` settings UI for toggling adapter behavior, web search, image generation, fast mode, native Responses compaction, and verbosity. See [Settings](#settings).
 
 ## Install
 
@@ -46,14 +46,17 @@ Use `/codex` to change adapter settings.
 - `/codex fast` — toggle priority service tier for the OpenAI Codex provider
 - `/codex search` — toggle native Codex web search
 - `/codex image` — toggle native Codex image generation
+- `/codex usage` — show Codex subscription usage windows for the active OpenAI Codex model
 - `/codex low`, `/codex medium`, `/codex high` — set Responses API verbosity
 
 Settings are saved globally in `~/.pi/agent/pi-codex-conversion.json`.
 
-The settings UI also has an **Overrides** tab. These options intentionally do not have `/codex ...` command shortcuts:
+The settings UI also has **Usage**, **Overrides**, and **About** tabs. **Usage** refreshes automatically when opened and can be refreshed manually with `r`. Override options intentionally do not have `/codex ...` command shortcuts:
 
 - add only the Pi `apply_patch` tool for GPT/Codex models while keeping Pi's default toolkit, prompt, provider behavior, and compaction flow
 
+The **Compaction** tab can enable native OpenAI Responses compaction and choose the compaction model/reasoning. If native compaction fails, the extension falls back to Pi's normal compaction flow; when an older native compacted window exists, it is included in that Pi fallback summarization request so OpenAI can still use the prior opaque context server-side.
+
 When `all` is on, non-Codex providers get the shell, patch, skill, and prompt-adapter behavior, but keep their normal Pi provider path. Native web search, native image generation, and priority service tier stay limited to the OpenAI Codex provider. Verbosity is applied to Responses API providers.
 
 The footer shows the active state, for example:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howaboua/pi-codex-conversion",
-  "version": "1.5.9",
+  "version": "1.5.10-dev.41.7e2d8d2",
   "description": "Codex-oriented tool and prompt adapter for pi coding agent",
   "type": "module",
   "repository": {

package/src/adapter/compaction.ts

@@ -2,9 +2,9 @@ import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent } from "
 import { clampThinkingLevel, type ModelThinkingLevel, type Tool } from "@earendil-works/pi-ai";
 import { executeNativeCompaction } from "./compact-client.ts";
 import { extractCompactionSummaryText, hasCompactionOutputItem, sanitizeCompactedWindow, summarizeCompactionOutputForDiagnostics } from "./compaction-output.ts";
-import { resolveLatestNativeCompactionEntry } from "./details-store.ts";
+import { findLatestNativeCompactionEntry, findLatestNativeCompactionEntryIndex, resolveLatestNativeCompactionEntry } from "./details-store.ts";
 import { rewriteResponsesPayloadWithNativeReplay, serializeLiveTailToResponsesInput } from "./payload-rewrite.ts";
-import { resolveNativeCompactionEnvironment } from "./compaction-runtime.ts";
+import { isResponsesCompatiblePayload, resolveNativeCompactionEnvironment, type ResponsesCompatibleRequestPayload } from "./compaction-runtime.ts";
 import { convertResponsesTools } from "../providers/openai-responses-shared.ts";
 import {
 	serializeCompactionPreparationToRequest,
@@ -12,7 +12,7 @@ import {
 	type NativeCompactionRequestOptions,
 	type ResponsesInputItem,
 } from "./serializer.ts";
-import { createNativeCompactionDetails, createNativeCompactionShimResult, isNativeCompactionDetails, NATIVE_COMPACTION_SHIM_SUMMARY } from "./types.ts";
+import { createNativeCompactionDetails, createNativeCompactionShimResult, isNativeCompactionDetails, NATIVE_COMPACTION_SHIM_SUMMARY, type NativeCompactionEntry } from "./types.ts";
 import { isOpenAICodexContext, isResponsesContext } from "./codex-model.ts";
 import { shouldUseCodexAdapter } from "./activation.ts";
 import type { AdapterState } from "./state.ts";
@@ -23,6 +23,31 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function stashLatestNativeWindowForPiCompactionFallback(
+	ctx: ExtensionContext,
+	branchEntries: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>,
+	runtime: { provider: string; api: string; baseUrl: string },
+	state: AdapterState,
+): boolean {
+	state.pendingPiCompactionNativeWindow = undefined;
+	const nativeEntry = findLatestNativeCompactionEntry(branchEntries, {
+		provider: runtime.provider,
+		api: runtime.api,
+		baseUrl: runtime.baseUrl,
+	});
+	const compactedWindow = cloneCompactedWindow(nativeEntry?.details?.compactedWindow ?? []);
+	if (!compactedWindow || compactedWindow.length === 0) return false;
+	state.pendingPiCompactionNativeWindow = {
+		window: compactedWindow,
+		provider: runtime.provider,
+		api: runtime.api,
+		baseUrl: runtime.baseUrl,
+		sessionId: ctx.sessionManager.getSessionId(),
+		sourceCompactionEntryId: nativeEntry?.id,
+	};
+	return true;
+}
+
 function cloneCompactedWindow(window: readonly unknown[]): ResponsesInputItem[] | undefined {
 	if (!window.every(isRecord)) return undefined;
 	return window.map((item) => structuredClone(item));
@@ -94,7 +119,7 @@ function formatCompactFailureMessage(compactResult: Awaited<ReturnType<typeof ex
 	const status = compactResult.status ? ` HTTP ${compactResult.status}` : "";
 	const response = compactResult.responseText?.trim();
 	const detail = response ? `: ${response.slice(0, 500)}` : compactResult.errorMessage ? `: ${compactResult.errorMessage}` : "";
-	return `OpenAI native compaction failed (${compactResult.reason}${status})${detail}; Pi compaction was not run.`;
+	return `OpenAI native compaction failed (${compactResult.reason}${status})${detail}`;
 }
 
 function formatCompactRequestDiagnostics(request: NativeCompactionRequestBody): string {
@@ -104,6 +129,11 @@ function formatCompactRequestDiagnostics(request: NativeCompactionRequestBody):
 	return `model=${request.model}, input=${request.input.length}, tools=${tools}, reasoning=${reasoning}, service_tier=${serviceTier}`;
 }
 
+function notifyNativeCompactionFallback(ctx: ExtensionContext, state: AdapterState, branchEntries: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>, runtime: { provider: string; api: string; baseUrl: string }, message: string): void {
+	const stashed = stashLatestNativeWindowForPiCompactionFallback(ctx, branchEntries, runtime, state);
+	ctx.ui.notify(`${message}; Pi compaction will run.${stashed ? " Previous native compacted window will be included in Pi compaction fallback." : ""}`, "error");
+}
+
 export async function handleCodexSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx: ExtensionContext, state: AdapterState, pi: ExtensionAPI) {
 	if (!state.config.responsesCompaction || !shouldUseCodexAdapter(ctx, state.config)) {
 		return undefined;
@@ -203,23 +233,23 @@ async function handleCodexSessionBeforeCompactInner(event: SessionBeforeCompactE
 	const compactResult = await executeNativeCompaction({ runtime, request, signal: event.signal });
 	if (!compactResult.ok) {
 		if (compactResult.reason !== "aborted") {
-			ctx.ui.notify(formatCompactFailureMessage(compactResult), "error");
+			notifyNativeCompactionFallback(ctx, state, branchEntries, runtime, formatCompactFailureMessage(compactResult));
 		}
-		return { cancel: true };
+		return compactResult.reason === "aborted" ? { cancel: true } : undefined;
 	}
 	const compactedWindow = sanitizeCompactedWindow(compactResult.compactedWindow);
 	if (compactedWindow.length === 0) {
-		ctx.ui.notify(`OpenAI native compaction returned no installable compacted context; Pi compaction was not run. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`, "error");
-		return { cancel: true };
+		notifyNativeCompactionFallback(ctx, state, branchEntries, runtime, `OpenAI native compaction returned no installable compacted context. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`);
+		return undefined;
 	}
 	if (!hasCompactionOutputItem(compactedWindow)) {
-		ctx.ui.notify(`OpenAI native compaction did not return a compaction item; Pi compaction was not run. Response=${compactResult.compactResponseId ?? "<none>"}. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`, "error");
-		return { cancel: true };
+		notifyNativeCompactionFallback(ctx, state, branchEntries, runtime, `OpenAI native compaction did not return a compaction item. Response=${compactResult.compactResponseId ?? "<none>"}. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`);
+		return undefined;
 	}
 	const encryptedSummary = extractCompactionSummaryText(compactedWindow);
 	if (!encryptedSummary) {
-		ctx.ui.notify(`OpenAI native compaction returned compacted context without a displayable summary; Pi compaction was not run. Response=${compactResult.compactResponseId ?? "<none>"}. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`, "error");
-		return { cancel: true };
+		notifyNativeCompactionFallback(ctx, state, branchEntries, runtime, `OpenAI native compaction returned compacted context without a displayable summary. Response=${compactResult.compactResponseId ?? "<none>"}. Request: ${formatCompactRequestDiagnostics(request)}. Output: ${summarizeCompactionOutputForDiagnostics(compactResult.compactedWindow, compactedWindow)}`);
+		return undefined;
 	}
 	try {
 		const details = createNativeCompactionDetails({
@@ -234,8 +264,8 @@ async function handleCodexSessionBeforeCompactInner(event: SessionBeforeCompactE
 		});
 		return { compaction: createNativeCompactionShimResult({ summary: NATIVE_COMPACTION_SHIM_SUMMARY, firstKeptEntryId: event.preparation.firstKeptEntryId, tokensBefore: event.preparation.tokensBefore, details }) };
 	} catch {
-		ctx.ui.notify("OpenAI native compaction produced details Pi could not store; Pi compaction was not run.", "error");
-		return { cancel: true };
+		notifyNativeCompactionFallback(ctx, state, branchEntries, runtime, "OpenAI native compaction produced details Pi could not store");
+		return undefined;
 	}
 }
 
@@ -245,17 +275,49 @@ export async function rewriteCodexCompactedProviderRequest(payload: unknown, ctx
 	if (!resolution.ok) return undefined;
 	const runtime = resolution.runtime;
 	const branchEntries = ctx.sessionManager.getBranch();
-	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
+	const latestNativeCompactionIndex = findLatestNativeCompactionEntryIndex(branchEntries, {
 		provider: runtime.provider,
 		api: runtime.api,
 		baseUrl: runtime.baseUrl,
 	});
-	if (!latestNativeCompaction.ok) return undefined;
+	if (latestNativeCompactionIndex === undefined) return undefined;
 	if (!runtime.payload) return undefined;
-	const rewrite = rewriteResponsesPayloadWithNativeReplay({ model: runtime.currentModel, payload: runtime.payload, branchEntries, compactionEntry: latestNativeCompaction.entry });
+	const rewrite = rewriteResponsesPayloadWithNativeReplay({ model: runtime.currentModel, payload: runtime.payload, branchEntries, compactionEntry: branchEntries[latestNativeCompactionIndex] as NativeCompactionEntry });
 	if (rewrite.ok) return rewrite.rewrittenPayload;
 	const detail = rewrite.parity?.mismatches.slice(0, 3).join("; ");
 	const message = `OpenAI native compaction replay failed (${rewrite.reason})${detail ? `: ${detail}` : ""}; request was not sent with placeholder compaction context.`;
 	ctx.ui.notify(message, "error");
 	throw new Error(message);
 }
+
+export async function injectPendingNativeWindowIntoPiCompactionRequest(payload: unknown, ctx: ExtensionContext, state: AdapterState): Promise<unknown | undefined> {
+	const pending = state.pendingPiCompactionNativeWindow;
+	if (!pending || pending.window.length === 0) return undefined;
+	if (!isResponsesCompatiblePayload(payload)) return undefined;
+	if (pending.sessionId !== ctx.sessionManager.getSessionId()) {
+		state.pendingPiCompactionNativeWindow = undefined;
+		return undefined;
+	}
+
+	const resolution = await resolveNativeCompactionEnvironment(ctx, { enabled: true }, payload);
+	if (!resolution.ok) return undefined;
+	const runtime = resolution.runtime;
+	if (pending.provider !== runtime.provider || pending.api !== runtime.api || pending.baseUrl !== runtime.baseUrl) return undefined;
+
+	const input = [...payload.input];
+	let insertAt = 0;
+	while (insertAt < input.length) {
+		const item = input[insertAt];
+		if (!isRecord(item) || (item.role !== "system" && item.role !== "developer")) break;
+		insertAt++;
+	}
+
+	return {
+		...payload,
+		input: [
+			...input.slice(0, insertAt),
+			...pending.window.map((item) => structuredClone(item)),
+			...input.slice(insertAt),
+		],
+	};
+}

package/src/adapter/provider-request.ts

@@ -5,7 +5,7 @@ import type { AdapterState } from "./state.ts";
 import { rewriteNativeImageGenerationTool } from "../tools/image-generation-tool.ts";
 import { rewriteNativeWebSearchTool } from "../tools/web-search-tool.ts";
 import { shouldUseCodexAdapter } from "./activation.ts";
-import { rewriteCodexCompactedProviderRequest } from "./compaction.ts";
+import { injectPendingNativeWindowIntoPiCompactionRequest, rewriteCodexCompactedProviderRequest } from "./compaction.ts";
 
 export async function rewriteCodexProviderRequest(payload: unknown, ctx: ExtensionContext, state: AdapterState): Promise<unknown | undefined> {
 	if (!shouldUseCodexAdapter(ctx, state.config) || (!isOpenAICodexContext(ctx) && !isResponsesContext(ctx))) {
@@ -21,5 +21,7 @@ export async function rewriteCodexProviderRequest(payload: unknown, ctx: Extensi
 		serviceTier: isOpenAICodex,
 		verbosity: true,
 	});
+	const piCompactionPayload = await injectPendingNativeWindowIntoPiCompactionRequest(configuredPayload, ctx, state);
+	if (piCompactionPayload !== undefined) return piCompactionPayload;
 	return (await rewriteCodexCompactedProviderRequest(configuredPayload, ctx, state)) ?? configuredPayload;
 }

package/src/adapter/state.ts

@@ -1,5 +1,15 @@
 import type { PromptSkill } from "../prompt/build-system-prompt.ts";
 import type { CodexConversionConfig } from "./config.ts";
+import type { ResponsesInputItem } from "./serializer.ts";
+
+export interface PendingPiCompactionNativeWindow {
+	window: ResponsesInputItem[];
+	provider: string;
+	api: string;
+	baseUrl: string;
+	sessionId: string;
+	sourceCompactionEntryId?: string;
+}
 
 export interface AdapterState {
 	enabled: boolean;
@@ -8,4 +18,5 @@ export interface AdapterState {
 	previousToolNames?: string[];
 	promptSkills: PromptSkill[];
 	config: CodexConversionConfig;
+	pendingPiCompactionNativeWindow?: PendingPiCompactionNativeWindow;
 }

package/src/codex-settings/command.ts

@@ -8,9 +8,10 @@ import {
 import { syncAdapter } from "../adapter/activation.ts";
 import type { AdapterState } from "../adapter/state.ts";
 import { openCodexSettingsScreen } from "./ui.ts";
+import { fetchCodexUsage, formatCodexUsage } from "./usage.ts";
 
-const CODEX_COMMAND_COMPLETIONS = ["all", "status", "fast", "search", "image", "compact", "low", "medium", "high"] as const;
-const CODEX_USAGE = "Usage: /codex, /codex all, /codex status, /codex fast, /codex search, /codex image, /codex compact, /codex low|medium|high";
+const CODEX_COMMAND_COMPLETIONS = ["all", "status", "fast", "search", "image", "compact", "usage", "low", "medium", "high"] as const;
+const CODEX_USAGE = "Usage: /codex, /codex all, /codex status, /codex fast, /codex search, /codex image, /codex compact, /codex usage, /codex low|medium|high";
 
 export function registerCodexCommand(pi: ExtensionAPI, state: AdapterState, onConfigApplied?: (config: CodexConversionConfig) => void): void {
 	function saveAndApply(ctx: ExtensionContext, nextConfig: CodexConversionConfig): boolean {
@@ -32,6 +33,36 @@ export function registerCodexCommand(pi: ExtensionAPI, state: AdapterState, onCo
 		handler: async (args, ctx) => {
 			state.config = readCodexConversionConfig();
 			const arg = args.trim().toLowerCase();
+			if (arg === "usage") {
+				let usage;
+				try {
+					usage = await fetchCodexUsage(ctx);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					if (!ctx.hasUI) {
+						ctx.ui.notify(message, "error");
+						return;
+					}
+					await openCodexSettingsScreen(ctx, {
+						initialConfig: state.config,
+						initialTab: "usage",
+						initialUsage: { error: message },
+						onChange: (config) => saveAndApply(ctx, config),
+					});
+					return;
+				}
+				if (!ctx.hasUI) {
+					ctx.ui.notify(formatCodexUsage(usage), "info");
+					return;
+				}
+				await openCodexSettingsScreen(ctx, {
+					initialConfig: state.config,
+					initialTab: "usage",
+					initialUsage: usage,
+					onChange: (config) => saveAndApply(ctx, config),
+				});
+				return;
+			}
 			if (arg === "compact") {
 				if (!ctx.hasUI) {
 					ctx.ui.notify(formatCodexSettings(state.config), "info");

package/src/codex-settings/ui.ts

@@ -10,25 +10,41 @@ import {
 	type CodexConversionConfig,
 } from "../adapter/config.ts";
 import { CHANGELOG_URL, DISCORD_URL, GITHUB_URL, ISSUE_URL, openExternalUrl } from "./links.ts";
+import { fetchCodexUsage, formatCodexUsage, type CodexUsageSnapshot } from "./usage.ts";
 
 export interface CodexSettingsScreenOptions {
 	initialConfig: CodexConversionConfig;
 	onChange: (nextConfig: CodexConversionConfig) => boolean;
 	initialTab?: SettingsTab;
+	initialUsage?: CodexUsageSnapshot | { error: string };
+	onRefreshUsage?: () => Promise<CodexUsageSnapshot>;
 }
 
-type SettingsTab = "general" | "compaction" | "overrides";
+type SettingsTab = "general" | "compaction" | "usage" | "overrides" | "about";
 
-const TAB_ORDER: readonly SettingsTab[] = ["general", "compaction", "overrides"];
+const TAB_ORDER: readonly SettingsTab[] = ["general", "compaction", "usage", "overrides", "about"];
 
 export async function openCodexSettingsScreen(ctx: ExtensionContext, options: CodexSettingsScreenOptions): Promise<void> {
 	let draft = { ...options.initialConfig };
 	let activeTab: SettingsTab = options.initialTab ?? "general";
+	let usageState: CodexUsageSnapshot | { error: string } | undefined = options.initialUsage;
+	let usageLoading = false;
+
+	const loadUsage = (requestRender: () => void) => {
+		if (usageLoading) return;
+		usageLoading = true;
+		requestRender();
+		(options.onRefreshUsage ?? (() => fetchCodexUsage(ctx)))()
+			.then((usage) => { usageState = usage; })
+			.catch((error) => { usageState = { error: error instanceof Error ? error.message : String(error) }; })
+			.finally(() => { usageLoading = false; requestRender(); });
+	};
 
 	await ctx.ui.custom<void>((tui, theme, _kb, done) => {
 		let settingsList = createSettingsList(activeTab, draft, options, (nextDraft) => {
 			draft = nextDraft;
 		}, done, () => tui.requestRender());
+		if (activeTab === "usage" && !usageState) loadUsage(() => tui.requestRender());
 
 		const switchTab = () => {
 			const currentIndex = TAB_ORDER.indexOf(activeTab);
@@ -36,6 +52,7 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 			settingsList = createSettingsList(activeTab, draft, options, (nextDraft) => {
 				draft = nextDraft;
 			}, done, () => tui.requestRender());
+			if (activeTab === "usage" && !usageState) loadUsage(() => tui.requestRender());
 			tui.requestRender();
 		};
 
@@ -47,12 +64,12 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 					rule(width, theme, "borderMuted"),
 					...(activeTab === "compaction" ? formatCompactionNotes(theme) : []),
 					...(activeTab === "overrides" ? formatOverridesNotes(theme) : []),
+					...(activeTab === "usage" ? formatUsageLines(theme, usageState, usageLoading) : []),
+					...(activeTab === "about" ? formatLinks(theme) : []),
 					"",
-					...settingsList.render(width),
-					rule(width, theme, "borderMuted"),
-					...formatLinks(theme),
+					...(activeTab === "usage" || activeTab === "about" ? [] : settingsList.render(width)),
 					rule(width, theme, "accent"),
-					theme.fg("dim", "  Tab to switch sections · g/c/d/i open links"),
+					theme.fg("dim", formatFooter(activeTab)),
 				].map((line) => truncateToWidth(line, width, "")),
 			invalidate: () => settingsList.invalidate(),
 			handleInput: (data: string) => {
@@ -60,7 +77,11 @@ export async function openCodexSettingsScreen(ctx: ExtensionContext, options: Co
 					switchTab();
 					return;
 				}
-				if (handleLinkKey(data, ctx)) return;
+				if (activeTab === "about" && handleLinkKey(data, ctx)) return;
+				if (activeTab === "usage" && data.toLowerCase() === "r") {
+					loadUsage(() => tui.requestRender());
+					return;
+				}
 				settingsList.handleInput?.(data);
 				tui.requestRender();
 			},
@@ -109,6 +130,8 @@ function createSettingsList(
 }
 
 function buildItems(tab: SettingsTab, draft: CodexConversionConfig): SettingItem[] {
+	if (tab === "usage" || tab === "about") return [];
+
 	if (tab === "compaction") {
 		return [
 			{ id: "responsesCompaction", label: "Responses compaction", currentValue: (draft.responsesCompaction ?? false) ? "on" : "off", values: ["off", "on"] },
@@ -150,7 +173,75 @@ function applySettingChange(id: string, value: string, draft: CodexConversionCon
 
 function formatTabs(activeTab: SettingsTab, theme: Theme): string {
 	const renderTab = (tab: SettingsTab, label: string) => activeTab === tab ? theme.bold(label) : theme.fg("dim", label);
-	return `  ${renderTab("general", "General")}  ${theme.fg("dim", "/")}  ${renderTab("compaction", "Compaction")}  ${theme.fg("dim", "/")}  ${renderTab("overrides", "Overrides")}`;
+	return `  ${renderTab("general", "General")}  ${theme.fg("dim", "/")}  ${renderTab("compaction", "Compaction")}  ${theme.fg("dim", "/")}  ${renderTab("usage", "Usage")}  ${theme.fg("dim", "/")}  ${renderTab("overrides", "Overrides")}  ${theme.fg("dim", "/")}  ${renderTab("about", "About")}`;
+}
+
+function formatFooter(activeTab: SettingsTab): string {
+	if (activeTab === "usage") return "  Tab to switch sections · r refresh";
+	if (activeTab === "about") return "  Tab to switch sections · g/c/d/i open links";
+	return "  Tab to switch sections";
+}
+
+function formatUsageLines(theme: Theme, usageState: CodexUsageSnapshot | { error: string } | undefined, loading: boolean): string[] {
+	if (loading && !usageState) return [theme.fg("dim", "  Loading Codex usage…")];
+	if (!usageState) return [theme.fg("dim", "  Loading Codex usage…")];
+	if ("error" in usageState) return [theme.fg("error", `  ${usageState.error}`), theme.fg("dim", "  Press r to retry.")];
+
+	const rows = usageState.limits.map((limit) => {
+		const primary = usageColumns(limit.primary);
+		const secondary = usageColumns(limit.secondary);
+		return [limit.limitName ?? limit.limitId, primary.bar, primary.percent, primary.reset, secondary.bar, secondary.percent, secondary.reset];
+	});
+	const headers = ["Limit", "5h", "", "Reset", "Weekly", "", "Reset"];
+	const widths = columnWidths([headers, ...rows]);
+	return [
+		`  ${theme.bold(`Codex usage${usageState.planType ? ` · ${usageState.planType}` : ""}`)}${loading ? theme.fg("dim", "  refreshing…") : ""}`,
+		"",
+		formatUsageRow(headers.map((header) => theme.fg("dim", header)), widths),
+		theme.fg("borderMuted", `  ${"─".repeat(widths.reduce((sum, width) => sum + width, 0) + (2 * (widths.length - 1)))}`),
+		...rows.map((row) => formatUsageRow(row, widths)),
+	];
+}
+
+function columnWidths(rows: string[][]): number[] {
+	const columnCount = Math.max(...rows.map((row) => row.length));
+	return Array.from({ length: columnCount }, (_, index) => Math.max(...rows.map((row) => stripAnsi(row[index] ?? "").length)));
+}
+
+function stripAnsi(value: string): string {
+	return value.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function padCell(value: string, width: number): string {
+	return value + " ".repeat(Math.max(0, width - stripAnsi(value).length));
+}
+
+function formatUsageRow(row: string[], widths: number[]): string {
+	return `  ${row.map((cell, index) => padCell(cell, widths[index] ?? 0)).join("  ")}`;
+}
+
+function usageColumns(window: { usedPercent?: number; windowMinutes?: number; resetsAt?: number } | undefined): { bar: string; percent: string; reset: string } {
+	if (!window) return { bar: "—", percent: "", reset: "" };
+	const percent = window.usedPercent === undefined ? undefined : Math.max(0, Math.min(100, window.usedPercent));
+	return {
+		bar: bar(percent),
+		percent: percent === undefined ? "?%" : `${Math.round(percent)}%`,
+		reset: formatResetShort(window.resetsAt),
+	};
+}
+
+function bar(percent: number | undefined): string {
+	if (percent === undefined) return "░░░░░░░░░░";
+	const filled = Math.max(0, Math.min(10, Math.round(percent / 10)));
+	return "█".repeat(filled) + "░".repeat(10 - filled);
+}
+
+function formatResetShort(timestampSeconds: number | undefined): string {
+	if (!timestampSeconds) return "reset ?";
+	const minutes = Math.max(0, Math.round((timestampSeconds * 1000 - Date.now()) / 60000));
+	if (minutes < 90) return `~${minutes}m`;
+	if (minutes < 60 * 48) return `~${Math.round(minutes / 60)}h`;
+	return `~${Math.round(minutes / 1440)}d`;
 }
 
 function formatLinks(theme: Theme): string[] {

package/src/codex-settings/usage.ts

@@ -0,0 +1,151 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+const JWT_CLAIM_PATH = "https://api.openai.com/auth";
+
+type RuntimeModel = Model<Api>;
+
+export interface CodexUsageWindow {
+	usedPercent?: number;
+	windowMinutes?: number;
+	resetsAt?: number;
+}
+
+export interface CodexUsageLimit {
+	limitId: string;
+	limitName?: string;
+	primary?: CodexUsageWindow;
+	secondary?: CodexUsageWindow;
+}
+
+export interface CodexUsageSnapshot {
+	planType?: string;
+	limits: CodexUsageLimit[];
+	raw: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function numberValue(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+export function buildCodexUsageUrl(): string {
+	return `${DEFAULT_CODEX_BASE_URL}/wham/usage`;
+}
+
+function extractBearerToken(headers: Headers): string | undefined {
+	const authorization = headers.get("authorization")?.trim();
+	const match = authorization?.match(/^Bearer\s+(.+)$/i);
+	return match?.[1]?.trim();
+}
+
+function extractAccountId(token: string): string | undefined {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return undefined;
+		const payload = JSON.parse(Buffer.from(parts[1] ?? "", "base64").toString("utf8")) as unknown;
+		const authClaims = isRecord(payload) ? payload[JWT_CLAIM_PATH] : undefined;
+		const accountId = isRecord(authClaims) ? authClaims.chatgpt_account_id : undefined;
+		return stringValue(accountId);
+	} catch {
+		return undefined;
+	}
+}
+
+async function buildCodexUsageHeaders(ctx: ExtensionContext, model: RuntimeModel): Promise<Headers> {
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) throw new Error(auth.error);
+	const headers = new Headers(model.headers);
+	for (const [key, value] of Object.entries(auth.headers ?? {})) headers.set(key, value);
+	if (auth.apiKey) headers.set("authorization", `Bearer ${auth.apiKey}`);
+	const token = auth.apiKey ?? extractBearerToken(headers);
+	const accountId = token ? extractAccountId(token) : undefined;
+	if (accountId) headers.set("chatgpt-account-id", accountId);
+	headers.set("accept", "application/json");
+	headers.set("originator", "pi");
+	return headers;
+}
+
+function parseWindow(value: unknown): CodexUsageWindow | undefined {
+	if (!isRecord(value)) return undefined;
+	const usedPercent = numberValue(value.used_percent);
+	const limitWindowSeconds = numberValue(value.limit_window_seconds);
+	const windowMinutes = numberValue(value.window_minutes) ?? (limitWindowSeconds === undefined ? undefined : Math.ceil(limitWindowSeconds / 60));
+	const resetsAt = numberValue(value.resets_at) ?? numberValue(value.reset_at);
+	return usedPercent === undefined && windowMinutes === undefined && resetsAt === undefined ? undefined : { usedPercent, windowMinutes, resetsAt };
+}
+
+function parseRateLimit(value: unknown): { primary?: CodexUsageWindow; secondary?: CodexUsageWindow } {
+	if (!isRecord(value)) return {};
+	return {
+		primary: parseWindow(value.primary_window) ?? parseWindow(value.primary),
+		secondary: parseWindow(value.secondary_window) ?? parseWindow(value.secondary),
+	};
+}
+
+export function parseCodexUsagePayload(payload: unknown): CodexUsageSnapshot {
+	const root = isRecord(payload) ? payload : {};
+	const limits: CodexUsageLimit[] = [];
+	const addLimit = (limitId: string, limitName: string | undefined, source: unknown) => {
+		const rateLimit = isRecord(source) && "rate_limit" in source ? source.rate_limit : source;
+		const parsed = parseRateLimit(rateLimit);
+		limits.push({
+			limitId,
+			...(limitName ? { limitName } : {}),
+			...(parsed.primary ? { primary: parsed.primary } : {}),
+			...(parsed.secondary ? { secondary: parsed.secondary } : {}),
+		});
+	};
+	addLimit("codex", undefined, root.rate_limit);
+	if (Array.isArray(root.additional_rate_limits)) {
+		for (const item of root.additional_rate_limits) {
+			if (!isRecord(item)) continue;
+			addLimit(stringValue(item.metered_feature) ?? "additional", stringValue(item.limit_name), item);
+		}
+	}
+	return { planType: stringValue(root.plan_type), limits, raw: payload };
+}
+
+export async function fetchCodexUsage(ctx: ExtensionContext): Promise<CodexUsageSnapshot> {
+	const model = ctx.model;
+	if (!model) throw new Error("No active model selected.");
+	if (model.provider !== "openai-codex") {
+		throw new Error("Codex usage is only available for OpenAI Codex subscription models.");
+	}
+	const response = await fetch(buildCodexUsageUrl(), { method: "GET", headers: await buildCodexUsageHeaders(ctx, model), signal: ctx.signal });
+	const text = await response.text();
+	if (!response.ok) throw new Error(`Usage request failed (${response.status}): ${text || response.statusText}`);
+	return parseCodexUsagePayload(JSON.parse(text));
+}
+
+function formatReset(timestampSeconds: number | undefined): string {
+	if (!timestampSeconds) return "reset unknown";
+	const ms = timestampSeconds * 1000;
+	const minutes = Math.max(0, Math.round((ms - Date.now()) / 60000));
+	return minutes < 90 ? `resets in ~${minutes}m` : `resets ${new Date(ms).toLocaleString()}`;
+}
+
+function formatWindow(label: string, window: CodexUsageWindow | undefined): string | undefined {
+	if (!window) return undefined;
+	const percent = window.usedPercent === undefined ? "?" : `${Math.round(window.usedPercent)}%`;
+	const span = window.windowMinutes ? `${Math.round(window.windowMinutes)}m` : "window";
+	return `${label}: ${percent} used (${span}, ${formatReset(window.resetsAt)})`;
+}
+
+export function formatCodexUsage(snapshot: CodexUsageSnapshot): string {
+	const lines = [`Codex usage${snapshot.planType ? ` (${snapshot.planType})` : ""}:`];
+	for (const limit of snapshot.limits) {
+		const title = limit.limitName ?? limit.limitId;
+		const parts = [formatWindow("5h", limit.primary), formatWindow("weekly", limit.secondary)].filter(Boolean);
+		lines.push(`- ${title}: ${parts.length ? parts.join("; ") : "no usage data"}`);
+	}
+	return lines.join("\n");
+}

package/src/index.ts

@@ -163,6 +163,7 @@ export default function codexConversion(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_compact", async (event) => {
+		state.pendingPiCompactionNativeWindow = undefined;
 		if (!event.fromExtension || !isNativeCompactionDetails(event.compactionEntry.details)) return;
 		pi.sendMessage(
 			{