watchandlearn
v0.1.0-demo.0
Published
Companion TUI for Claude Code: spaced-repetition micro-practice generated from the code Claude just wrote in your repo, plus a live plain-language feed of what Claude is doing. Learn to code by not coding.
Maintainers
Readme
watchandlearn
Learn to code by not coding. A companion TUI for Claude Code that fills your wait time — while Claude thinks and works — with spaced-repetition micro-practice generated from the code Claude just wrote in your own repo, plus a live plain-language feed of what Claude is doing so you can steer at turn boundaries.
Demo release (
0.1.0-demo.x, npm tagdemo): early and rough — install withnpx watchandlearn@demoexplicitly; plainnpm install watchandlearnstays unassigned until 0.1.0 proper.
You run Claude Code in one tmux pane and wal in the pane next to it. While Claude
works: a feed narrates each edit, and you review flashcards mined from your recent
sessions. When Claude needs a permission: the pane flashes with exactly which tool
wants to do what. When a turn ends: one checkpoint question tests whether you
understood the change well enough to accept it — and if you didn't, you get a
ready-to-paste steering prompt for Claude.
TODO: GIF — Claude working in the left pane, a flashcard about that exact code appearing in the right pane.
Install
Requires Node ≥ 22.13 and Claude Code installed and authenticated. Zero native dependencies — nothing compiles at install.
npx watchandlearn init # onboarding: your levels, focus topics, consent, hook setupRestart any Claude Code sessions that were already running (hooks load at session start), then open the TUI in a spare pane:
npx watchandlearn # or the short alias: walHow it works
- Hooks → events.
initregisters passive, async Claude Code hooks that append every session event to a local JSONL file via an atomic writer. Hooks never block or slow Claude Code; if wal isn't running, events simply accumulate and are processed on the next launch. - Parser. wal tails that file and reconstructs sessions and turns — multiple concurrent Claude sessions stay cleanly separated.
- Workers. Small headless calls to your own Claude (
claude -p, Haiku-class for volume work, Sonnet-class for the turn-end checkpoint) narrate edits, extract teachable concepts from the diffs, and author flashcards — which are then parser-linted, verifier-gated, and scheduled by FSRS. All scheduling, levels, and stats are computed by local code; no model ever writes a number. - Review. Due cards first, then at most 5 new cards per session. Rate with one key; your per-topic level promotes and demotes automatically from your accuracy.
Card content mirrors to plain markdown in ~/watchandlearn/cards/ — edit any card in
your editor and wal re-imports your wording on next launch (scheduling stays in
SQLite, so hand-edits can never break your review history).
Keys
space reveal · 1-4 rate (again/hard/good/easy) · f flag a bad card ·
enter reveal checkpoint · k/d knew / didn't know · c copy steering prompt ·
tab switch focused session · q quit
Privacy — exactly what is stored where
Everything is local. There are no servers, no telemetry, and no accounts.
| Path | Contents |
|---|---|
| ~/watchandlearn/events.jsonl (+ rotated archives) | Raw hook events from your Claude Code sessions: your prompts, file paths, diffs and tool inputs/outputs |
| ~/watchandlearn/watchandlearn.db | Sessions, the concept ledger, cards with FSRS scheduling, your review log, checkpoint results, and generation/feed logs (the exact model inputs and outputs, kept so bad cards can be debugged) |
| ~/watchandlearn/cards/*.md | Human-editable card content mirrors |
| ~/watchandlearn/profile.md | Your learner profile — yours to edit freely |
| ~/watchandlearn/hook.mjs | The event writer the hooks run |
| ~/watchandlearn/debug.log | Diagnostics for dropped model calls |
| ~/.claude/settings.json | The hook registrations (timestamped .wal-backup-* copies are written before every change) |
The only thing that ever leaves your machine: the headless claude -p calls above,
which carry diff excerpts, ledger summaries, and your profile excerpt to your own
authenticated Claude — the same trust boundary as using Claude Code itself.
WATCHANDLEARN_DIR relocates the entire data dir (useful for sandboxes).
Uninstall
npx watchandlearn uninstall # removes hooks + writer; your data stays
npx watchandlearn uninstall --purge # ...and deletes all local data tooSettings backups from every change remain at ~/.claude/settings.json.wal-backup-*.
Development
Start with docs/README.md — a nine-part onboarding series
covering the full pipeline, every worker, the storage schema, the domain rules and
where each is wired, and the known gaps. Binding contracts: INVARIANTS.md,
BEHAVIOR.md, design/. AI contributors: CLAUDE.md is the entry point.
npm test (includes replaying the captured hook fixture through the full pipeline),
npm run typecheck, npm run build. TESTING.md is the manual QA walkthrough. Pack
smoke: npm pack, install the tarball in a clean directory, run wal --help and
wal --replay on the fixture.
watchandlearn is an independent open-source project that works with Claude Code; it is not affiliated with Anthropic. MIT licensed.
