Penmentor AI Math Mentor: Real-Time Feedback for Handwritten Work

Penmentor: An AI Mentor for Handwritten Mathematics

Penmentor is a specialized AI tool designed to function as a math mentor, providing detailed, teacher-like feedback on handwritten mathematical work. By integrating with handwriting applications, the tool allows users to receive immediate guidance, error correction, and conceptual visualizations while working by hand.

Core Functionality and User Experience

Penmentor operates by allowing users to press a key while working in a handwriting application, such as Xournal++. This action triggers the AI to analyze the handwritten mathematical slip and mark it directly onto the page. The system supports several key functions:

  • Guided Feedback: The AI marks the work with colored pens, circling mistakes and ticking correct lines, mimicking a teacher's review.
  • Conceptual Animation: Users can box specific mathematical concepts to generate an interactive animation, similar to those produced by 3Blue1Brown, using the Manim library.
  • Whole Page Awareness: The tool utilizes an Xournal++ plugin to share the entire page content with the AI, ensuring context is maintained beyond the currently visible screen area.

Pedagogical Approach: Learning Through Scaffolding

Penmentor is designed not merely to provide answers, but to facilitate deep learning by guiding the user through the problem-solving process. The system employs several pedagogical techniques:

  • Hints Over Answers: The feedback mechanism provides a progressive ladder of support, ranging from a simple nudge to naming the required technique, ensuring the user performs the critical thinking necessary for the knowledge to stick.
  • Detailed Error Tracking: The system provides specific feedback on mistakes, such as circling the exact point of error, ticking correct steps, and underlining later lines that inherit the initial mistake.
  • Practice Drills: Penmentor supports various practice modes, including find-the-error drills and questions that require the user to identify the appropriate mathematical technique.

Technical Architecture and LLM Integration

Penmentor is built to run on existing AI command-line agents, allowing users to leverage their current subscriptions and preferred models. The tool acts as an interface that routes the handwritten input to the selected agent for processing.

The system supports three primary agent prefixes:

Prefix Agent Example Models
claude: Claude Code claude:opus, claude:sonnet, claude:haiku
codex: Codex codex:gpt-5.6-terra
agy: Antigravity CLI agy:gemini-4-argon-medium, agy:gemini-3.8-flash-medium

Users select the desired agent via the settings menu. The underlying mechanism is detailed in the project guide, which explains how the tool interacts with the chosen AI agent and what data is shared with the model.

Installation and System Requirements

Penmentor requires a specific environment to function correctly. It is designed for Linux on X11, with the i3 window manager being recommended for optimal performance.

Prerequisites

To run Penmentor, the following components are required:

  • Linux operating system running X11.
  • An installed AI agent (Claude Code, Codex, or Antigravity CLI).
  • Required dependencies: rofi, slop, xdotool, and PyQt6.

Quick Start

The initial setup involves cloning the repository and running a self-test:

git clone https://github.com/AbdullahAlhariri/penmentor ~/src/penmentor
~/src/penmentor/bin/penmentor --selftest

After setup, the bin/penmentor executable must be bound to a specific key within the user's window manager configuration (e.g., in an i3 configuration file).

Licensing

Penmentor is released under the MIT license.

Sources