Learning Moments

Keep the speed of AI-assisted programming without giving up the habit of understanding your code.

Learning Moments asks brief questions about changes made during a Claude Code session.

AI coding agents can inspect a codebase, plan a change, edit files, run tests, and summarize the result. Their speed also makes it easy to move on before tracing the code, predicting its behavior, or deciding how to test it.

After a meaningful change, Learning Moments may ask one short question about the files you are working on:

Learning Moment lm_a7f3 The new retry branch treats timeouts differently from other failures. What behavior would you expect after the final timeout, and what test would distinguish it from the old behavior?

You answer in the normal Claude Code conversation. Learning Moments gives brief feedback and the work continues. If the change does not support a useful, specific question, or if selection fails, it stays quiet.

Each question checks whether you can explain, predict, or test code you just accepted. It supplements code review and tests with a quick comprehension check while the change is still fresh.

Because the hook runs inside active projects, the package is unobfuscated, has no runtime dependencies or install-time scripts, and includes checks that connect the public GitHub source to the npm package. See Inspectability and package integrity.

learning-moments metrics reports added time and estimated model cost, with token counts available in JSON. One pause command stops the questions when you need uninterrupted work. The learning profile, selection policy, and grading rubric are Markdown files you can edit without rebuilding or reinstalling anything.

Contents

• Get started with the quick start, commands, and configuration.
• Read the project status, current claims, hook lifecycle, and design rationale.
• Review privacy and trust, package integrity, and performance and cost.
• See related projects, development, the roadmap, and the license.

Status

Learning Moments is an early alpha for local testing and research prototypes.

Implemented today:

• project-local installation through Claude Code Hooks;
• Git-based detection of changes made during the current Claude Code session;
• situated Predict and Test questions selected with claude -p;
• answer capture, skipping, structured 0-3 grading, and brief feedback;
• configurable question and classifier budgets;
• local timing, usage, cost, and outcome metrics;
• project/session pause controls and observe-only mode;
• secret-path filtering, pattern redaction, and local integrity auditing; and
• fail-open behavior: a Learning Moments failure does not block Claude Code.

Not implemented yet:

