Imported from kingdomseed/cursor-calculator (AGENTS.md). Install upstream with npx skills add kingdomseed/cursor-calculator. Copyright stays with the author.

AGENTS.md

This file provides guidance to coding agents working in this repository.

Project Goal

This project is an empirical budgeting tool for Cursor IDE pricing. Every number shown in the app must trace back to Cursor's official docs at https://cursor.com/docs and the relevant pricing or individual model pages. Do not invent or assume pricing rules. If a pricing rule or model rate cannot be sourced from Cursor docs, mark it as unverified instead of presenting it as fact.

The app answers three questions:

1. Budget mode — “I have a budget.” Which plan is best, and how many tokens do I get per model?
2. Token mode — “I know my token usage.” What will it cost, and which plan covers it?
3. CSV replay mode — “I have a Cursor usage export.” Reprice the exact imported token columns and show which plan would have covered that month.

Source-of-Truth Boundaries

Manual mode and CSV replay do not share the same source catalog:

• src/data/cursor-pricing.json is the source of truth for current Cursor-supported manual calculations.
• src/data/importReplayHistoricalModels.ts and src/data/importReplayLabelMappings.ts exist only for CSV replay of retired historical labels and mapping policy for labels that no longer have a current Cursor catalog entry.
• Import-only historical or provider-backed estimates must stay visibly approximate and must not leak into the manual model selector as though they were current Cursor-native entries.

When Cursor updates pricing, update the underlying data and the calculations together so the UI remains consistent with the docs.

Commands

• npm install — install dependencies
• npm run dev — run the Vite dev server
• npm run build — type-check and build production assets into dist/
• npm run lint — run ESLint
• npm run preview — preview the production build
• npm test — run Vitest once
• npm run test:watch — run Vitest in watch mode

Architecture

This is a single-page React + TypeScript app deployed to Vercel.

Stack: React 19, TypeScript 5.9, Vite 7, Tailwind CSS 4 via @tailwindcss/postcss.

Key structure

