Project Info
Inspiration
The idea for KlarifAi came from a problem we experienced ourselves while studying for standardized exams like the SAT. We frequently used ChatGPT to help solve math problems, but we found ourselves spending a lot of time manually describing equations, diagrams, graphs, and problem statements. For visual questions in particular, explaining the context accurately was often more work than solving the problem itself. We started asking a simple question: why should students have to translate what they see into text for an AI to understand it? What if an AI could see the problem directly and explain it the same way a tutor sitting next to you would? That question became the foundation for KlarifAi.
What it does
KlarifAi is a desktop AI assistant that analyzes what's on your screen and provides visual, step-by-step explanations for math problems in real time. Instead of copying and pasting questions or manually describing diagrams, users can simply have the problem visible on their screen. KlarifAi identifies the relevant mathematical content, understands the context, and generates guided explanations that break the solution into manageable steps. The goal is not just to provide answers, but to help students understand the reasoning behind them through visual and interactive guidance.
How we built it
At the core of KlarifAi is a multi-step AI workflow designed to replicate how a human tutor approaches a problem. First, the system captures and analyzes the user's screen, identifying the relevant mathematical content and surrounding context. That information is stored and managed through a memory layer that preserves important details throughout the interaction. Next, KlarifAi classifies the user's intent—whether they need a full solution, a hint, conceptual clarification, or a step-by-step walkthrough. Based on that intent, the system performs targeted research and gathers additional context that may help explain the underlying concepts. Finally, all of this information—the screen analysis, conversation memory, user intent, research results, and visual context—is combined into a single reasoning request. The final AI call synthesizes everything into a structured explanation that is then rendered visually on screen for the user. Rather than relying on a single prompt, KlarifAi uses an orchestrated pipeline that separates observation, memory management, research, reasoning, and presentation into a unified workflow.
Challenges we ran into
One of our biggest challenges was reliably understanding complex mathematical content from screenshots. SAT-style problems often include graphs, geometric diagrams, tables, and formatting that can be difficult for AI systems to interpret correctly. Another challenge was balancing accuracy with usability. We wanted explanations that were detailed enough to teach concepts without overwhelming students with unnecessary information. We also spent significant time optimizing the user experience so that assistance felt immediate and seamless rather than requiring multiple manual steps.
Accomplishments we're proud of
We're proud that we transformed a frustration we personally experienced into a working product that feels natural to use. Instead of forcing students to rewrite questions for an AI, KlarifAi allows them to get help directly from what they already have on screen. We're especially proud of the quality of the visual step-by-step explanations and how quickly users can move from confusion to understanding. Most importantly, we built a tool that focuses on learning and comprehension rather than simply generating answers.
What we learned
Building KlarifAi taught us that the biggest barriers to learning are often not the concepts themselves, but the friction involved in accessing help. We learned how important visual context is for educational AI applications and how much information can be lost when students are forced to convert diagrams and equations into plain text. On the technical side, we gained experience integrating computer vision, multimodal AI systems, desktop application development, and user-centered design into a single product.
What's next
Our vision is to expand KlarifAi into a universal learning companion that can assist students across a wide range of subjects, not just mathematics. Future plans include: Support for science, physics, and engineering problems. More interactive visual explanations and tutoring experiences. Personalized learning paths based on student strengths and weaknesses. Improved real-time screen understanding and context awareness. Collaboration features for study groups and classrooms. Ultimately, we want KlarifAi to make high-quality, personalized tutoring accessible to anyone with a computer, turning every screen into an opportunity to learn.
🎓 ScreenTutor AI
A cursor-native AI tutor that lives near your cursor, captures the screen on demand, and draws overlays directly on top of your windows.
What It Does
- Cursor-Native Buddy: Buddy lives near your cursor, follows you around in a compact bubble state, and expands to a full chat panel on request. When explaining concepts, Buddy smoothly animates (flies) to coordinates on your screen to point at items.
- Captures Screen on Demand: Trigger screen capture explicitly using
Ctrl+Shift+Eor the floating microphone button. Never records in the background or polls your screen silently. - Draws Overlays on Top of Apps: Draws circles, arrows, highlighters, step badges, and text labels directly on a transparent SVG window layered over your active screen content.
- Remembers Weak Concepts: Uses Redis (or in-memory fallback) to log weak concepts, track question patterns, and adapt explanation styles dynamically.
- Speech Interactivity: Push-to-talk microphone input records audio chunk sessions safely. Text-to-speech engine speaks answers out loud while stripping coordinate tags.
Quick Start
Prerequisites
- Node.js 20+
- pnpm 9+
- Docker (optional — only needed for Redis container)
Install & Run
# 1. Clone the repository
git clone <repo-url>
cd 2nd_brain
# 2. Install dependencies
pnpm install
# 3. Create env file
cp .env.example .env
# 4. Start Redis (optional — falls back to in-memory)
docker compose up -d redis
# 5. Start development environment (orchestrator + desktop concurrently)
powershell -ExecutionPolicy Bypass -Command "pnpm dev"
Configuration & Setup
ScreenTutor AI works out of the box in Mock Mode using local templates for lessons. To configure real integrations, set the following environment variables in .env:
1. Mock Mode (Default)
Runs entirely locally without external API connections or paid accounts.
AI_PROVIDER=mock
MEMORY_ENABLED=true
2. Redis Memory
To persist profile records, weak concepts, and user sessions across app restarts.
REDIS_URL=redis://localhost:6379
MEMORY_ENABLED=true
Note: If Redis is unavailable or fails to connect, the orchestrator automatically logs a warning and falls back to InMemoryService in RAM.
3. Claude (Anthropic AI)
For real-time multi-modal screen capture analysis and chat responses.
AI_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-your-key-here
CLAUDE_MODEL=claude-3-5-sonnet-20241022
4. Browserbase (Research Mode)
Allows the tutor to spawn headless browser sessions to search Wikipedia/web resources for tutoring material.
BROWSERBASE_ENABLED=true
BROWSERBASE_API_KEY=your-api-key
BROWSERBASE_PROJECT_ID=your-project-id
5. Simular (Co-drive Actions)
Proposes desktop actions (clicks, keypresses) that the user can review and approve.
SIMULAR_ENABLED=true
SIMULAR_API_KEY=your-simular-key
ENABLE_SAFE_ACTIONS=true
6. Fetch AI / Agentverse (Specialist Agent Routing)
Registers and routes tutoring tasks to local or remote Fetch-compatible agents.
FETCH_AGENTVERSE_ENABLED=true
FETCH_AGENTVERSE_API_KEY=your-agentverse-key
FETCH_AGENTVERSE_AGENT_ADDRESS=agent-address-here
7. Arize / Phoenix (Observability Tracing)
Tracks telemetry spans, latency metrics, and LLM evaluations.
ARIZE_ENABLED=true
ARIZE_API_KEY=your-arize-key
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces
8. Sentry (Error Tracking)
Captures backend runtime errors and desktop crashes.
SENTRY_ENABLED=true
SENTRY_DSN=https://your-dsn-key@o0.ingest.sentry.io/0
Privacy Model & Redaction
- On-Demand Capture Only: Captures the screen only when the hotkey is triggered. No background polling or recordings.
- Sensitive Window Denylist: Analysis is immediately blocked if any of the 16 sensitive window title terms (e.g.
password,keychain,bank,email,stripe) are active. - Data Redaction Layer: A shared
RedactionServiceautomatically strips passwords, API keys, emails, credit cards, and query parameters from all logs, Sentry events, Arize telemetry, and UI debug views. - Developer Redaction Override: Available as a toggle in the developer panel, allowing developers to see raw data for debugging. It is turned off by default.
- No Screenshot Storage: Screenshots are processed in memory and never written to disk or sent to observability endpoints. Only a secure MD5 hash is stored.
Bundled Demo Lessons
ScreenTutor includes six bundled offline lessons accessible by clicking the Graduate Cap (🎓) icon in the header:
- Algebra: distributive property
- Algebra: common mistake
- Calculus: chain rule
- Calculus: u-substitution
- Graph interpretation: vertex/slope
- Coding error: off-by-one IndexError
Selecting a lesson displays a static lesson preview and allows you to test the hotkey, drawing overlays, and voice synthesis without external network calls.
Troubleshooting
Error: connect ECONNREFUSED 127.0.0.1:6379
- Cause: Redis container is not running.
- Fix: Redis is completely optional. The app falls back to memory storage. To enable Redis, start the container:
docker compose up -d redis.
Hotkey Ctrl+Shift+E Not Working
- macOS: Ensure Electron has Accessibility permissions granted in System Preferences → Privacy & Security → Accessibility.
- Windows: Run as Administrator if hotkeys are intercepted by other fullscreen windows.
Screen Capture Black / Empty
- macOS: Ensure Electron has Screen Recording permissions granted in System Preferences → Privacy & Security → Screen Recording.
listen EADDRINUSE :::4317
- Cause: Port 4317 is already in use by another process.
- Fix: Change
ORCHESTRATOR_PORTin your.envfile to a free port.
Analysis
View
Metric
- 4
- 3
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- AnthropicIn code
- CSSIn code
- HTMLIn code
- JavaScriptIn code
- ReactIn code
- TypeScriptIn code
- RedisClaimed
6 of 7 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- CursorCommits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
709 KB
Source files
147
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
DMgaming00/ScreenTutor_AI
162 files · 764 KB · @ 44b3468
Structure
Interface
31 files · 19%Screens, components and styles rendered to the user.
API & routing
10 files · 6%Request entry points: routes, handlers and controllers.
Application logic
69 files · 43%Domain rules, services and shared utilities.
Data & schema
5 files · 3%Schema definitions, migrations and data access.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- TypeScript67%
- YAML14%
- Markdown11%
- CSS8%
- HTML1%
- JavaScript0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
apps/desktop/package.json
npm · 14- @screentutor/shared
- @sentry/node
- @sentry/react
- koffi
- react
- react-dom
- +8 more
services/orchestrator/package.json
npm · 13- @anthropic-ai/sdk
- @fastify/cors
- @screentutor/shared
- @sentry/node
- dotenv
- fastify
- ioredis
- uuid
- +5 more
package.json
npm · 33 development-only dependencies.
packages/shared/package.json
npm · 2- zod
- +1 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.