• delayed recall across sessions (issue #15);
• background classification; the classifier currently adds synchronous hook latency (issue #14);
• confidence prompts or polished research exports; and
• support for coding agents other than Claude Code.

What I can claim so far

I have used Learning Moments in my own work for several weeks. That is too little evidence to say whether it prevents long-term skill decay, especially without delayed recall.

In that time, its questions have regularly shown me that I accepted code without fully understanding it. A specific question often reveals that I cannot yet predict the behavior, explain a decision, or name the test that would expose a mistake.

For now, I can say only that it checks comprehension in the moment. I do not yet know whether repeated checks improve long-term retention.

Quick start

Requirements

• Node.js 20 or newer
• Git
• a recent Claude Code version with Hooks support
• Claude Code authenticated on your machine
• a Git repository you trust

Learning Moments calls claude -p using your existing Claude Code authentication and model configuration. Those calls can consume usage and may incur provider charges.

Install

npm install -g learning-moments

Initialize it in a project where you use Claude Code:

cd /path/to/your/project
learning-moments init
learning-moments doctor

Then start Claude Code normally:

claude

init creates project-local configuration under .learning-moments/, adds that directory to .gitignore, installs hooks in .claude/settings.local.json, and creates /learning-moments:* command prompts. It is safe to rerun after an upgrade.

By default, Learning Moments asks at most one question per hour, with at least 20 minutes between questions. It is intentionally not triggered by every edit.

When you just need to get work done, pause it from Claude Code:

/learning-moments:pause

Resume later with /learning-moments:resume. The equivalent shell commands are learning-moments pause --project and learning-moments resume --project. Pausing does not uninstall the hooks or delete your learning record.

Try it without automatic questions

Observe-only mode runs selection and records what would have happened, but does not inject questions:

learning-moments init --observe-only

Observe-only mode still calls Claude for candidate selection, so it can add latency and consume usage.

Install from an auditable checkout

The package runs directly from readable JavaScript. There is no generated dist/ bundle.

git clone https://github.com/raghubetina/learning-moments.git
cd learning-moments
npm ci --ignore-scripts
node src/cli.js init
node src/cli.js doctor

Hooks installed this way point to that checkout's absolute src/cli.js path, so you can inspect or pin the exact implementation being executed.

How it works

Claude Code session starts
        |
        v
Record a Git working-tree baseline
        |
        v
Claude edits files ---> compare with the baseline
        |
        v
Filter ignored paths, bound context, skip symlinks/binaries,
and redact likely secrets
        |
        v
Use `claude -p` to decide whether the change contains a
specific, worthwhile Learning Moment
        |
        +--- decline / timeout / error ---> stay quiet
        |
        v
Check the interruption budget and inject one short question
        |
        v
Capture the next answer or "skip" ---> grade ---> brief feedback

The lifecycle is implemented with six Claude Code hooks:

1. SessionStart records the current branch, commit, dirty paths, and content fingerprints.
2. PostToolUse records lightweight edit telemetry.
3. PostToolBatch finds files that changed since the session baseline and selects a candidate moment.
4. UserPromptSubmit captures and grades the answer to a pending question.
5. Stop checks whether the question or feedback was actually displayed.
6. UserPromptExpansion records slash-command hook activity.

Change attribution is session-relative. Learning Moments can tell that a file changed after the baseline; it cannot prove that every byte came from Claude rather than an external editor used during the same session.

Question types

• Predict asks what behavior changed or what might break.
• Test asks for a concrete check that would expose a misunderstanding.
• Recall would ask for the rationale behind an earlier change. It is part of the design vocabulary but is not implemented yet.

The selector generates an expected-answer outline for grading, but that outline is not inserted into the conversation before you answer.

Commands

Command	Purpose
learning-moments init	Create local data, hooks, and command prompts
learning-moments doctor	Check the installation and required tools
learning-moments status	Show mode, pause state, frequency, and answer counts
learning-moments metrics [--since 7d]	Report latency, outcomes, usage, and estimated cost
learning-moments verify	Print a question about meaningful current uncommitted changes
learning-moments pause --project	Stop asking questions in this project
learning-moments resume --project	Resume questions in this project
learning-moments override <id> --grade 0-3	Record a manual grade correction
learning-moments audit	Verify installed package files against the shipped manifest
learning-moments uninstall	Remove hooks and slash commands but keep learning data
learning-moments delete-data --logs-only	Truncate disposable telemetry only
learning-moments delete-data	Delete all project-local Learning Moments data

Claude Code command prompts are also installed for status, metrics, pause, resume, and manual verification.

Configuration

Learning Moments separates stable integration code from editable pedagogical policy:

.learning-moments/
|-- config.json
|-- profile.md
|-- prompts/
|   |-- classify-change.md
|   |-- grade-answer.md
|   |-- answer-feedback.md
|   |-- select-recall.md
|   `-- verify.md
|-- ledger.jsonl
|-- control.jsonl
`-- telemetry.jsonl

• profile.md describes the skills you want to preserve and your interruption preferences.
• classify-change.md defines what makes a question worthwhile.
• grade-answer.md defines the 0-3 rubric and feedback style.
• config.json controls models, timeouts, budgets, ignored paths, and context limits.

The profile, classifier policy, and grading rubric are read again when the relevant model call runs. Edit the Markdown, save it, and the next selection or grading call uses the new policy. There is no prompt build step and no restart required.

Defaults:

Setting	Default
Visible questions per hour	1
Minimum spacing	20 minutes
Classifier calls per hour	10
Maximum changed paths	20
Maximum diff/context	12,000 characters
Classifier model	opus
Grader model	opus
Model-call timeout	45 seconds

init preserves valid existing configuration, profiles, and prompt policies. It refreshes the installed hooks and Claude Code command files.

Privacy and trust

Learning Moments stores its own data locally and uses your configured Claude provider for inference. It has no backend and sends no product telemetry to the project author. Configuration and event records stay in the Git-ignored .learning-moments/ directory. Candidate diffs and answers are sent through your configured Claude Code model provider when Learning Moments calls claude -p.

Before a model call, the tool:

• excludes common generated and secret-bearing paths such as node_modules/**, .env*, .npmrc, .ssh/**, private-key extensions, and lockfiles;
• refuses to follow symbolic links while gathering file context;
• skips large and binary untracked files;
• caps both path count and context size;
• redacts common credential formats in diffs and answers;
• disables tools, hooks, slash commands, and session persistence in the nested Claude process; and
• validates model responses against strict JSON schemas.

These controls reduce exposure but cannot catch every secret. Review .learning-moments/config.json and src/core/redaction.js before using the tool on sensitive code. Use it only in repositories you trust. Claude Code's non-interactive -p mode does not show the workspace trust dialog.

See SECURITY.md for vulnerability reporting and AUDIT.md for the current code-review record and residual risks.

Local storage classes

• ledger.jsonl is the durable learning record: questions, answers, grades, and model-call usage.
• control.jsonl contains bounded operational state such as session baselines and recent classifier claims.
• telemetry.jsonl contains disposable hook timing and failure outcomes.

learning-moments delete-data --logs-only truncates only telemetry. Full deletion removes the entire .learning-moments/ directory.

Inspectability and package integrity

Learning Moments is designed so you can inspect the code that runs inside your projects:

• unobfuscated, source-executed ESM JavaScript;
• no bundling, minification, or generated runtime artifact;
• zero runtime npm dependencies;
• no npm install-time lifecycle scripts;
• CI on the declared Node 20 floor;
• package metadata that identifies this public GitHub repository;
• npm Trusted Publishing from GitHub Actions, without a long-lived npm publish token;
• an npm provenance attestation connecting the published package to its source repository and workflow; and
• a SHA-256 manifest that accounts for every expected shipped source file and flags unexpected ones.

You can inspect the latest version's registry attestation without installing it:

npm view learning-moments dist.attestations --json

The npm package page exposes the attested source commit, build workflow, and public transparency-log entry. npm also documents how npm audit signatures verifies registry signatures and provenance for packages downloaded into a local npm project.

After installation, run:

learning-moments audit

The command reports installation mode, hook entrypoints, runtime dependencies, lifecycle scripts, prompt files, and any missing, unexpected, or modified shipped file. These checks expose the implementation, package contents, and GitHub-to-npm provenance for independent review. Assessing whether the software is safe still requires reading the code and considering the repository where it will run.

Performance and cost

Model selection and grading cost time and tokens. Learning Moments records hook latency, classifier and grader latency, token use, cache tokens, and Claude-reported estimated cost:

learning-moments metrics
learning-moments metrics --since 7d
learning-moments metrics --since 24h --json

Metrics include:

• total hook runs, median latency, and p95 latency;
• classifier attempts, declines, duplicates, and fail-open outcomes;
• answer-feedback attempts and failures;
• questions, answers, skips, and grades; and
• Claude-reported token use and estimated cost.

The current classifier runs synchronously in PostToolBatch, so eligible classification attempts can noticeably pause the workflow. Frequency gating avoids many unnecessary calls, but the architectural fix is the background pipeline tracked in issue #14.

Related projects

Other projects are also exploring how developers can keep learning while they work with coding agents:

Project	When it intervenes	What it offers
Learning Opportunities	On request, or after substantial work and commits	Open-source Claude Code and Codex skills for optional 10-15 minute exercises, retrieval check-ins, and codebase orientation
StaySharp	When the developer runs /learn after a session	An early-access hosted dashboard with a generated lesson and optional short quiz
Learning Moments	After selected changes during a Claude Code session	A brief question inside the coding conversation, followed by structured feedback and local research metrics

Learning Opportunities provides longer exercises and guided exploration. StaySharp turns a completed session into material for later review. Learning Moments stays in the coding conversation: it selects one brief question from session changes, enforces an interruption budget, reports model cost, and stores outcomes locally.

Why this design

Learning Moments starts from a narrow concern: AI assistance can reduce opportunities to rehearse the comprehension and judgment routines developers still need to supervise and maintain software.

The design draws on several lines of research:

• skill decay under nonuse;
• the out-of-the-loop problem in automation;
• retrieval practice and long-term retention;
• self-explanation as a learning mechanism;
• the navigator's role in pair programming; and
• cognitive-engagement interfaces for AI-generated code.

The design follows five rules:

1. Use questions that require the developer to produce an answer.
2. Tie each question to the current change.
3. Ask while the relevant code is still in working memory.
4. Prefer concrete prediction, explanation, and verification.
5. Enforce interruption budgets and prefer silence over a weak question.

Structured local outcomes and observe-only mode make the intervention measurable without requiring a Learning Moments backend.

This prototype does not establish that Learning Moments prevents long-term deskilling. Immediate questions test feasibility and situated comprehension. Delayed recall and comparison designs are needed to study retention more directly.

Development

git clone https://github.com/raghubetina/learning-moments.git
cd learning-moments
npm ci --ignore-scripts
npm run check
npm test
node src/cli.js --help

The test suite mocks Claude model calls; running it does not consume Claude usage.

Release verification additionally checks npm advisories, the shipped-file manifest, and installation from the packed tarball. See CONTRIBUTING.md for the full workflow.

Roadmap

The next two product steps are:

1. Move classification off the blocking hook path.
2. Add delayed recall for prior Learning Moments.

Bug reports and small, well-tested improvements are welcome. For research use, the repository includes citation metadata.

License

MIT