Learn Shell is a native teaching operating system for agents, with the goal of providing a "classroom" where an AI's teaching intent can actually be learned, practiced, and accepted by learners. It does not replace the AI that users talk to every day, but instead gives its teaching behavior a place to land: courses, lessons, flashcards, graded exercises, mind maps, a document reader, and a memory layer that agents can read back. Teachers can switch conversations or even switch models, and when they re-enter, the classroom remains as it was.
Purpose
Learn Shell turns an AI's teaching intent into concrete content that learners can actually study, practice, and be graded on. It solves the problem of chat windows lacking a "floor": teaching evidence evaporates with the context window, and every new conversation starts the teacher off as a stranger. Learn Shell provides a persistent place for teaching, allowing the teaching relationship to continue.
Main Capabilities
The system consists of an MCP server and a self-hosted web application. Teacher agents interact with the system through MCP (currently about 50 tools, data resources, and a composable skills/prompts layer); humans access it through the ordinary web application, and both read and write the same data. The pages already online include: Courses, Lesson (course text + exercises + Live Teaching panel), Review (FSRS flashcard review), Cards (deck management), Journal (learning biography timeline), Quiz (agent-generated + real question bank), Mind Map, Document Reader, and Settings (identity, appearance, contract certificate and pacing, learner model, feedback ledger, data export).
The MCP surface is self-describing: the live-generated menu of tools, resources, prompts, and recipes can be read through the manifest://capabilities resource; mutation-type tools return structured success/error envelopes, and most tools (about 34/50) support an optional idempotency_key to make retries safe. The teaching loop has actually been run: teach → grade exercises → form hypotheses → attribute based on evidence and counterfactual checks → revise the next lesson → revisions are visible to learners as Revised · v{n}. In addition, a teacher inbox is provided (get_teacher_inbox), listing pending items as an incremental to-do list, such as items to grade, Live sessions not yet reflected on, AdHoc messages not yet replied to, flashcard difficulties, unsigned contracts, etc., with each item suggesting the next tool to call. Live Teaching supports real-time turn-based sessions, online/offline bridging, and mid-lesson snapshot recovery.
How to Use
- Start the database: docker compose up -d (Postgres only; the application runs as a host process).
- Copy the environment variables: cp apps/server/.env.example apps/server/.env; DATABASE_URL has no default value in the code, and startup will be refused if it is missing.
- Install dependencies and migrate: pnpm install, then pnpm --filter @learn-shell/server db:migrate; optionally run pnpm --filter @learn-shell/server db:seed:demo to load demo data (a real CFA course, marked is_demo, not a real enrollment prerequisite).
- Run apps/server (:3000) and apps/web (:5173 development mode), open http://localhost:5173/lesson。
- Connect MCP: claude mcp add learn-shell -e DATABASE_URL="postgresql://learn_shell:learn_shell_dev@localhost:5432/learn_shell" -- pnpm -C /absolute/path/to/learn-shell --filter @learn-shell/server mcp (stdio transport, compatible with any MCP-capable client).
- First read manifest://capabilities, then fetch recipes on demand via recipe://<name>. If there is no active learner_agent_pair yet, real enrollment requires using the create_pair tool: the learner first enters their own name on the Web first-run page (name sovereignty; the agent must not fill it in on their behalf), and then the agent calls create_pair with that exact name.
Self-hosted cross-device access requires two explicit options to both be satisfied: HOST=0.0.0.0 and CORS_ORIGINS set correctly; otherwise it falls back to loopback-only binding and a localhost-only CORS allowlist.
Applicable scenarios
Suitable for individuals or single-machine environment users who already have a daily conversational AI and wish to persist its teaching behavior and form a complete teaching loop. Since 2026-07-02, the system has been continuously used in a real teaching relationship: one learner preparing for a real exam, with one agent serving as their teacher. Suitable for scenarios requiring lessons, exercise grading, flashcard review, and continuity of teaching memory.
Limitations
v1 uses a single-machine, unauthenticated trust model: the server binds to 127.0.0.1 by default, with no account system, no per-agent credentials, no scoped tokens, and no audit trail beyond "actor: mcp". Cross-device deployment is an explicit opt-in and should only be done within a trusted LAN; the server (REST or MCP stdio bridge) must never be exposed to the public internet. Real authentication is on the roadmap for multi-device scenarios, but is not yet implemented. The project is currently a working system and has been in continuous self-use since 2026-07-02; where documentation and code disagree, the code prevails. The 2026-07-28 MCP specification revision (stateless core, Apps and Tasks extensions) is on the roadmap watchlist, not yet committed. The interface is bilingual: documentation and receipts prioritize English, while MCP tool descriptions and pre-reports prioritize Chinese in v0.1, with full English localization on the roadmap.The interface is bilingual: documentation and receipts prioritize English, while MCP tool descriptions and pre-reports prioritize Chinese in v0.1, with full English localization on the roadmap.
