main e590907

Adaptive mentorship skills and a local browser companion that help coding agents teach humans

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:

Pi browser companion

After installing in Pi, the agent can start the browser companion with supermentor_start when a lesson would benefit from a side guide. You can also start it manually in a Pi session:

/supermentor-start Learning session
/supermentor-status
/supermentor-stop

Use the browser companion for long teaching walkthroughs, code anchors, inline comments, and longer exercise paths. It displays learning material and side-thread questions; it is not a coding environment, generic design canvas, or product-brainstorming surface. Learners still write code in their IDE or current codebase. A running browser session is updated by rewriting lesson.json; it does not need to be restarted for each exercise.

For short explanations, or in clients without a supported browser bridge, use chat. In Pi, prefer the integrated tool or command over launching server.cjs manually. Manual server startup displays lessons but cannot route inline browser questions back into the active agent session.

Session storage

supermentor does not write session state into the current project by default. Sessions live under the platform cache directory:

SUPERMENTOR_CACHE_DIR/sessions/<sessionId>/          # explicit override
$XDG_CACHE_HOME/supermentor/sessions/<sessionId>/    # Linux/Unix when set
~/.cache/supermentor/sessions/<sessionId>/           # Linux/Unix fallback
~/Library/Caches/supermentor/sessions/<sessionId>/   # macOS fallback
%LOCALAPPDATA%\supermentor\sessions\<sessionId>      # Windows fallback

A session contains:

session.json          # manifest: id, cwd, title
server.json           # current server URL/token when running
lesson.json           # adaptive learning document
threads/<threadId>/
  question.json       # browser question/action written by the server
  reply.json          # agent answer written by the coding agent
events.jsonl          # append-only operational events

Exercise documents keep JSON minimal. Supermentor infers default English action labels such as "I'm struggling" and "Review my attempt". Lesson authors should describe tasks, constraints, references, and success criteria instead of hardcoding UI labels. Reviewing an attempt is the completion checkpoint for a step. Existing inline comments and answers should be preserved when a lesson is updated.

Browser protocol

The browser companion uses a file-based side-thread protocol. The server writes question.json, emits an inline-question or agent-action event, waits for the harness adapter to acknowledge delivery, and then polls for the agent's reply.json.

A harness adapter that wants browser support must:

  1. read server-started, inline-question, and agent-action JSON events from stdout;
  2. inject browser questions/actions into the active agent context;
  3. write supermentor-ack JSON lines to stdin; and
  4. tell the agent to answer by writing the requested reply.json file.

See docs/architecture.md for protocol details.

Development

npm test
npm run smoke
node --check server.cjs

Start the server manually for UI/server smoke testing:

node server.cjs

Manual server mode prints a server-started JSON event with the URL, session id, session directory, and token. Inline browser questions still require a harness adapter; manual server mode does not route questions into an agent session by itself.

Credits

Supermentor is inspired by Superpowers by Jesse Vincent (@obra), especially its skill-first approach and local harness installation patterns.

License

MIT © bnema

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 4

↑↓ moveenter openesc close