Supermentor

supermentor

supermentor is a local teaching toolkit for coding agents. It provides portable teaching skills, client install helpers, and an optional Pi browser companion for longer lessons, code walkthroughs, exercises, and inline questions.

The primary interface is skill-based mentoring in the agent chat. Slash commands and browser support are available only when the client integration provides them.

What it includes

• Teaching skills for guided learning, code dissection, codebase tours, and setup support.
• Local install helpers for Pi, OpenCode, Claude Code, and Codex.
• A Pi extension with supermentor_start plus /supermentor-start, /supermentor-status, and /supermentor-stop.
• A local HTTP server and file-based protocol for browser lessons and inline comments.
• Adapter helpers for harness integrations.

Browser side-thread support requires a tested harness bridge. Pi supports the browser companion today. OpenCode, Claude Code, and Codex can use the local skills, but their browser companion bridges are not supported yet.

Local installation

Install Supermentor separately for each agent client:

git clone https://github.com/bnema/supermentor ~/.local/share/supermentor
cd ~/.local/share/supermentor
node scripts/install-local.mjs pi

Supported install targets:

node scripts/install-local.mjs pi
node scripts/install-local.mjs opencode
node scripts/install-local.mjs claude
node scripts/install-local.mjs codex

Use your development checkout instead of ~/.local/share/supermentor when working on Supermentor itself. Use --copy if symlinks are inconvenient:

node scripts/install-local.mjs codex --copy

Client support

Client	Local support	Browser companion	Install details
Pi	Skills + extension commands	Supported	install/pi.md
OpenCode	Skills + bootstrap plugin	Not supported yet	install/opencode.md
Claude Code	Skills-directory plugin	Not supported yet	install/claude-code.md
Codex	Local skills	Not supported yet	install/codex.md

Learning methods

Supermentor adapts lessons to the learner's goal, current level, workspace context, and preferred amount of agent help. When the request needs clarification, the agent asks focused calibration questions before planning the lesson.

Context	Typical use
Blank repo or scratch folder	Guided course, tiny lab, or project slice.
Project idea	Small build with learner-owned implementation choices.
Existing or public codebase	Repository map, reading path, and focused flow dissection.
Selected code or named file	Purpose, behavior chunks, example traces, and micro-exercises.
Error, log, or failing test	Diagnosis lesson based on evidence.
Concept-only question	Explanation with examples, checks for understanding, and recall prompts.

Methods include exercises, guided projects, worked examples, code dissection, codebase tours, debugging lessons, drills, predictions, and recaps.

A common teaching loop is:

Orient -> predict -> explain -> modify or trace -> practice -> recap

For exercise-based learning, the learner writes code in their IDE or current codebase. The agent frames the task, gives constraints and success criteria, offers hints, reviews attempts, and corrects misconceptions. Full solutions are reserved for explicit requests or real blockage after an attempt.

Pedagogical basis

Supermentor uses common evidence-backed teaching techniques:

• Retrieval practice: ask the learner to recall, predict, or explain before showing the answer.
• Spaced practice: mark concepts worth revisiting later.
• Interleaving: vary related problem types after the first pattern is stable.
• Worked examples and fading: move from complete examples to partial examples to learner attempts.
• Example-based code reading: use traces, tests, fixtures, and small changes to connect code to behavior.
• Metacognition: ask the learner to notice why an answer felt plausible.

References: