A study partner that makes you explain what you've read, in your own words, until you really understand it.
You read a book and mark what matters. ai-coach turns your marks into a few clear ideas, then quizzes you on them like a demanding tutor. It never gives you the answer. It pushes back on vague answers and buzzwords, tells you what you missed, and brings each idea back when you're about to forget it.
It works on your own notes in an Obsidian vault, and the sparring runs entirely on your machine.
$ npm run coach -- spar
coach> Explain, as if to a newcomer, why a note is distilled in layers rather than all at once.
you> You bold what matters on the first pass, then highlight the best of the bold,
... so later you can read just the highlights.
...
coach> You said "the best of the bold". What makes one bolded sentence better than
another when you come back to the note months later?
(An illustration: the questions depend on your note and the model.)
read ──► distill ──► synthesize ──► spar ──► judge ──► study
▲ │
└──── review ◄──────┘
- Read and distill a book in Obsidian: bold what matters, highlight the best, summarise each chapter.
- Synthesize your marks into concept notes, one idea each, in your words.
- Spar: explain an idea to a local model (Gemma on Ollama). It asks follow-ups and gives a verdict. Offline.
- Judge: an online model (Gemini) checks your answers for gaps. It sees only the questions and your answers, never your notes.
- Study what you missed, then review when the idea is due. Ideas you know well come back less often.
The same vault can also hold your plans: Claude Code skills plan your year down to your day.
You need Node.js 24+, an Obsidian vault, Ollama, and a built checkout of kb-template (see Status).
npm install && npx nx run-many -t build
ollama pull gemma3
cp coach.config.example.json coach.config.json # set vault, docsMcpBin, ollama.model
npm run coach -- init # set up the vault folders
npm run coach -- due # see what to study todayThe setup guide explains each step, and your first session walks you through the whole loop.
| I want to… | Read |
|---|---|
| Install and connect everything | Setup |
| Try the loop on a real book | Your first session |
| Look up a command or a setting | Commands · Configuration |
| Pick how the coach pushes me | Coaching styles |
| Know what leaves my machine | Privacy |
| Fix an error | Troubleshooting |
| Understand a term | Glossary |
| Plan my week with Claude Code | Planning skills |
| See how it's built, and why | Architecture · Decisions |
| Change the code | Contributing |
Everything is also on the documentation site, with search.
ai-coach is a personal project, used daily and still changing. It needs kb-template, which owns the vault and is not public yet, so it can't run without a checkout of it. Small local models make mistakes: treat a sparring verdict as a first opinion, which is what the judge is for.
MIT © 2026 push-based. kb-template is a separate project with its own license.