Arkimedes — Agentic Desmos

An intelligent graphing calculator powered by Claude AI that transforms how you interact with mathematics. Using natural language, voice commands, or image analysis, Arkimedes helps you visualize, understand, and explore mathematical concepts through an autonomous agent with deep integration into the Desmos graphing engine.

More than a calculator — it's your personal math tutor. Every interaction is designed to teach concepts, build intuition, and deepen understanding, not just compute answers.

Architecture

• Frontend: Vite + React 19 + TypeScript + TailwindCSS 4 + Zustand
• Backend: C++20 HTTP server (cpp-httplib + nlohmann/json + OpenSSL)
• AI: Claude via Anthropic Messages API with tool use + extended thinking
• Graph Engine: Desmos Graphing Calculator API (CDN)

Why Arkimedes?

Traditional graphing calculators are powerful but intimidating. Arkimedes bridges the gap between computational power and educational accessibility by:

• Lowering the barrier to entry — natural language instead of cryptic syntax
• Building mathematical intuition — every response explains the "why", not just the "what"
• Encouraging exploration — AI-generated suggestions guide you toward deeper insights
• Providing immediate feedback — intelligent error messages turn mistakes into learning opportunities

Whether you're a student learning calculus, an educator creating demonstrations, or an enthusiast exploring mathematical beauty, Arkimedes meets you where you are.

Key Features

🎯 Socratic Graphing Partner

The AI doesn't just execute commands — it teaches. Ask "Graph y = sin(x²) + 5" and you'll get both the visualization AND an educational breakdown: what the +5 does (vertical shift), how x² inside sin creates accelerating oscillations, and suggested experiments to deepen your understanding.

⚡ Quick-Graph from Chat

Type mathematical expressions like y = x² or f(x) = cos(x) directly in chat and watch them appear instantly on the canvas — no sidebar needed. The AI follows up with contextual explanations to reinforce the concepts.

🧠 Graph-Aware AI Context

Every AI interaction automatically includes your current graph state (all expressions, viewport settings, colors, and labels). Ask "make the parabola wider" or "shift everything left by 2 units" and the agent knows exactly what you're referring to.

🔍 "What Changed?" Dynamic Diffing

Double-click any expression to edit it inline. When you modify it, an intelligent popover appears explaining the conceptual impact: "Increasing the coefficient from 2 to 4 made the line twice as steep" or "Adding 3 shifted the entire graph upward."

🛠️ Intelligent Error Recovery

