Install

What Learner needs, the ways in, what lands where, and which platforms can run it.

Requirements

• jq on PATH — needed to install (the hook wiring is merged with it) and needed by every hook at run time except the update-check notifier, which has no jq dependency by design. Without it the rest are inert, and SessionStart says so once.
• bash on PATH to install — install.sh is a bash script.
• curl is used at run time — by the update-check hook only, once every 24h, to look for a newer version. Its absence there is silent, not an error — unlike jq, curl is never a hard requirement for anything already installed.
• A POSIX-compliant shell at run time — separate from the bash requirement above, and not satisfied by it. The hooks are plain sh scripts, wired into settings.json as sh "…/hooks/learner-quiz.sh". See Platforms.
• Claude Code — either claude on PATH or an existing config directory.

Claude Code plugin

claude plugin marketplace add Tykok/learning-with-claude
claude plugin install learner@learning-with-claude

Installs and enables the skills and their hooks natively — no ~/.claude file copying, no learner-install step. Claude Code manages updates itself (/plugin update learner); run learner update and it will tell you the same thing rather than trying to curl a second, traditional install on top. Already installed via curl, clone, Homebrew, or apt? Run uninstall.sh (or learner-uninstall) first — running both wires every hook twice.

apt (Debian/Ubuntu)

# one time
curl -fsSL https://tykok.github.io/learning-with-claude/apt/learner.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/learner.gpg
echo "deb [signed-by=/usr/share/keyrings/learner.gpg] https://tykok.github.io/learning-with-claude/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/learner.list

# from then on
sudo apt update && sudo apt install learner
learner-install --level S --synthesis normal --blanks 2

One curl remains — fetching the repository's trust anchor once, the same pattern Docker's and HashiCorp's own apt repos use. There is no keyless way to establish that first trust, but after this one-time step, sudo apt update && sudo apt upgrade learner is the whole update story — no more curl involved, ever.

Prefer not to add a repository? Grab the .deb directly from Releases instead:

curl -LO https://github.com/Tykok/learning-with-claude/releases/download/v0.3.0/learner_0.3.0_all.deb
sudo apt install ./learner_0.3.0_all.deb
learner-install --level S --synthesis normal --blanks 2

v0.3.0 is this release. Check Releases for the current version if you're reading this after a newer one has shipped.

Homebrew

brew install tykok/tap/learner
learner-install --level S --synthesis normal --blanks 2

A personal tap (Tykok/homebrew-tap), not homebrew-core. Each tagged release updates it.

Both apt and Homebrew only stage the files and drop learner-install / learner-uninstall on PATH — neither touches ~/.claude on its own. Run learner-install afterward, same flags as install.sh below. Uninstalling reverses the same way: sudo apt remove learner / brew uninstall learner only remove those two wrapper binaries — the payload under ~/.claude still needs learner-uninstall (same as uninstall.sh) to actually come out.

Clone and run

A first-class path, not a fallback: it is the one that lets you read the installer before you run it.

git clone https://github.com/Tykok/learning-with-claude
cd learning-with-claude
./install.sh                       # prompts for level / synthesis / blanks
./install.sh --dry-run             # print what would happen, write nothing
./install.sh --yes                 # never prompt; defaults for anything unset
./install.sh --level S --synthesis normal --blanks 2    # non-interactive, one shot

To install a release rather than whatever main says today, clone its tag: git clone --depth 1 --branch v0.5.0 https://github.com/Tykok/learning-with-claude. There is no path that pipes a download into a shell: every install runs an install.sh you have on disk and can read first.

• --level D|J|C|S|E — the letter, or the full word from the levels table, in any case. It has no default: on a fresh install, --yes with no level stops rather than guessing. Once learner.json already exists this whole prompt/validate step is skipped — the flag has nothing to do, and the existing config is left untouched either way.
• --synthesis off|rare|normal|often — how often a synthesis question replaces a granular one.
• --blanks N — holes left in a fill exercise, an integer of 1 or more.
• --dry-run — print what would be written; write nothing.
• --yes (-y) — never prompt; use the default for anything not passed.

The installer is idempotent: re-running re-copies the hooks and the skills and re-merges the hook wiring without duplicating entries, and it never overwrites a config you already have. It writes nothing into any repository. Every path it touches is under $CLAUDE_CONFIG_DIR (default ~/.claude), and every wired hook command carries the literal ${CLAUDE_CONFIG_DIR:-$HOME/.claude} rather than an expanded path, so moving your config directory later needs no reinstall.

Hook wiring is read once, when a Claude Code session starts. Installing (or re-installing) while a session is already open changes nothing in it — quit and start a new session for the hooks to take effect.

What gets installed, and where

Everything lives under $CLAUDE_CONFIG_DIR, written $CFG below.

Fifteen hook files ship and twelve are wired, into SessionStart (three times — learner-onboard.sh, learner-update-check.sh and pilot-brief.sh all fire there), PreToolUse (coach-gate.sh on the Write|Edit|NotebookEdit matcher, plus learner-agent-track.sh --start on its own Task matcher), PostToolUse (learner-record-edit.sh on Write|Edit, plus learner-agent-track.sh --end on Task), Stop, SessionEnd (twice — learner-cleanup.sh and pilot-record.sh, the latter at a raised timeout of 15 since it reads a whole transcript) and UserPromptSubmit (twice — pilot-nudge.sh and coach-armed-check.sh). Three ship unwired: learner-config.sh is sourced-only, and Claude Code never invokes it directly; coach-watch.sh is never a static entry either — learner-onboard.sh arms it as a Monitor at session start, only once coach mode is on; and learner-sync.sh is never wired to a hook event at all — the skill invokes it directly, only when the dev types learner sync. Twelve of the other thirteen source learner-config.sh — every hook but learner-cleanup.sh, which needs none of it.

Platforms

Native Windows is a genuine gap rather than an untested platform. Every hook is a POSIX sh script and each is wired as sh "…", so without a POSIX shell on the machine there is nothing for Claude Code to execute. WSL and Git Bash both supply one, and on either of them Learner behaves exactly as it does on Linux.

Next: Usage — the three shapes a question takes.