🖋️ Penmentor: An AI Math Tutor for Your Handwritten Work

Penmentor is an innovative AI-driven mentor designed to read and critique your mathematical handwriting in real-time. Instead of providing raw answers, it acts like a human teacher, marking up your digital page with colored pens and guiding you toward the solution.

---

🛠️ The Workflow

The system transforms the traditional study loop into a seamless interactive experience:

Core Experience

1. Input: Write your equations in xournal++.
2. Trigger: Hit a single key.
3. Feedback: The AI marks the slip directly on your page.
4. Visualization: Box an integral $\int_{a}^{b} f(x) \, dx$ to generate a 3Blue1Brown-style interactive animation.

---

🎯 Why Penmentor?

The creator developed this tool to solve a specific friction point in studying calculus.

"I used to spend my time screenshotting my work and uploading it to Claude, only to receive long, text-heavy explanations. I wanted a mentor looking over my shoulder—someone to circle a mistake, tick a correct step, and nudge me forward."

The "Learning Ladder"

Penmentor avoids giving away the answer immediately. Instead, it provides a graduated series of hints:

• Level 1: A subtle nudge.
• Level 2: Naming the required mathematical technique.
• Level 3: A "ghost" image of the next line to guide your pen.

This ensures you do the cognitive heavy lifting, which is essential for the material to stick.

---

✨ Key Features

• Visual Corrections:
  • 🔴 Circles around the first point of failure.
  • ✅ Ticks for logically sound lines.
  • 〰️ Underlines for subsequent lines that inherit a previous error.
• Active Learning:
  • Interactive drills like "find-the-error."
  • Questions regarding your specific steps (respond via typing or writing).
  • Technique-matching challenges.
• Dynamic Visuals: Integration with manim allows you to manipulate variables or drag bounds to see how $\sum_{i=1}^{n} f(x_i^*)\Delta x$ (Riemann sums) behave.
• Full-Page Context: A dedicated xournal++ plugin ensures the AI sees the entire page, not just the current viewport.

---

⚙️ Technical Integration

Penmentor leverages the AI command-line agents you already use. You can configure which model handles the mentoring via the Settings menu using specific prefixes.

Agent Configuration Table

---

🚀 Quick Start Guide

Prerequisites

• Linux environment running X11 (Optimized for i3 window manager).
• An active subscription/login for claude, codex, or agy.
• Installed dependencies: rofi, slop, xdotool, and PyQt6.

Installation

Run the following commands in your terminal:

# Clone the repository
git clone https://github.com/AbdullahAlhariri/penmentor ~/src/penmentor

# Navigate to the directory
cd ~/src/penmentor

# Run the self-test to verify installation
~/src/penmentor/bin/penmentor --selftest

License: This project is released under the MIT License.