MentorX

MentorX — an AI tutor for your terminal. Created by Kartavya Gore.

A terminal-based AI tutor with a pedagogy engine: structured lesson plans, streamed and rendered teaching grounded in Wikipedia references, quizzes that interleave past-lesson retrieval practice, confidence calibration, Socratic reteaching that guides you to answers instead of revealing them, an FSRS spaced-repetition deck, model-graded open-ended questions with an eval harness, a final exam, and progress/streak tracking in SQLite.

First run

No config? mentorx starts a guided setup: pick a provider (OpenAI, OpenRouter, or Ollama), paste an API key, it verifies the connection live and writes your .env — then drops you straight at the prompt. It also checks npm once a day and hints when a newer version is out.

Install (shared package)

npm install -g mentorx
mentorx

Then create a .env file in the folder where you run it (see Setup below), or export the variables in your shell. Everything (progress, review deck, notes) is stored per-folder in tutor.db.

Requirements

• Node.js 22.18+ (Node 24 recommended — the app relies on native TypeScript file support and the built-in node:sqlite module)
• Any OpenAI-compatible chat-completions API: OpenAI, OpenRouter, LM Studio, Ollama, etc.

Setup (development)

git clone <this repo> && cd ai-tutor
npm install

Create a .env file next to package.json (or export the variables in your shell):

TUTOR_BASE_URL=https://api.openai.com/v1   # or https://openrouter.ai/api/v1, http://localhost:11434/v1 (Ollama), ...
TUTOR_MODEL=gpt-4o-mini                    # model name your provider expects
TUTOR_API_KEY=sk-...                       # any non-empty value for local servers
# TUTOR_GRADER_MODEL=gpt-4o-mini           # optional cheaper model for grading/validation calls
# TUTOR_DB_PATH=tutor.db                   # optional, defaults to ./tutor.db

The app refuses to start if the first three variables are missing.

Usage

npm start          # from a dev checkout
mentorx            # after a global install

| Command | What it does | | --- | --- | | /learn <topic> | Generates a lesson plan and starts the course. Options: --lessons 3-10, --level beginner\|intermediate\|advanced, --from <file\|url> to ground it in your material | | /book <file.pdf> | Scan a PDF book and learn it chapter by chapter: /next teaches the current chapter, then quizzes you on it before moving on | | /library add <file\|url> | Add material the tutor cites while teaching: pdf, epub, docx, md, txt, web page, YouTube video, or arXiv paper | | /library list · remove <id> · attach <id> | Manage the material library | | /source <n> | Show the library excerpt behind a [n] citation in the last answer | | /next | Teaches the current lesson; once taught, starts its quiz | | /quiz | Retake the current lesson's quiz (70% needed to pass) | | /focus [min] | Pomodoro study sprint (default 25 min) with automatic breaks; completed sprints count for your streak | | /lang [language] | Teach in your language — /lang hindi, /lang hinglish, /lang spanish, any name works; /lang clear resets to English | | /review | Spaced-repetition review session (FSRS scheduling, self-graded) — also resurfaces stale concepts with a fresh check | | /cram <min> | One-shot deadline-aware session over everything stale: weak cards, overdue checks, fading concepts — with an exam date set, post-exam reviews get pulled forward | | /plan [when\|clear] | Set your exam date ("in 3 weeks", "2026-11-05", "friday"); /plan shows the countdown, /plan clear unsets | | /anki [file] [--apkg] | Export the review deck as CSV, or a real Anki .apkg package | | /socratic | Guiding-question reteaching for your latest quiz miss — no answer reveals | | /exam | Final exam once every lesson is passed — one open-ended question per lesson | | /project [--code] | Applied project for a completed course, graded on a rubric. With --code: a coding project with model-generated hidden tests (see below) | | /oral [lesson\|all\|last] | Oral exam: spoken-style questions, 0-10 rubric grades, one follow-up probe per weak answer, report feeds concept mastery. /oral last reprints the most recent saved report | | /stats | Study streak, per-lesson accuracy, confidence calibration, review-deck stats | | /progress | Lists every course, per-lesson status, and review-deck stats | | /course <id> | Switch to another course | | /delete <id> | Delete a course and all its progress, answers, and cards | | /export | Save the course as markdown study notes (study-notes-course<id>.md) | | /save | Save the active course plan as JSON (course-<id>-plan.json) | | /load <file> | Import a course plan from a JSON file (no regeneration needed) | | /help | Show the command list | | /quit | Exit |

Free text (anything not starting with /) asks the tutor a question about the current lesson — with memory of the lesson so far, so follow-ups like "explain that again with an example" work. Quizzes accept the option number for multiple-choice; open-ended questions are graded by the model as correct / partial / incorrect with feedback. q aborts a quiz, exam, or review session.

Concept-level memory. Beyond per-card scheduling, every graded answer advances an FSRS schedule per concept (through the same mastery chokepoint — quiz, drill, marathon, daily, and cram flows all count once). /review and /daily resurface concepts whose schedule lapsed with a fresh check; /cram ranks everything stale by weakness × urgency and rehearses it in one sitting.

Your material, cited. Material added with /library add (or a /book import) is chunked and indexed locally (FTS5 full-text search with a plain-LIKE fallback). When the tutor teaches, answers free-text questions, or runs drills, it retrieves the most relevant excerpts of your material and cites them inline as [1], [2]… — /source 2 prints the exact excerpt behind a marker. Attached library sources take precedence over Wikipedia grounding.

Oral exams (/oral). The examiner asks 3-5 questions (whole course or one lesson), grades each answer 0-10 against an ideal answer, and — when the answer is weak — probes your weakest claim with one follow-up (max 2 per question); a clearly better follow-up raises the score to at most 8. The session report averages the per-question scores and feeds every concept you discussed into the mastery map, exactly like quiz answers. Every finished session is saved; /oral last replays the latest report with its per-question rows and flags the weakest answer worth revisiting.

