feat(openai-codex): add ChatGPT subscription usage limits dashboard (#10813)

Author: hannesrudolph

packages/types/src/providers/index.ts

@@ -19,6 +19,7 @@ export * from "./moonshot.js"
 export * from "./ollama.js"
 export * from "./openai.js"
 export * from "./openai-codex.js"
+export * from "./openai-codex-rate-limits.js"
 export * from "./openrouter.js"
 export * from "./qwen-code.js"
 export * from "./requesty.js"

packages/types/src/providers/openai-codex-rate-limits.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenAI Codex usage/rate limit information (ChatGPT subscription)
+ */
+export interface OpenAiCodexRateLimitInfo {
+	primary?: {
+		/** Used percent in 0–100 */
+		usedPercent: number
+		/** Window length in minutes, when provided */
+		windowMinutes?: number
+		/** Reset time (unix ms since epoch), when provided */
+		resetsAt?: number
+	}
+	secondary?: {
+		/** Used percent in 0–100 */
+		usedPercent: number
+		/** Window length in minutes, when provided */
+		windowMinutes?: number
+		/** Reset time (unix ms since epoch), when provided */
+		resetsAt?: number
+	}
+	credits?: {
+		hasCredits: boolean
+		unlimited: boolean
+		balance?: string
+	}
+	planType?: string
+	/** Timestamp when this was fetched (unix ms since epoch) */
+	fetchedAt: number
+}

packages/types/src/vscode-extension-host.ts

@@ -19,6 +19,7 @@ import type { SerializedCustomToolDefinition } from "./custom-tool.js"
 import type { GitCommit } from "./git.js"
 import type { McpServer } from "./mcp.js"
 import type { ModelRecord, RouterModels } from "./model.js"
+import type { OpenAiCodexRateLimitInfo } from "./providers/openai-codex-rate-limits.js"
 
 /**
  * ExtensionMessage
@@ -95,6 +96,7 @@ export interface ExtensionMessage {
 		| "customToolsResult"
 		| "modes"
 		| "taskWithAggregatedCosts"
+		| "openAiCodexRateLimits"
 	text?: string
 	payload?: any // eslint-disable-line @typescript-eslint/no-explicit-any
 	checkpointWarning?: {
@@ -150,7 +152,9 @@ export interface ExtensionMessage {
 	customMode?: ModeConfig
 	slug?: string
 	success?: boolean
-	values?: Record<string, any> // eslint-disable-line @typescript-eslint/no-explicit-any
+	/** Generic payload for extension messages that use `values` */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	values?: Record<string, any>
 	requestId?: string
 	promptText?: string
 	results?:
@@ -192,6 +196,12 @@ export interface ExtensionMessage {
 	historyItem?: HistoryItem
 }
 
+export interface OpenAiCodexRateLimitsMessage {
+	type: "openAiCodexRateLimits"
+	values?: OpenAiCodexRateLimitInfo
+	error?: string
+}
+
 export type ExtensionState = Pick<
 	GlobalSettings,
 	| "currentApiConfigName"
@@ -518,6 +528,7 @@ export interface WebviewMessage {
 		| "openDebugUiHistory"
 		| "downloadErrorDiagnostics"
 		| "requestClaudeCodeRateLimits"
+		| "requestOpenAiCodexRateLimits"
 		| "refreshCustomTools"
 		| "requestModes"
 		| "switchMode"
@@ -546,6 +557,7 @@ export interface WebviewMessage {
 	promptMode?: string | "enhance"
 	customPrompt?: PromptComponent
 	dataUrls?: string[]
+	/** Generic payload for webview messages that use `values` */
 	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	values?: Record<string, any>
 	query?: string
@@ -612,6 +624,10 @@ export interface WebviewMessage {
 	updatedSettings?: RooCodeSettings
 }
 
+export interface RequestOpenAiCodexRateLimitsMessage {
+	type: "requestOpenAiCodexRateLimits"
+}
+
 export const checkoutDiffPayloadSchema = z.object({
 	ts: z.number().optional(),
 	previousCommitHash: z.string().optional(),

src/core/webview/__tests__/webviewMessageHandler.spec.ts

@@ -5,6 +5,17 @@ import type { Mock } from "vitest"
 // Mock dependencies - must come before imports
 vi.mock("../../../api/providers/fetchers/modelCache")
 
+vi.mock("../../../integrations/openai-codex/oauth", () => ({
+	openAiCodexOAuthManager: {
+		getAccessToken: vi.fn(),
+		getAccountId: vi.fn(),
+	},
+}))
+
+vi.mock("../../../integrations/openai-codex/rate-limits", () => ({
+	fetchOpenAiCodexRateLimitInfo: vi.fn(),
+}))
+
 // Mock the diagnosticsHandler module
 vi.mock("../diagnosticsHandler", () => ({
 	generateErrorDiagnostics: vi.fn().mockResolvedValue({ success: true, filePath: "/tmp/diagnostics.json" }),
@@ -15,8 +26,13 @@ import type { ModelRecord } from "@roo-code/types"
 import { webviewMessageHandler } from "../webviewMessageHandler"
 import type { ClineProvider } from "../ClineProvider"
 import { getModels } from "../../../api/providers/fetchers/modelCache"
+const { openAiCodexOAuthManager } = await import("../../../integrations/openai-codex/oauth")
+const { fetchOpenAiCodexRateLimitInfo } = await import("../../../integrations/openai-codex/rate-limits")
 
 const mockGetModels = getModels as Mock<typeof getModels>
+const mockGetAccessToken = vi.mocked(openAiCodexOAuthManager.getAccessToken)
+const mockGetAccountId = vi.mocked(openAiCodexOAuthManager.getAccountId)
+const mockFetchOpenAiCodexRateLimitInfo = vi.mocked(fetchOpenAiCodexRateLimitInfo)
 
 // Mock ClineProvider
 const mockClineProvider = {
@@ -580,6 +596,43 @@ describe("webviewMessageHandler - requestRouterModels", () => {
 	})
 })
 
+describe("webviewMessageHandler - requestOpenAiCodexRateLimits", () => {
+	beforeEach(() => {
+		vi.clearAllMocks()
+		mockGetAccessToken.mockResolvedValue(null)
+		mockGetAccountId.mockResolvedValue(null)
+	})
+
+	it("posts error when not authenticated", async () => {
+		await webviewMessageHandler(mockClineProvider, { type: "requestOpenAiCodexRateLimits" } as any)
+
+		expect(mockClineProvider.postMessageToWebview).toHaveBeenCalledWith({
+			type: "openAiCodexRateLimits",
+			error: "Not authenticated with OpenAI Codex",
+		})
+	})
+
+	it("posts values when authenticated", async () => {
+		mockGetAccessToken.mockResolvedValue("token")
+		mockGetAccountId.mockResolvedValue("acct_123")
+		mockFetchOpenAiCodexRateLimitInfo.mockResolvedValue({
+			primary: { usedPercent: 10, resetsAt: 1700000000000 },
+			fetchedAt: 1700000000000,
+		})
+
+		await webviewMessageHandler(mockClineProvider, { type: "requestOpenAiCodexRateLimits" } as any)
+
+		expect(mockFetchOpenAiCodexRateLimitInfo).toHaveBeenCalledWith("token", { accountId: "acct_123" })
+		expect(mockClineProvider.postMessageToWebview).toHaveBeenCalledWith({
+			type: "openAiCodexRateLimits",
+			values: {
+				primary: { usedPercent: 10, resetsAt: 1700000000000 },
+				fetchedAt: 1700000000000,
+			},
+		})
+	})
+})
+
 describe("webviewMessageHandler - deleteCustomMode", () => {
 	beforeEach(() => {
 		vi.clearAllMocks()

src/core/webview/webviewMessageHandler.ts

@@ -3285,6 +3285,38 @@ export const webviewMessageHandler = async (
 			break
 		}
 
+		case "requestOpenAiCodexRateLimits": {
+			try {
+				const { openAiCodexOAuthManager } = await import("../../integrations/openai-codex/oauth")
+				const accessToken = await openAiCodexOAuthManager.getAccessToken()
+
+				if (!accessToken) {
+					provider.postMessageToWebview({
+						type: "openAiCodexRateLimits",
+						error: "Not authenticated with OpenAI Codex",
+					})
+					break
+				}
+
+				const accountId = await openAiCodexOAuthManager.getAccountId()
+				const { fetchOpenAiCodexRateLimitInfo } = await import("../../integrations/openai-codex/rate-limits")
+				const rateLimits = await fetchOpenAiCodexRateLimitInfo(accessToken, { accountId })
+
+				provider.postMessageToWebview({
+					type: "openAiCodexRateLimits",
+					values: rateLimits,
+				})
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error)
+				provider.log(`Error fetching OpenAI Codex rate limits: ${errorMessage}`)
+				provider.postMessageToWebview({
+					type: "openAiCodexRateLimits",
+					error: errorMessage,
+				})
+			}
+			break
+		}
+
 		case "openDebugApiHistory":
 		case "openDebugUiHistory": {
 			const currentTask = provider.getCurrentTask()

src/integrations/openai-codex/__tests__/rate-limits.spec.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest"
+
+import { parseOpenAiCodexUsagePayload } from "../rate-limits"
+
+describe("parseOpenAiCodexUsagePayload()", () => {
+	it("maps primary/secondary windows", () => {
+		const fetchedAt = 1234567890000
+		const payload = {
+			rate_limit: {
+				primary_window: { used_percent: 12.34, limit_window_seconds: 300 * 60, reset_at: 1700000000 },
+				secondary_window: { used_percent: 99.9, limit_window_seconds: 10080 * 60, reset_at: 1700000000 },
+			},
+			plan_type: "plus",
+		}
+
+		const out = parseOpenAiCodexUsagePayload(payload, fetchedAt)
+
+		expect(out).toEqual({
+			primary: {
+				usedPercent: 12.34,
+				windowMinutes: 300,
+				resetsAt: 1700000000 * 1000,
+			},
+			secondary: {
+				usedPercent: 99.9,
+				windowMinutes: 10080,
+				resetsAt: 1700000000 * 1000,
+			},
+			planType: "plus",
+			fetchedAt,
+		})
+	})
+
+	it("clamps used_percent to 0–100 and tolerates missing fields", () => {
+		const fetchedAt = 1
+		const payload = {
+			rate_limit: {
+				primary_window: { used_percent: 1000 },
+				secondary_window: { used_percent: -5 },
+			},
+		}
+		const out = parseOpenAiCodexUsagePayload(payload, fetchedAt)
+		expect(out.primary?.usedPercent).toBe(100)
+		expect(out.secondary?.usedPercent).toBe(0)
+		expect(out.fetchedAt).toBe(fetchedAt)
+	})
+})

src/integrations/openai-codex/rate-limits.ts

@@ -0,0 +1,96 @@
+import type { OpenAiCodexRateLimitInfo } from "@roo-code/types"
+
+const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage"
+
+type WhamUsageResponse = {
+	rate_limit?: {
+		primary_window?: {
+			limit_window_seconds?: number
+			used_percent?: number
+			reset_at?: number
+		}
+		secondary_window?: {
+			limit_window_seconds?: number
+			used_percent?: number
+			reset_at?: number
+		}
+	}
+	plan_type?: string
+}
+
+function clampPercent(value: number): number {
+	if (!Number.isFinite(value)) return 0
+	return Math.max(0, Math.min(100, value))
+}
+
+function secondsToMs(value: number | undefined): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? Math.round(value * 1000) : undefined
+}
+
+export function parseOpenAiCodexUsagePayload(payload: unknown, fetchedAt: number): OpenAiCodexRateLimitInfo {
+	const data = (payload && typeof payload === "object" ? payload : {}) as WhamUsageResponse
+	const primaryRaw = data.rate_limit?.primary_window
+	const secondaryRaw = data.rate_limit?.secondary_window
+
+	const primary: OpenAiCodexRateLimitInfo["primary"] | undefined =
+		primaryRaw && typeof primaryRaw.used_percent === "number"
+			? {
+					usedPercent: clampPercent(primaryRaw.used_percent),
+					...(typeof primaryRaw.limit_window_seconds === "number"
+						? { windowMinutes: Math.round(primaryRaw.limit_window_seconds / 60) }
+						: {}),
+					...(secondsToMs(primaryRaw.reset_at) !== undefined
+						? { resetsAt: secondsToMs(primaryRaw.reset_at) }
+						: {}),
+				}
+			: undefined
+
+	const secondary: OpenAiCodexRateLimitInfo["secondary"] | undefined =
+		secondaryRaw && typeof secondaryRaw.used_percent === "number"
+			? {
+					usedPercent: clampPercent(secondaryRaw.used_percent),
+					...(typeof secondaryRaw.limit_window_seconds === "number"
+						? { windowMinutes: Math.round(secondaryRaw.limit_window_seconds / 60) }
+						: {}),
+					...(secondsToMs(secondaryRaw.reset_at) !== undefined
+						? { resetsAt: secondsToMs(secondaryRaw.reset_at) }
+						: {}),
+				}
+			: undefined
+
+	return {
+		...(primary ? { primary } : {}),
+		...(secondary ? { secondary } : {}),
+		...(typeof data.plan_type === "string" ? { planType: data.plan_type } : {}),
+		fetchedAt,
+	}
+}
+
+export async function fetchOpenAiCodexRateLimitInfo(
+	accessToken: string,
+	options?: { accountId?: string | null },
+): Promise<OpenAiCodexRateLimitInfo> {
+	const fetchedAt = Date.now()
+	const headers: Record<string, string> = {
+		Authorization: `Bearer ${accessToken}`,
+		Accept: "application/json",
+	}
+	if (options?.accountId) {
+		headers["ChatGPT-Account-Id"] = options.accountId
+	}
+
+	const response = await fetch(WHAM_USAGE_URL, { method: "GET", headers })
+	if (!response.ok) {
+		const text = await response.text().catch(() => "")
+		throw new Error(
+			`OpenAI Codex WHAM usage request failed: ${response.status} ${response.statusText}${text ? ` - ${text}` : ""}`,
+		)
+	}
+
+	const json = (await response.json()) as unknown
+	const parsed = parseOpenAiCodexUsagePayload(json, fetchedAt)
+	if (!parsed.primary && !parsed.secondary) {
+		throw new Error("OpenAI Codex WHAM usage response did not include rate_limit windows")
+	}
+	return parsed
+}

webview-ui/src/components/settings/providers/OpenAICodex.tsx

@@ -7,6 +7,7 @@ import { Button } from "@src/components/ui"
 import { vscode } from "@src/utils/vscode"
 
 import { ModelPicker } from "../ModelPicker"
+import { OpenAICodexRateLimitDashboard } from "./OpenAICodexRateLimitDashboard"
 
 interface OpenAICodexProps {
 	apiConfiguration: ProviderSettings
@@ -50,6 +51,9 @@ export const OpenAICodex: React.FC<OpenAICodexProps> = ({
 				)}
 			</div>
 
+			{/* Rate Limit Dashboard - only shown when authenticated */}
+			<OpenAICodexRateLimitDashboard isAuthenticated={openAiCodexIsAuthenticated} />
+
 			{/* Model Picker */}
 			<ModelPicker
 				apiConfiguration={apiConfiguration}