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.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/media/01-lesson-exercise-feedback-dark.png"> <img alt="Lesson page: a graded exercise where the teacher's feedback quotes the learner's own answer verbatim and corrects a compounding/discounting mix-up" src="docs/media/01-lesson-exercise-feedback-light.png"> </picture>

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.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/media/02-journal-timeline-dark.png"> <img alt="Journal page: a timeline of lessons, reviews and live sessions reading like a learning biography" src="docs/media/02-journal-timeline-light.png"> </picture>

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.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/media/03-review-flashcards-dark.png"> <img alt="Review page: an FSRS-scheduled flashcard mid-review with the due count visible" src="docs/media/03-review-flashcards-light.png"> </picture>

Review — FSRS-scheduled flashcards, authored by the teacher out of what the lessons actually covered.

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/media/04-live-teaching-panel-dark.png"> <img alt="Lesson page with the Live Teaching panel open: a real-time turn-based session beside the course text" src="docs/media/04-live-teaching-panel-light.png"> </picture>

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:

{
  "pair_id": "pair_ms5wgdg0_ov2qty",
  "generated_at": "2026-07-30T00:35:38.461Z",
  "active_contracts": [
    {
      "id": "tc_ms5wgdgd_vyoo2f",
      "title": "Pass CFA Level I Quantitative Methods, starting with the time value of money",
      "setup_status": "established",
      "progress": "setup: established",
      "source_material": null
    }
  ],
  "recent_lessons": [
    {
      "id": "lsn_ms5wgwvy_qtcpbo",
      "title": "Time Value of Money — The Clock Inside Every Dollar",
      "status": "completed_declared",
      "last_activity_at": "2026-07-29T09:52:14.587Z"
    }
  ],
  "pending_pool": { "count": 0, "latest_titles": [] },
  "live_session": null,
  "unread_adhoc_count": 0,
  "active_reminder_count": 0,
  "contract_progress": [
    {
      "contract_id": "tc_ms5wgdgd_vyoo2f",
      "goal": "Pass CFA Level I Quantitative Methods, starting with the time value of money",
      "covered_course_count": 1,
      "completed_course_count": 1,
      "operationally_caught_up": true,
      "goal_completion_ready": false
    }
  ],
  "hypotheses_in_book_count": 1,
  "brief_etag": "b17254aded7a",
  "identity": { "learner_id": "lrn_ms5wg1wk_h36xhm", "agent_id": "agt_ms5wgdg0_7qzil8" }
}

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.

Cross-device deployment (HOST=0.0.0.0) is an explicit opt-in. Setting it means you trust every device on that network — only do this on a trusted LAN, and never expose the server (REST or the MCP stdio bridge) to the public internet. Real authentication is on the roadmap, targeted at the multi-device case: agent credential → principal → pair derivation → real-name audit, scoped as its own dedicated batch, not a full multi-tenant system.

---

Current state

Learn Shell is not a demo. It has been in continuous daily use as one real teaching relationship — one learner preparing for a real exam, one agent as her teacher — since the first real lesson on 2026-07-02. Every rule in the recipes traces back to a real lesson or a real failure: a course was once published into the void, so now there is a publish gate; a summary once outran the learner's own words, so now closing a lesson is a handshake; a green check once lied about "done", so now the lesson-completion check has exactly one owner — the learner.

What's actually shipped, as of this writing:

• 8 live pages: Courses, Lesson (course text + exercises + Live Teaching panel), Review (FSRS flashcard review), Cards (deck management), Journal (learning "biography" timeline), Quiz (agent-authored + real question-bank), Mind Map, Document Reader — plus Settings (identity, appearance, contract certificate + cadence, learner-model, feedback ledger, data export).
• MCP surface: 50 tools (at this writing, counted from the live registry) + pair:// data resources + the manifest://capabilities menu + per-recipe recipe:// volumes + a composable skill/prompt stack (domain × modality × intensity × tone × pace, picked per contract — ledger and verification layers are fixed, tone is never auto-imposed: the teacher's own voice wins). Mutating tools return a structured success/error envelope (resource_id/created_refs/next_recommended_actions on success; a closed VALIDATION/NOT_FOUND/CONFLICT/PERMISSION/RETRYABLE taxonomy on failure); most (34 of 50 at this writing) accept an optional idempotency_key for retry safety.
• A closed teaching loop that has actually run: lesson taught → exercise graded → hypothesis formed → attributed with evidence and a counterfactual check → next lesson revised → revision history visible to the learner as Revised · v{n}.
• A teacher inbox (get_teacher_inbox): a single incremental to-do list — pending grading, unreflected Live sessions, unanswered AdHoc messages, flashcard trouble spots, unsigned contracts — each item naming which tool to call next.
• Live Teaching: real-time turn-based sessions with an online/offline bridge and mid-lesson snapshot recovery.

An exact, current-as-of-code inventory of every route, table, and known drift between docs and implementation is maintained internally, kept honest against git HEAD, not against intent. When this README and the code disagree, trust the code.

The MCP capability surface is self-describing: read the manifest://capabilities resource for the live, generated menu of every tool, resource, prompt, and recipe this server exposes — it is derived from the running registries, never a hand-authored parallel list.

---

Promise status

The vision makes promises; this table says which ones the machine currently keeps. Three tiers:

• Enforced — a machine invariant: bypassing it is rejected by the system, not discouraged by docs.
• Implemented — the capability exists and works; adherence relies on convention and the recipes.
• Planned — on the roadmap, not in the code.

Qualified entries ("by default config", "by design", "partially") mean exactly what they say.

| Promise | Status | Where it stands | | --- | --- | --- | | Learner-sovereign completion | Enforced | Lesson close requires the learner's own declaration; a Live session cannot reach completed before the learner rings the close bell (the completion gate is machine-checked; pre-bell teacher moves are not blocked). | | Terminal states are immutable | Implemented | State-machine guard on the read-then-write path; REST and MCP share the same semantics. Atomic conditional-update hardening against concurrent writers: Planned. | | Publish gate on both surfaces | Enforced | Same gate on the MCP tool and the REST PATCH path. Post-publish edits revalidate-then-compensate rather than run in a single transaction; transactional hardening: Planned. | | Data stays home by default | Enforced by default config | Server and Postgres bind loopback only; logs are redacted. Cross-device is an explicit opt-in; real authentication is Planned — targeted at the multi-device case (agent credential → principal → pair derivation → real-name audit trail), scheduled separately and not a full multi-tenant system. | | Real enrollment / first-run | Implemented | create_pair is the front door, behind the name-sovereign first-run page. Multi-client fresh-agent E2E in CI: Planned. | | Conversation as