Baiqiao Zhang is a PhD student in Computer Science and Engineering at HKUST, advised by Prof. Xiaojuan Ma, working on human-AI alignment between developers and AI coding agents.
moodle-driver is a Node.js library, and a moodle command, that works a Moodle site the way a person does: it lists their courses, reads content, submits assignments and answers quizzes as a student, and builds courses, grades with rubrics, runs forums and the gradebook as a teacher. It drives a real browser logged in as that person, calling the same AJAX services and filling the same forms Moodle's own pages use, so it works on any Moodle 4.x or 5.x site with no web service tokens, no administrator and no plugin. Results are plain typed data, and every function declares the kind of data it touches.
✨ Why moodle-driver
🔑 The person's own login. They log in once in a window (SSO and two-factor included); the driver never sees a password.
🧩 No web services. Many campuses don't enable them. The driver uses the same pages and AJAX services Moodle's own screens use: the services over plain HTTP with the person's session, the browser to log in, fill forms and read pages.
🔐 Moodle decides. It can do what the person can do, and nothing more: every permission is Moodle's.
🌍 Any language. Pages are read by structure (ids, data attributes, field names), never by their text.
🐢 At a person's pace when acting as a student, so Moodle's logs and completion look like a person's; or fast when time matters.
🛡️ Safe to hand to an agent. Every function declares the data it touches (own, course content, others' work, communication…), so a program can allow only some.
📦 Plain data, typed. JSON results, ISO dates, long lists a page at a time, errors with stable codes, TypeScript types included.
🖥️ A library and a command. The same operations from your code or from a terminal.
🚀 Quick start
You need Node.js 20+, a Moodle 4.x or 5.x site, and Edge or Chrome (or let it download Chromium, or Playwright's Firefox if you choose it). Add it to your project:
import { createMoodle } from "@falkenslab/moodle-driver";
await using moodle = createMoodle({ site: "https://campus.example.org/", profileDir: "/home/ada/.moodle-profile", headless: true, downloadBrowser: true });
await moodle.logIn(); // 🔑 the first time a window opens and the person logs in; afterwards, nothing
for (const course of await moodle.listCourses()) {
const { pending } = await moodle.pendingActivities(course.id);
console.log(`📚 ${course.fullname}: ${pending.length} things to do`);
}
That's it: no API keys, nothing to ask the administrator. The browser closes by itself at the end of the block. Step by step in installation and your first program.
Every method is also a command of moodle, which comes with the package:
Tables at a terminal, JSON for scripts, errors with their code and an exit status. moodle help lists every command, generated from the API so none is missing; --allow own,course-content refuses anything touching other people's data. moodle shell --show keeps one browser open while you type commands, to watch each act, and moodle open --show leaves one open for separate commands from any terminal (reachable only with a token of yours) until moodle close. See the command line.
🧪 A taste of the code
🧑🎓 A student's week, deadlines first:
for (const d of await moodle.deadlines({ days: 7 })) {
console.log(`${d.date.slice(0, 10)} ${d.activity}${d.overdue ? " ⚠️ overdue" : ""}`);
}
👩🏫 A teacher grading what's waiting, with feedback the student gets notified of:
for (const s of await moodle.assignmentSubmissions(35)) {
if (s.needsGrading) await moodle.gradeSubmission(35, s.userId, { grade: 8.5, feedback: "<p>Great work!</p>", notify: true });
}
🏗️ Building a course: every write tells you what it did:
🤝 Sharing a unit with another teacher, anonymous, restored on their site where they want it:
const { file } = await moodle.backupCourse(3, "/home/ada/catalog", { sections: [12], activities: [57] }); // no names, no origin
const { activities } = await moodle.backupContents(file.path); // what it holds, read locally
await colleague.restoreCourse(file.path, { into: 8, afterSectionId: 30 }); // as new sections after section 30
📸 See it at work
A real session: the moodle command, logged in as a teacher of a Moodle 5.2 site, lists a course's participants and groups and reads a quiz, each in one line.
Complete programs for real tasks, commented, are in the examples.
🧰 What's inside
Area
For example
📚 Courses and content
Course structure and updates, pages, books, files and folders, H5P and SCORM content
🏗️ Building courses
Sections and activities of any type, settings, restrictions and completion, the course page's blocks, images embedded in rich text, databases' fields, templates and entries, external tools (LTI)
📝 Assignments and grading
Submissions, rubrics and marking guides, the marking workflow, extensions, feedback files
❓ Quizzes and questions
Attempts, results, statistics, manual grading, quiz layout and overrides, question banks with GIFT and Moodle XML import and export, their categories, the question types a site offers
📊 Gradebook and reports
The grader report, grade items and categories, exports, completion, badges and competencies, activity and participation reports, logs
👥 Participants and groups
Enrolments and their methods, roles, groups and groupings, notes about participants
💬 Forums and messages
Discussions, replies, ratings and subscriptions, workshops, glossary entries and their approval, wiki pages and their history, notifications and conversations
📅 Calendar and to-dos
Events, deadlines, what's pending and what changed, BigBlueButton meetings and their recordings
🔄 Course life cycle
Copies, resets, imports, backups and restores, whole or in part, anonymous for sharing
🧩 For your program
Typed results and errors, data categories, the session's low-level pieces, a fake Moodle for tests
npm install
npm run typecheck && npm run lint
npm run test:docker # the tests open browsers: always in Docker, never on the desktop
npm run test:sandbox # every function against a real Moodle (the sandbox), on demand (it takes hours)
npm run build # dist/, with declarations
npm run docs:check # every example in the docs compiles against the code
More in development; the design lives in .minispec/ (start with core/project.md and the decisions). Extracted from moodle-mcp, its first consumer.
