Configuration

Every setting Learner reads, where to put it, and how to make it stop.

Two layers, read in this order:

$CLAUDE_CONFIG_DIR/learner.json (default ~/.claude/learner.json) — your defaults for every repository. Written by the installer, edited by learner config ….
<repo>/.claude/learner.local.json — optional, gitignored, a partial override for one repository. Written by learner off, learner on and learner config project ….

The project layer wins key by key, and arrays are replaced wholesale rather than merged: a project untrackGlobs is the whole list for that repo, not an addition to the global one. A key you did not set keeps its global value, and "enabled": false survives the merge — it is a deliberate override, not an absent key.

Key	Values	Default	Effect
`level`	`D`/`J`/`C`/`S`/`E`	— required	How hard a question is. No valid level means no questions
`enabled`	bool	`true`	Master switch for the automatic quiz
`questionStyles`	`"auto"`, or a subset of `code`/`architecture`/`fill`	`"auto"`	Which formats a question may take
`synthesisFrequency`	`off`/`rare`/`normal`/`often`	`normal`	A synthesis question every 0 / 8 / 4 / 2 questions
`blanksPerExercise`	int ≥ 1	`2`	`// LEARNER-TODO` holes cut in a `fill` exercise
`untrackGlobs`	array of globs	`[]`	Extra paths excluded from quiz material
`disabledPaths`	array of path prefixes	`[]`	Repositories where Learner stays silent
`coach`	bool	`false`	Coach regime: the dev writes, Claude challenges
`coachPollSeconds`	int ≥ 5	`30`	How often the watcher measures the dev's changes
`coachQuietPolls`	int ≥ 1	`1`	Consecutive unchanged polls — a pause — before a review fires
`coachMinLines`	int ≥ 1	`10`	Fewer changed lines than this never triggers a review
`coachCooldownMinutes`	int ≥ 0	`3`	Floor between two reviews
`coachMaxWaitMinutes`	int ≥ 0	`15`	Emit even without a pause once material has waited this long; `0` disables
`coachIdleMinutes`	int ≥ 1	`45`	Zero changes for this long — the watcher stops
`pilotEnabled`	bool	`false`	Opt-in master switch
`pilotCadenceDays`	int ≥ 1	`7`	Days between briefs
`pilotJudgeIntervalHours`	int ≥ 1	`24`	Minimum gap between queue drains
`pilotNudge`	bool	`true`	Whether a live manoeuvre may speak on UserPromptSubmit
`agentSalvo`	bool	`true`	Questions while a subagent is working
`agentSalvoQuestions`	int ≥ 0	`2`	Questions in a salvo, before the exercise
`agentSalvoFill`	bool	`true`	Cut a fill-in exercise at the end of a salvo

The seven keys above configure the automatic quiz. The seven coach* keys configure the coach regime, where the dev writes the code and Claude challenges it: a review fires when the dev pauses typing, sized by how much changed since the last one. See the coach section of Usage for how the cadence behaves. The four pilot* keys configure Pilot, an opt-in subsystem that measures delegation to Claude across all repositories over weeks.

level is the only one of the seven with no default. The other six have theirs in LEARNER_DEFAULTS at the top of hooks/learner-config.sh; level is left out on purpose, so a half-finished install asks nothing rather than guessing how much you know. SessionStart mentions it once when that happens. A full config looks like this:

{
  "level": "C",
  "enabled": true,
  "questionStyles": "auto",
  "synthesisFrequency": "normal",
  "blanksPerExercise": 2,
  "untrackGlobs": ["*.md", "*.json"],
  "disabledPaths": []
}

You do not have to edit it by hand: learner config level=S validates and writes for you, and learner config project synthesisFrequency=often does the same for the current repository only. The same shape ships in the repository as learner.json.example, for reference or copy-paste.

Levels

The canonical value is the letter. The full word is accepted too, in any case, so senior, Senior and S are the same setting.

Letter	Name	What a question targets
`D`	Discovering	syntax, what a block is for, basic vocabulary
`J`	Junior	what the function does, where the code lives
`C`	Competent	why this split, edge cases, error handling
`S`	Senior	trade-offs, rejected alternatives, impact on performance and coupling
`E`	Expert	invariants, failure modes, what breaks at scale

The level is a claim about you on this code, not a job title, and it is one word to change. Set it high and the easy questions stop; set it low for a stack you have never touched. Anything that is not one of the five letters or names is not a level at all: the hook treats it as unset and asks nothing.

Turning it off

Three ways, by scope. The first two leave the guardrail in place; the third silences that too, which is rather the point of it.

Everywhere. Set "enabled": false in the global config, or say learner config enabled=false. An explicit learner quiz still runs when you ask for one — you asked.
One repository you own. Say learner off in it. That writes <repo>/.claude/learner.local.json and adds the file to the repo's .gitignore if it is not already there. learner on reverses it. That file is the only thing Learner ever adds to a repository, and only on request — a fill exercise (see above) is a different kind of change: it temporarily edits one of your own source files rather than adding a new one.
One repository you do not own, where nothing of yours should be committed. Add its path to disabledPaths in the global config — learner config disabledPaths='["/path/to/repo"]'. Nothing is written into that repository at all. Matching is a path-prefix check on whole components, so disabling /a/b silences /a/b/c but not a sibling /a/bee; a leading ~/ is expanded, and an entry that exists on disk is resolved to its physical path first, so an entry that reaches the repo through a symlink still matches.

Next: Safety — what a fill exercise does to your files.