• src/App.tsx — composition root and page layout
• src/app/calculatorState.ts — reducer-owned source state and defaults
• src/app/calculatorReducer.ts — calculator state transitions
• src/app/calculatorSelectors.ts — derived app view data, replay reports, and recommendations
• src/app/cursorImportActions.ts — import action sequencing
• src/app/cursorImportPresentation.ts — UI-facing replay summary formatting
• src/app/useCalculatorController.ts — reducer wiring, file reading, and UI callbacks
• src/components/ — presentational UI components, including import flow UI
• src/data/cursor-pricing.json — current Cursor pricing catalog for manual mode
• src/data/importReplayHistoricalModels.ts — import-only historical replay models
• src/data/importReplayLabelMappings.ts — import-only replay label mappings and approximations
• src/domain/catalog/ — current Cursor catalog accessors and types
• src/domain/recommendation/ — pricing math, effective rates, conversions, and recommendations
• src/domain/importReplay/ — CSV parsing, normalization, pricing, aggregation, and summary logic
• src/domain/modelConfig/ — model config defaults, selection reconciliation, and capability helpers
• src/lib/types.ts — shared type barrel for component imports
• src/domain/*/__tests__/ and src/app/__tests__/ — current automated coverage
• data/private/raw/cursor/ — optional local-only copied Cursor export fixtures; data/private/ is gitignored

There is no routing layer or external state-management library. Keep src/App.tsx composition-focused, app orchestration in src/app/, and domain logic in src/domain/.

Core calculation logic

• getPricingCatalog(), getManualApiModels(), getPlans() — current manual catalog accessors
• getImportReplayModels() — replay catalog assembly from current and historical import-only models
• computeRecommendation() — shared recommendation entry point for budget mode and manual token mode
• computeExactUsageRecommendation() — plan comparison logic for imported exact-usage rows
• computeBillableRates() and computeEffectiveRates() — Max/long-context rate overrides, fast variants, and caching math
• parseCursorUsageFiles() — CSV parsing, billable row filtering, normalization, replay pricing, and summaries
• useCalculatorController() — app orchestration for reducer state, selectors, and CSV-loading side effects

Budget mode uses exact-token pricing with cache-read share via dollarsToExactTokens(). The legacy DEFAULT_RE_READS = 3 pattern is only used by the per-model effective rate display in ModelConfigRow.

Pricing Domain Rules

All pricing facts should be verified against Cursor docs before changing the catalog or recommendation logic.

Empirical boundary

• Manual calculator mode may only expose models and rates present in src/data/cursor-pricing.json.
• CSV replay may use import-only estimates for retired labels from historical exports, but those rows must remain clearly labeled as approximate.
• Do not move provider-backed replay estimates into the main pricing JSON unless Cursor publishes a current first-party pricing entry for them.

Usage pools

• Cursor Models — Composer 2.5, Grok 4.6, and Grok 4.5. Generous included usage; no published dollar amount. Auto is a router, not a pool.
• Other Models — third-party models at API rates. Last published official floors: Pro at least $20, Pro Plus $70, Ultra $400. Live docs now say only “Included.” Those floors are not current guaranteed included dollars. Ultra used to include $400 on a $200 plan; you may not get that now. Teams dollars unpublished.
• Do not treat $20 / $70 / $400 as current guaranteed coverage in recommendation or overage math. Keep them as last-published historical floors. If a floor still applies, billed-beyond is usage minus that floor. If it does not, Other Models usage bills in full. Teams/Enterprise add $0.25/M on third-party tokens.

Max Mode

Max Mode is available only on legacy request-based plans, at API rate plus 20%. Current usage-based plans do not include Max Mode, so the +20% upcharge is hidden. Some model pages publish separate long-context rates when input exceeds the default context window.

Current documented examples:

• Claude 4.6 Sonnet and Claude Opus 4.8: no long-context surcharge — same per-token rates in Max Mode
• Gemini 3.1 Pro: input 2x and output 1.5x when input exceeds 200k
• GPT-5.4 and GPT-5.5: input 2x and output 1.5x when input exceeds 272k

Model-specific long-context rates belong in the catalog as documented rate overrides. Do not infer a blanket Max Mode multiplier.

Fast mode

Fast mode is a distinct model variant, not a toggle on the base model.

• Claude Opus 4.8 Fast: $10/M input and $50/M output, and requires Max Mode
• GPT-5.5 Fast: $12.50/M input and $75/M output
• GPT-5.6 Sol, Terra, and Luna Fast: 2x each model's standard rates
• Composer 2.5 Fast: $3/M input and $15/M output
• Grok 4.5 Fast: $4/M input and $18/M output

Historical imported fast labels may still be replayed as best-effort estimates, but that approximation logic belongs only in the import layer.

Thinking mode

Thinking mode exists for Claude models, current GPT models, Gemini models, and Composer 2.5, but Cursor docs do not currently publish separate token pricing for thinking tokens.

Context windows

• Claude Opus 4.8 and Claude Fable 5: 300k default, 1M max
• Claude 4.6 Sonnet and Gemini 3.1 Pro: 200k default, 1M max
• GPT-5.5 and GPT-5.4: 272k default, 1M max
• Claude Sonnet 5: 200k default, 1M max
• GPT-5.6 Sol: 272k default, 1M max; input 2x and output 1.5x above 272k
• GPT-5.6 Terra and Luna: 272k default, no Max Mode extension
• Composer 2.5: 200k default, no Max Mode
• Grok 4.5: 256k default, no Max Mode extension
• GLM 5.2: 200k default, no Max Mode extension
• Kimi K2.7 Code: 262k default, no Max Mode extension

Testing and Verification

• Prefer targeted tests for the area you changed before broader validation.
• Run npm test for logic changes and npm run lint for code quality when relevant.
• Use npm run build before finalizing significant app or type changes.
• Browser verification still matters for file-upload behavior because there is not yet a committed jsdom/browser integration suite for the import UI path.

Styling and UI

• Use Tailwind utility classes inline; there is no component library.
• Keep the existing palette aligned with #14120b, #f7f7f4, and #e0e0d8.
• Reuse the established provider color mapping in PROVIDER_COLORS.

Working Rules for Agents

• Keep changes minimal and aligned with the existing architecture.
• Fix root causes instead of layering on ad hoc patches.
• Do not add unsupported pricing assumptions or undocumented Cursor behavior.
• Treat imported historical replay behavior as approximate unless backed by current first-party Cursor docs.
• Preserve the distinction between current manual pricing data and historical replay-only data.
• Do not write mannered prose in UI copy or agent-facing repo docs. Mannered prose substitutes metaphor and flourish for direct statement. Write "a parameter worth varying," not "a dial worth turning." Write "this point still matters," not "this point earns its keep." Those phrases display the writer instead of stating the idea. They also import connotations you did not choose. When a literal phrase is available, use it.