sf-shenfeng/learn-shell

> Your AI is becoming the one who knows you best. Learn Shell gives it a classroom that remembers — an agent-native teaching OS that turns your AI's teaching intent into things a learner can actually study, practice against, and get graded on.
**Codename**: learn-shell · **Status**: working system, actively dogfooded since 2026-07-02. Not authenticated. AGPL-3.0 licensed (v0.x was MIT; relicensed 2026-08-16, see note below); v1 is a single-machine, no-auth trust model.
**Setting this up from a code snapshot?** Follow SETUP.md — from-zero bring-up (Docker Postgres → migrate → seed → run → connect your own AI over MCP), every command verified against this repo's real config. Once it's running, the product tutorial (Chinese-first: cold-start pitfalls, the recommended lesson path, the agent's onboarding letter) is docs/TUTORIAL.md.
---
What this is
If you already have an AI you talk to daily — a work assistant, a long-running companion — it is quietly becoming the person who knows you best: it has read your every answer and seen your every hesitation. What it's missing is not knowledge of you. It's a floor. A chat window has no floor: the evidence of teaching evaporates with the context window, every new session your teacher wakes up a stranger, and you introduce yourself, again, to the one who knows you best.
Learn Shell is the floor. It doesn't replace your AI — it gives its teaching somewhere to live: courses, lessons, flashcards (FSRS-scheduled), exercises with grading, a mindmap, a document reader, and a memory layer the agent reads back (get_context / get_learner_brief) instead of re-deriving you from scratch every session. The teacher can change sessions, change models entirely — walk back in, and the classroom is exactly as it was left.
The agent talks to Learn Shell through MCP — 50 tools at this writing, plus data resources and a composable skill/prompt layer. The exact surface is self-describing: the manifest://capabilities resource is generated live from the running registries, so it can't drift the way this sentence can. MCP itself is evolving — the 2026-07-28 spec revision (stateless core, Apps and Tasks extensions) is on our roadmap watch list, tracked but not yet promised. Surfaces are bilingual: docs and receipts are English-first, MCP tool descriptions and the prep-report Chinese-first in v0.1 — agents read both; full EN localization is on the roadmap. A human talks to it through a normal web app. Both surfaces read and write the same data.
Full vision: docs/VISION.md (v5.2 — voice recast 2026-07-27, promises unchanged; red-team calibrated; assertion-by-assertion status tracked internally, not part of this package — a promise-level summary is public in Promise status below). Product direction / what's being hardened next is tracked in an internal working doc.
---
What it looks like
Real product, demo environment (the seeded English TVM course), no mockups. Every image follows your color scheme — dark readers see the dark app, light readers the light one.
*Lesson — graded exercise feedback. The teacher quotes the learner's answer back verbatim before correcting it; the mistake shown is a real one, kept because it was worth being wrong about.*
*Journal — the learning biography. Lessons, reviews and live sessions on one timeline; scrolling it reads like a record of a relationship, because it is one.*
*Review — FSRS-scheduled flashcards, authored by the teacher out of what the lessons actually covered.*
*Live Teaching — a real-time, turn-based session beside the course text. The learner ends it, not the teacher: the close bell is theirs.*
What the agent sees
The pages above are the learner's surface. The teacher's surface is receipts — here is a real get_context return from that same demo environment, data field verbatim, nothing truncated:
One call, and a teacher who has never met this session knows where the relationship stands. That — not the pages — is the point.
---
⚠️ Security notice — read before you deploy this anywhere but localhost
**v1's trust model is single-machine.** The server binds 127.0.0.1 by default — your data is visible only to processes on the same machine. No account system exists because this is local-first by design, not an oversight: there is no per-agent credential, no scoped token, no audit trail beyond "actor: mcp", because v1 assumes one machine, one trust boundary.