Mentat | @usulpro/mentat

A system that deploys and scaffolds an AI led course into a local directory on your machine, then teaches it to you there.

It is domain-agnostic: nothing in it knows what is being taught until you tell it. The course is generated at onboarding, from a conversation about your background, the subject you want, and what you actually want out of it — and it is built around you specifically, not around the subject in the abstract. Explanations start from what you already know: onboarding records your prior experience per topic, and the teacher uses it to reach for a short analogy to something familiar rather than teaching everything from zero.

The course leads with practice. From early on you get real tasks to do by hand — write the code, run the experiment — with theory delivered where it is needed to do the task, not as a separate track to sit through first. It is not static: the teacher watches how a task goes, what came easily, what needed help, and adjusts what comes next rather than following a fixed lesson plan.

Practical skill is not left to fade after one exposure, the way a book or a classical course leaves it. Every task deliberately combines something new with one or two things you're still short on or overdue to revisit — the course's whole interleaving mechanism — so a skill keeps recurring, at rising difficulty, until it is solid rather than merely seen once. Periodically the course steps back to check what has actually stuck and whether it is time to move on.

Quick start

npx @usulpro/mentat --target ./my-course --platform claude-code

cd my-course

Then, in your agent CLI: /onboarding

Once onboarding is done: /teacher

The roles

Two role skills run inside a course, installed into the agent CLI you already use:

• teacher — runs a teaching session: reports where things stand, and dynamically authors the next task from your progress rather than pulling it from a fixed sequence. It stays out of the way while you work, and closes tasks through review.
• deputy — owns the curriculum. It runs onboarding, cuts the course into tracks — separate sub-areas or layers of the subject you can move between — and authors the ledger of competencies each track has to cover. Tracks are the one static part of the plan; the tasks that fill them are not. Some topics stay locked until you have the prerequisites for them, which the deputy also decides.

A third skill, director, owns the harness itself — the scripts a course runs on — and is a stub in this version.

The record on disk is the only memory that survives between sessions, which is what makes a course something you can put down for a month and pick up again.

This is version 1.0.0. It installs, onboards, and teaches; the director role is a stub.

Requirements

• Node.js 18 or newer
• One of: Claude Code or Codex

Install

mentat is not on the npm registry yet. Install it from a clone:

git clone https://github.com/usulpro/mentat.git
cd mentat
npm run deploy -- --target ../my-course --platform claude-code

Use --platform codex for Codex. The platform is never inferred — the installer refuses to guess, because a course is built differently for each.

Add --dry-run to see exactly what would be written and change nothing:

npm run deploy -- --target ../my-course --platform claude-code --dry-run

The installer writes nothing outside the target directory. It merges into an existing hook configuration rather than replacing it, and it never overwrites a course record that already exists.

Once the package is published, the same install becomes a single command with no clone:

npx @usulpro/mentat --target ./my-course --platform claude-code

First run

Start your agent CLI in the course directory — the path you gave the installer as --target, ../my-course in the example above — and invoke /onboarding in the session.

Not from the clone, and not from a parent directory: the skills and the hook configuration are installed in the course, and a session started elsewhere does not see them.

Onboarding is a conversation, not a form. It establishes what is being taught, what the learner already knows, what "done" looks like, the language they want to be addressed in, and the track cut — then authors the ledger those tracks are measured against. It ends with a course you can teach from.

After that, /teacher runs a session and /deputy changes the plan.

The course and the workspace

A course is two directories, and knowing which is which saves confusion later.

The course is the durable record. It holds .course/ — the ledger, the journal, the learner profile, the configuration — plus the installed skills and harness. It is what survives.

The workspace is the learner's code: one directory per track, with numbered entries inside it. It is theirs to reorganise or throw away, and nothing in the record depends on its contents.

The workspace is created during onboarding, not by the installer — a freshly installed course does not have one yet, and that is expected. By default it lands at workspace/ inside the course, so a course is one directory to back up or delete. Pass --workspace <path> to scaffold.mjs during onboarding to put it somewhere else.

They are separate because the record has to outlive the code. Deleting a half-finished experiment should not delete the evidence that you learned something from it.

One caveat worth knowing: the workspace path is recorded as an absolute path, so renaming or relocating a course directory breaks the link. It fails clearly rather than silently — the harness reports the work directory as missing — and it is fixed by correcting workspace in .course/config.json.

Upgrading a course

Re-run the installer over the same directory:

npm run deploy -- --target ../my-course --platform claude-code

Code is refreshed. The course record — ledger, journal, learner profile, and the configuration values onboarding set — is left as it was, and so is the workspace. The installer reports how many files it wrote and how many it kept.

Platform notes

Both platforms require hooks to be reviewed and trusted before they run. mentat uses a per-turn hook to hold the teaching mode's contract; until the hook is trusted it never fires, and it fails silently rather than loudly. If sessions seem to lose their footing, check the hook trust state in your CLI first.

Codex reads no project-local configuration. A course is therefore a relocated Codex home, and the installer writes a course.sh launcher that sets CODEX_HOME to the course before starting Codex. Start Codex sessions through that launcher, or the course does not exist as far as Codex is concerned.

Two consequences follow from that, and the installer prints both after a Codex install:

• A relocated home has no login of its own. The installer links your existing Codex credentials into the course so a session does not fail on the first request. Run codex login inside the course instead if you want it authenticated separately.
• A session started through the launcher uses the course as its whole Codex home, so your global Codex skills, plugins, history and sessions are not visible inside it.

Read the notes the installer prints. They are the accurate ones for the install that just ran.

Developing mentat

git clone https://github.com/usulpro/mentat.git
cd mentat
npm test

Courses are never installed inside this repository — an agent started here picks up this directory's own hook and skill configuration, which contaminates exactly the runs that are meant to distinguish an installed course from a bare one. The installer refuses a target inside the repository for that reason.

Probes and manual verification run in a disposable directory outside the working tree, whose path comes from dev.local.json; see dev.local.example.json for the shape.

CLAUDE.md at the root holds the rest of the development conventions.

License

MIT. See LICENSE.