An interactive token budget visualizer for LLM context windows.
Context Surgeon helps developers see exactly where their tokens are going across system prompts, tool schemas, few-shot examples, RAG documents, conversation history, and user messages — then uses AI-powered surgery to trim what doesn't fit.
"The LLM is the CPU and the context window is the RAM." — Andrej Karpathy
As LLMs move from simple chat interfaces to complex agentic systems, the bottleneck has shifted from prompt engineering (crafting a single good prompt) to context engineering (managing everything that goes into the context window). A production LLM application might combine a system prompt, tool schemas, retrieved documents, conversation history, and few-shot examples — all competing for limited context space.
When the total exceeds a model's context window, developers resort to guesswork: truncating conversation history, removing examples, or compressing instructions. Context Surgeon makes this process visible and systematic — see exactly where tokens are allocated, compare across models, and use AI-powered analysis to identify what can be safely trimmed.
- Node.js 18+
- An Anthropic API key (for Surgery Mode and Exact Count)
# Clone the repo
git clone https://github.com/your-username/context-surgeon.git
cd context-surgeon
# Install dependencies
npm install
# Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local
# Start the dev server
npm run devOpen http://localhost:5173 and start pasting your prompts — or click Load Example Prompt to see it in action.
| Command | Description |
|---|---|
npm run dev |
Start dev server |
npm run build |
Production build (TypeScript check + Vite) |
npm run test |
Run unit & component tests (Vitest) |
npm run test:watch |
Run tests in watch mode |
npm run test:e2e |
Run E2E tests (Playwright) |
npm run lint |
Run ESLint |
npm run format |
Format with Prettier |
npm run typecheck |
TypeScript type checking |
npm run preview |
Preview production build |
- Treemap — colored rectangles proportional to each section's token usage, with hover tooltips showing counts, percentages, and estimated costs
- Stacked bar chart — horizontal budget allocation view with output reserve boundary line
- Live updates — type or paste content and watch visualizations animate in real time (D3.js data join pattern with 300ms transitions)
- Client-side WASM — tiktoken runs directly in the browser via WebAssembly (~2.5MB gzipped), no server round-trips for counting
- Multiple encodings —
cl100k_base(GPT-4, Claude) ando200k_base(GPT-4o) with automatic switching when you change models - Exact counts for Claude — one-click API call to Anthropic's
/v1/messages/count_tokensendpoint, with approximate vs. exact comparison
- Claude-powered analysis — when you exceed a model's context window, Claude analyzes your prompt structure and suggests specific changes
- Inline word-level diffs — see exactly what text is being removed (red strikethrough) and added (green) for each suggestion
- Accept / Reject / Edit — apply suggestions individually, reject ones you disagree with, or edit the suggested text before accepting
- Undo support —
Cmd+Zrestores any accepted suggestion with per-section undo stacks
- Per-request input/output costs based on real model pricing
- Monthly projections with configurable requests-per-day
- Copy to clipboard — formatted prompt with labeled section headers
- Download JSON — structured export with model info, section data, token counts, and timestamp
| Shortcut | Action |
|---|---|
Cmd+Enter |
Trigger surgery mode |
Cmd+E |
Copy prompt to clipboard |
Cmd+Z |
Undo accepted suggestion |
Escape |
Close surgery panel |
| Layer | Technology |
|---|---|
| Framework | React 19, TypeScript 5.9 |
| Build | Vite 7.3 |
| Styling | Tailwind CSS v4 |
| State | Zustand v5 (3 stores: budget, surgery, toasts) |
| Visualization | D3.js v7 (treemap + stacked bar chart) |
| Tokenization | tiktoken WASM (cl100k_base, o200k_base) |
| API | Vercel Edge Functions → Claude API |
| Testing | Vitest (56 unit/component tests), Playwright (10 E2E tests) |
| Fonts | Inter, JetBrains Mono (Google Fonts) |
| Model | Context Window | Encoding | Exact Count |
|---|---|---|---|
| Claude Sonnet 4 | 200K | cl100k_base | ✅ |
| Claude Haiku 4 | 200K | cl100k_base | ✅ |
| GPT-4o | 128K | o200k_base | — |
| GPT-4 Turbo | 128K | cl100k_base | — |
Token counts for Claude models are approximate (Claude uses a proprietary tokenizer). Use the Exact Count button for a precise number via the Anthropic API.
- Zustand over Context — three independent stores (budget, surgery, toasts) with selector-based subscriptions for minimal re-renders. Stores can read from each other via
getState()without circular dependencies. - D3 owns SVG, React owns HTML — clear boundary prevents DOM ownership conflicts. D3 data joins (enter/update/exit) enable smooth animated transitions.
- tiktoken WASM in the browser — no server round-trip for token counting. Lazy initialization defers encoder creation until first use.
- Raw fetch for Edge Functions — no Anthropic SDK, keeping the edge bundle lightweight and avoiding runtime compatibility issues.
- Word-level LCS diff — custom ~60-line implementation rather than a library dependency. Word-level diffs are more readable than character-level for natural language.
- Pure function extraction —
computeBudget()and export utilities are independently testable without mocking React or Zustand.
npm test # 56 unit/component tests (Vitest + React Testing Library)
npm run test:e2e # 10 E2E tests (Playwright)Unit tests cover: TokenizerService (encoding/switching), BudgetCalculator (budget math), budgetStore (state management), word-level diff algorithm, and export utilities.
Component tests cover: ModelSelector (rendering/interaction), SectionInput (typing/collapse/removal), SuggestionCard (accept/reject/edit flows).
E2E tests cover three critical paths: budget analysis (load example, type content, switch models, verify treemap), surgery flow (overflow detection, surgery panel activation), and export (clipboard copy, JSON download).
graph LR
A[User types in section] --> B[useTokenizer hook<br/>150ms debounce]
B --> C[TokenizerService<br/>tiktoken WASM]
C --> D[budgetStore<br/>Zustand]
D --> E[D3 Treemap<br/>animated transitions]
D --> F[Budget Bar Chart]
D --> G[Cost Estimator]
D --> H{Over budget?}
H -->|Yes| I[Surgery Mode]
I --> J[/api/surgery<br/>Edge Function/]
J --> K[Claude Sonnet 4]
K --> L[SuggestionCards<br/>accept/reject/edit]
L --> D
src/
├── components/
│ ├── Header/ # ModelSelector, BudgetSummaryBar, OutputReserveSlider, ExportMenu
│ ├── InputPanel/ # SectionHeader, SectionInput, InputPanel
│ ├── Visualization/ # TokenTreemap, BudgetBarChart, CostEstimator, OverflowWarning
│ ├── Surgery/ # DiffViewer, SuggestionCard, SurgeryPanel
│ └── shared/ # ToastContainer, KeyboardShortcutsHint
├── store/ # Zustand stores (budgetStore, surgeryStore, toastStore)
├── services/ # TokenizerService (singleton), BudgetCalculator (pure function)
├── hooks/ # useTokenizer (debounced tokenization)
├── utils/ # diff (word-level LCS), export (clipboard/JSON)
├── data/ # modelRegistry, defaultSections, examplePrompt
└── types/ # PromptSection, ModelConfig, SurgerySuggestion, etc.
api/
├── surgery.ts # Edge Function: Claude-powered prompt optimization
└── count-tokens.ts # Edge Function: Anthropic exact token counting
Data flow: User types → debounced tokenization (150ms) → Zustand store update → D3 visualizations re-render with animated transitions.
- Prompt template library with pre-built section layouts for common use cases
- Side-by-side model comparison view
- Token usage history and session tracking
- Shareable prompt configurations via URL
- Additional model support (Gemini, Llama, Mistral)