Make a syntax mistake like y = sin(x (missing closing parenthesis)? Instead of cryptic error messages, you'll see a clear explanation of what went wrong, why the syntax matters, and get a one-click "Fix it" button with the corrected expression.

💡 Concept Explorer

Graph functions and watch contextual suggestion chips appear: "Find intersection points", "Explore the derivative", "Analyze symmetry". Click any chip to launch a guided AI exploration of that mathematical concept.

🔧 12 Powerful AI Tools

The autonomous agent has complete control over your graphing experience through 12 specialized tools: add/remove/update expressions, configure viewport and zoom, animate slider parameters, construct piecewise functions, run polynomial regressions, label key features, clear the canvas, capture screenshots, and read the complete graph state.

Backend Features

• True SSE Streaming: Real-time response streaming from Claude through the C++ backend to your browser using httplib's chunked content provider
• Rate Limiting: Intelligent 20 requests/minute per IP limit with sliding window algorithm to prevent abuse
• Structured Logging: Comprehensive request tracking with IDs, IP addresses, message counts, payload sizes, and performance metrics
• Resilient Retry Logic: Automatic exponential backoff for transient API failures (429, 529, 5xx errors) ensures reliable operation
• Model Configuration: Frontend control over model selection with support for extended thinking budgets for complex mathematical reasoning
• Context Management: Automatic conversation pruning with intelligent summary injection to maintain performance during extended sessions

Prerequisites

• Node.js 20+ and npm
• CMake 3.20+
• C++20 compiler (MSVC via Visual Studio on Windows, or GCC/Clang on Linux/macOS)
• OpenSSL development libraries
  • Windows: winget install ShiningLight.OpenSSL or install from https://slproweb.com/products/Win32OpenSSL.html
  • macOS: brew install openssl
  • Linux: sudo apt install libssl-dev (Ubuntu/Debian)
• Anthropic API key from https://console.anthropic.com

Setup

1. Install Frontend Dependencies

npm install

2. Configure API Key

Create a .env file in the project root with your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-your-key-here

Get your API key from the Anthropic Console.

3. Build the C++ Backend

# First-time configuration (downloads cpp-httplib and nlohmann/json via CMake FetchContent)
cmake -S server -B server/build

# Build the server in release mode
cmake --build server/build --config Release

Windows users: You can also open server/CMakeLists.txt directly in Visual Studio.

4. Start Both Servers

Open two separate terminal windows:

# Terminal 1: Start the C++ backend server (port 3001)
./server/build/arkimedes-server                    # Linux/macOS
.\server\build\Release\arkimedes-server.exe        # Windows

# Terminal 2: Start the Vite frontend dev server (port 5173)
npm run dev

Then open your browser to http://localhost:5173

Note: The frontend provides basic graphing functionality (expression input, keypad, visual editing) even without the backend. However, all AI chat features require the C++ server to be running.

Usage

Basic Graphing

• Direct expression input: Type equations in the sidebar expression list to graph them immediately
• Chat-based graphing: Type mathematical expressions like y = x², f(x) = tan(x), or r = 2sin(θ) directly in chat for instant visualization
• Inline editing: Double-click any expression in the sidebar to edit it on-the-fly

AI Interaction

Talk to the AI agent via the floating Command Center panel (top-right corner):

Natural Language Commands:

• "Plot y = sin(x) with a removable discontinuity at x = 0"
• "Create a parabola with vertex at (2, 3) and a root at x = 5"
• "Clear the graph and start with a fresh canvas"
• "Make the blue curve twice as steep"
• "Fit a quadratic regression to these data points: (1,2), (3,8), (5,18)"
• "Show me the tangent line to f(x) at x = 3"
• "Animate parameter 'a' from 0 to 10"

Multimodal Input:

• Voice input: Click the microphone button to dictate mathematical commands hands-free
• Vision analysis: Switch to the Vision tab and drag-and-drop an image of any graph — the AI will analyze it, identify key features, and recreate it on your canvas

Interactive Features

• Concept chips: After graphing functions, explore AI-generated suggestion chips that appear below the chat window
• Error assistance: Get instant help when you make syntax errors, complete with one-click fixes
• Clear chat: Reset the conversation history with the trash icon in the Command Center header

Tip: The AI remembers your entire graph state, so you can reference "the parabola", "the red line", or "that function" naturally in conversation.

Project Structure

arkimedes/
├── server/                          C++ backend (HTTP proxy to Anthropic API)
│   ├── CMakeLists.txt              Build configuration with dependency management
│   └── src/
│       ├── main.cpp                 SSE streaming server on port 3001 with rate limiting
│       ├── anthropic_client.h       HTTPS client with retry logic and exponential backoff
│       ├── system_prompt.h          Socratic Math Expert Module system prompt
│       └── tools.h                  12 tool definitions with JSON schemas
│
├── src/                             React 19 frontend application
│   ├── components/
│   │   ├── agent/                   AI interaction components
│   │   │   ├── CommandCenter.tsx    Main AI chat interface
│   │   │   ├── ChatPanel.tsx        Message display and streaming
│   │   │   ├── VoiceInput.tsx       Speech-to-text integration
│   │   │   ├── VisionInput.tsx      Image analysis interface
│   │   │   ├── ErrorSuggestion.tsx  Syntax error help with auto-fix
│   │   │   └── ConceptChips.tsx     AI-generated exploration suggestions
│   │   │
│   │   ├── calculator/              Graph visualization and controls
│   │   │   ├── DesmosCalculator.tsx Desmos API wrapper component
│   │   │   ├── ExpressionList.tsx   Interactive expression sidebar
│   │   │   ├── Keypad.tsx           Virtual mathematical keyboard
│   │   │   └── DiffPopover.tsx      Expression change explanations
│   │   │
│   │   ├── layout/                  App structure components
│   │   │   ├── TopBar.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── MainLayout.tsx
│   │   │
│   │   └── ui/                      Reusable UI primitives
│   │       ├── GlassPanel.tsx       Glassmorphism container
│   │       └── IconButton.tsx       Accessible icon buttons
│   │
│   ├── hooks/                       Custom React hooks
│   │   ├── useDesmos.ts             Desmos calculator state management
│   │   ├── useAgentChat.ts          AI conversation handling with SSE
│   │   └── useVoiceInput.ts         Web Speech API integration
│   │
│   ├── lib/                         Core utilities and business logic
│   │   ├── calculator-controller.ts Desmos API abstraction layer
│   │   ├── sse-parser.ts            Server-sent events stream parser
│   │   ├── diff-analyzer.ts         Expression change detection
│   │   ├── concept-detector.ts      Pattern recognition for suggestions
│   │   ├── markdown.ts              Lightweight markdown renderer
│   │   ├── math-detector.ts         Expression pattern matching
│   │   └── context-window.ts        Conversation history management
│   │
│   ├── stores/                      Zustand state management
│   │   ├── graph-store.ts           Graph state and expression tracking
│   │   ├── agent-store.ts           AI agent configuration
│   │   ├── chat-store.ts            Message history and streaming
│   │   └── desmos-store.ts          Global calculator instance
│   │
│   └── types/                       TypeScript type definitions
│       └── desmos.d.ts              Desmos API type declarations
│
├── index.html                       Entry point (loads Desmos CDN)
├── vite.config.ts                   Dev server config (proxies /api → :3001)
├── tailwind.config.js               TailwindCSS 4 configuration
├── package.json                     Node.js dependencies and scripts
└── .env                             Environment variables (API keys)

Technologies

Frontend Stack

• React 19 — Latest React with improved concurrent rendering
• TypeScript — Type safety and enhanced developer experience
• Vite — Lightning-fast build tool and dev server with HMR
• TailwindCSS 4 — Utility-first CSS with alpha features
• Zustand — Lightweight state management without boilerplate

Backend Stack

• C++20 — Modern C++ with concepts, ranges, and coroutines
• cpp-httplib — Single-header HTTP/HTTPS server library
• nlohmann/json — Intuitive JSON parsing and serialization
• OpenSSL — Secure HTTPS communication with Anthropic API

AI Integration

• Claude 3.5 Sonnet — State-of-the-art language model with tool use
• Extended Thinking — Deep reasoning mode for complex mathematics
• Tool Use — 12 specialized functions for graph manipulation
• SSE Streaming — Real-time token-by-token response delivery

Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, improving documentation, or enhancing the educational prompts, your help makes Arkimedes better for everyone.

Development Guidelines

1. Fork the repository and create a feature branch
2. Follow existing code style and TypeScript conventions
3. Test thoroughly — both frontend UI and backend integration
4. Update documentation for any new features or changes
5. Submit a pull request with a clear description

License

This project is open source and available under the MIT License.

Acknowledgments

• Desmos — For their incredible graphing calculator API
• Anthropic — For Claude and the powerful tool use capabilities
• cpp-httplib — For making HTTP servers in C++ delightfully simple