your-ai-tutor
A harness that turns Claude into a Socratic tutor.
A harness is the system around a model that lets it act as an agent: prompts, tools, memory, skills, orchestration. your-ai-tutor is a harness built for one job. It makes the agent teach by asking questions, so the learner writes every line that matters and the agent never finishes the work for them.
You bring a topic. your-ai-tutor gives you an env for it, a session loop that remembers where you stopped, a schedule that tells you what to do today, retros that improve the harness, and a ladder for learning how real websites work by reverse engineering them in your own Chrome.
Start
You need Claude Code. Nothing else.
git clone <this repo> your-ai-tutor && cd your-ai-tutor
claude
Then say what you want to learn:
I want to learn
The tutor interviews you, makes an env for it, and tells you the one phrase to start. Next time, just open claude here and say what should I do today.
What you get
| You say | What happens |
|---|
| "I want to learn " | yat:new-env interviews you and scaffolds envs/<topic>/ |
| "let's do my-env" | yat:learn runs a Socratic session from the env's spec |
| "what should I do today" | yat:session reads every env's cadence and names today's block |
| "wrap up" | yat:session saves the bookmark, journals the session, ticks the swim lane |
| "quiz me" / "test me" | yat:grill asks only about what you have learned, never repeating a question, keeps a mistake book you correct in your own words, and brings ideas back for review when they're due |
| "show my profile" | yat:memory shows what the tutor has learned about how you learn, each line backed by dated evidence you approved |
| "read with me" | yat:read walks a book or paper with you section by section: you predict, read and explain; every question names its page, and the tutor never summarizes for you |
| "review my notebook" / "compile my notebook" | yat:notebook keeps your own explanations, word for word, one page per idea; the tutor only asks questions about them, and compiles them into a book you wrote |
| "build my mastery map" | yat:mastery maps the ideas behind your roadmap and tracks each one by what you've shown, never by what you say |
| "retro" | yat:retro debriefs you and queues concrete improvements to the harness |
| "reverse engineer " | yat:reverse-engineer walks a seven-rung ladder in your Chrome |
| "card this" | yat:anki makes a flashcard in Anki, if you have it |
yat: is how these docs name the skills. Inside this repo they load as project skills, so Claude Code lists them by folder name (/learn, /session, /grill). You only see /yat:learn after installing the plugin (see For contributors). Either way you rarely type the name: routing is by phrase.
How it is built
Everything that shapes the tutor lives under harness/ as plain files: system prompt, guardrails, memory schema, tool guidance, subagents, skills, scripts, plugins. Your topic is data, one env.toml per env, and the pedagogy never has to change to add one. Skills load straight from the repo through .claude/skills, so there is nothing to install. Read docs/ARCHITECTURE.md, and docs/CONCEPT.md for why it exists.
Your data lives in envs/, media/, tracker/ and memory/. They ship empty and are git-ignored by default.
Docs
The same pages, as a site: https://rdennler.github.io/yat/ (built from docs/ by website/).
For contributors
The Python package (3.11+, no dependencies) holds the checks and the optional plugin install. Run from the repo root, no pip install needed:
python3 -m your_ai_tutor.cli.lint # skill manifests, env specs, cross-references
python3 -m unittest discover tests
python3 -m your_ai_tutor.cli.status # today's block, each env's bookmark, a graph summary
python3 -m your_ai_tutor.cli.install # optional: install the `tp` plugin to use the tutor outside this repo
python3 -m your_ai_tutor.cli.evals check # eval cases, labels and routing coverage (offline)
python3 -m your_ai_tutor.cli.evals run --rule route # live: does each request reach the right skill
python3 -m your_ai_tutor.cli.evals run # live: the whole tutor eval suite
The docs site is a separate Node app; the Python package stays dependency-free:
cd website && npm install && npm start # live preview of docs/ at localhost:3000/yat/
npm run build # what the GitHub Pages workflow runs; fails on broken links
pip install -e . adds these as yat-lint, yat-status, yat-new, yat-install and yat-evals.
yat-evals run and calibrate need Claude Code 2.1.269+ with claude plugin eval, and spend model calls (about one
agent run per case per run). --runs, --rule, --case and --max-cost-usd keep a run small. Results go to the
git-ignored runs/evals/.
License
Apache 2.0. See LICENSE.