Code projects (/project --code). The model designs a small project with hidden node:test tests; you paste your implementation, and it runs in a sandboxed child process — a fresh temp directory with a hard 10-second limit — while the hidden tests run against it. Your grade combines the hidden-test pass rate (60%) with a code review (40%). The sandbox is convenience isolation, not a security boundary: it prevents accidental mess (stray files, hangs) but does not contain malicious code, and it runs with your user's permissions — only ever submit code you wrote yourself.

Lecture-notes workspace (/notes). Type /notes <text> (or /notes paste for a multi-line dump) to attach lecture notes to the current lesson. Each note is saved, added to the searchable library (so /ask-ai and teaching can cite it with [n] markers), and instantly distilled by the LLM into 2-5 atomic flashcards that land in your spaced-repetition deck (/review studies them). /notes lists a lesson's notes; /notes del <n> removes one. Notes work in every course type — /learn, /book, and /course alike — so the more you watch and jot, the smarter the tutor's citations and the richer your deck get.

Exam-aware cramming (/plan + /cram). Set your exam date once (/plan in 3 weeks, /plan 2026-11-05, /plan friday — /plan clear unsets) and the countdown appears in the startup banner and /stats. From then on, /cram treats the date as a deadline: any item whose next spaced review would land after the exam is pulled forward into the session, so nothing important is seen for the first time after the exam. The header shows exactly how many items were pulled and why.

Paid-course companion (/course). Give it a Udemy/Coursera/any paid-course link (or a pasted/saved curriculum) and ai-tutor imports the public outline — sections and lecture titles — then builds the learning structure around it: each section gets a pre-watch primer (what to look for, how it connects), the section's quiz after you watch, missed- question reteaching, and spaced review. What it deliberately does NOT do: touch the paid videos themselves — ai-tutor is the study layer on top, not a scraper. When a platform blocks server-side fetching (Udemy usually does), the fastest path is printed: select the curriculum on the page, copy it, and either save it to outline.txt and run /course outline.txt, or run bare /course and paste it (finish the paste with a line containing only END). Section plans generate lazily — a 30-section course pays one plan generation per study session, never for sections you never open.

Ctrl-C cancels the current LLM call (lesson stream, grading, plan generation) without exiting; transient API errors (429/5xx/network) are retried automatically with backoff.

After each quiz the tutor automatically reteaches the concepts behind missed questions and schedules them as review cards. Key points are seeded as cards when a course starts and when each lesson is taught; /review resurfaces them on an SM-2-style schedule with 1-4 grading. The startup banner shows your streak and how many cards are due.

Progress persists in SQLite: quit at any point and the next run resumes the active (or most recent unfinished) course.

Development

npm test         # unit tests (node:test)
npm run typecheck
npm run eval     # grading eval harness — needs API access; fails below 80% soft accuracy

Command menu (autocomplete)

On an interactive terminal, typing / at the prompt opens a fuzzy-matched command menu: ↑/↓ move the selection, Enter submits the highlighted command, Tab fills it and keeps editing (arg commands get a trailing space), Esc sends the text as typed, Ctrl-C clears the line (or cancels the current prompt when empty). Scoring favors prefixes and consecutive characters; ties keep the documented command order. Non-TTY input (pipes, CI) keeps plain readline — the menu never engages.

To add a command to the menu, append it to COMMAND_ITEMS in src/autocomplete.ts (kept in the same order as /help).

Pedagogy notes

• Interleaving — each quiz mixes in ~30% questions from earlier lessons (preferring ones you missed), the single most proven retrieval-practice technique.
• Confidence calibration — every quiz answer is prefixed with your confidence (3|answer = certain); /stats reports over/underconfidence once you have ≥5 data points.
• Socratic reteaching — /socratic never reveals the answer; it asks up to 4 guiding questions so you derive it yourself.
• FSRS scheduling — the review deck uses an FSRS-4.5-style power-law scheduler (target retention 90%); legacy SM-2 card states migrate automatically.
• Grounding — lessons and Q&A fetch a Wikipedia summary of the topic and instruct the model to stay consistent with it (best-effort; falls back silently when offline).

Publishing / sharing

npm packages ship compiled JavaScript (Node refuses to type-strip TypeScript under node_modules), so publishing runs a build: prepack typechecks, compiles src/*.ts → dist/*.js (.ts imports rewritten to .js), and the files whitelist packs only bin/, dist/, and README.md — never .env, tutor.db, tests, or source.

npm run typecheck && npm test   # sanity before publishing
npm publish                     # first time; afterwards: npm version patch && npm publish

Your friend then runs:

npm install -g mentorx
mkdir my-course && cd my-course   # any folder; progress lives in ./tutor.db there
cd my-course
mentorx                           # prints exactly which env vars are missing

They need to set three variables (one-time) — in a .env file in the folder they run mentorx from, or exported in their shell:

TUTOR_BASE_URL=https://api.openai.com/v1
TUTOR_MODEL=gpt-4o-mini
TUTOR_API_KEY=sk-...

Notes:

• .env, tutor.db, tests, and dev config are excluded from the tarball by the files whitelist — npm's own files at ~/.npm are shared, nothing from the app leaks in.
• Version bumps: edit version in package.json (or npm version patch), then publish again; friends upgrade with npm update -g mentorx.
• Don't want to publish publicly? npm publish --access restricted requires a paid account; the zero-config alternative is npm pack and sending the resulting mentorx-0.1.0.tgz — your friend runs npm install -g ./mentorx-0.1.0.tgz.