{"id":"6a6ce1e5-144a-48b2-ac89-d466d29b331f","slug":"ai-tutor-bot","kind":"skill","name":"ai-tutor-bot","summary":"An AI tutor prototype that uses Obsidian notes and iMessage check-ins to help interrupted study resume.","owner":"cheryljia27-commits","repoUrl":"https://github.com/cheryljia27-commits/ai-tutor-bot","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-23T07:44:34.000Z","addedAt":"2026-10-21T11:17:07.431Z","logoUrl":"https://avatars.githubusercontent.com/u/250459068?u=3cf9291147633f25cf5288949ae5296ca49705be&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","productivity"],"tags":["ai-tutor","education","karpathy","llm","python","self-directed-learning","imessage","obsidian"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T03:59:17.824Z","sample":false,"url":"https://conduits.dev/tools/ai-tutor-bot","language":"Python","transports":["stdio"],"install":{"pypi":"ai-tutor-bot"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# AI Tutor Bot\n\n[![CI](https://github.com/cheryljia27-commits/ai-tutor-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/cheryljia27-commits/ai-tutor-bot/actions/workflows/ci.yml)\n\nThis repository contains the public version of the AI Tutor Bot I first shared\non X. It shows the reusable parts of the project without publishing my private\nnotes, contact details, or credentials.\n\nThe private prototype reads the learner's current state and Obsidian course\nnotes twice a day. It sends one focused prompt through iMessage based on the\ncurrent notes and source material, then follows up briefly when the learner\nreplies. The teaching still comes from the original course; the bot simply\nhelps the learner find a way back after an interruption.\n\n<a href=\"assets/demo.mp4\">\n  <img src=\"assets/demo-poster.png\" width=\"280\" alt=\"AK Tutor Bot iMessage re-entry prototype\">\n</a>\n\n*An 8.5-second, anonymized recording of the original `AK · Tutor Bot` loop:\nnotification → iMessage anchor → learner reply → brief follow-up → Obsidian\ncourse note. Click the image for the H.264 video.*\n\n## Origin\n\nI built the original AI Tutor Bot for myself while working through Andrej\nKarpathy's online courses. The material was not the problem. After a study\nsession was interrupted, the source and notes were still there, but the plan\noften did not restart itself. I had to reconstruct what I understood, where\nthe explanation had broken down, and what the smallest useful next step should\nbe.\n\nThe prototype tested a narrower idea:\n\n> AI does not need to perform the understanding for the learner. It can\n> preserve one concrete way back into the learning process.\n\nWhat changed was not what I could access once I sat down. It was what happened\nbefore I sat down. The system did not make the course easier; it made the first\nstep back into the course smaller. I think of it as a small **continuation\nlayer for learning**.\n\nThe private system used an Obsidian state file, the current raw course note,\nscheduled morning and evening triggers, and an iMessage read/send bridge. This\nrepository publishes the reusable and inspectable parts without exposing\nprivate notes, contact identifiers, or transport credentials.\n\n## The loop shared on X\n\n```mermaid\nflowchart LR\n  A[\"Public teaching source\"] --> B[\"Obsidian note + learner state\"]\n  B --> C[\"Morning / evening trigger\"]\n  C --> D[\"iMessage re-entry point\"]\n  D --> E[\"Brief reply and follow-up\"]\n  E --> F[\"Desktop source + note artifact\"]\n  F --> B\n```\n\nThe key behavior is not “send a reminder.” The tutor must:\n\n- read the current learning state instead of inventing a generic topic;\n- choose one focused prompt based on the current notes and source material;\n- keep the exchange on the phone brief;\n- stop after a brief follow-up rather than maximizing conversation;\n- bring the learner back to the original material and leave behind a useful\n  note or small piece of work.\n\nThe sanitized morning interaction from the demo is:\n\n```text\n☀️ No need to rebuild the plan this morning.\n\nYour note already points back to tool use and web search.\n\nJust rewatch that bit and make one sentence less vague.\n```\n\nAfter the learner replies that the section is still fuzzy:\n\n```text\nGood. Make the sentence say what the model checked, not just what tool use does.\n```\n\nSee the complete evening anchor, morning re-entry, learner replies, and desktop\nartifact in\n[`examples/sanitized-tutor-loop.md`](examples/sanitized-tutor-loop.md).\n\n## What this public repository implements\n\nThe private iMessage scheduler is not published. The repository packages the\nparts that make the behavior inspectable and reusable:\n\n| Layer | What it does | Where to inspect |\n| --- | --- | --- |\n| Sanitized tutor loop | Reconstructs the interaction and desktop artifact shown in the demo | [`examples/sanitized-tutor-loop.md`](examples/sanitized-tutor-loop.md) |\n| Agent Skill | Interprets notes and selects one bounded, source-grounded re-entry action | [`skill/ai-tutor-bot/SKILL.md`](skill/ai-tutor-bot/SKILL.md) |\n| Deterministic core | Validates learner state, previews messages, records progress, and checks message invariants | [`src/ai_tutor_bot/`](src/ai_tutor_bot/) |\n| Source pack | Maps 14 creator-owned public sources to teaching moves and minimum artifacts | [`source-packs/karpathy-ai-systems/course-map.md`](source-packs/karpathy-ai-systems/course-map.md) |\n| Seed eval set | Exercises a valid re-entry, generic encouragement, and persona simulation | [`examples/eval-set.json`](examples/eval-set.json) |\n\nNo model API or key is required to verify the public reference core.\n\n## Verify it in three minutes\n\nRequires Python 3.10 or newer.\n\n```bash\ngit clone https://github.com/cheryljia27-commits/ai-tutor-bot.git\ncd ai-tutor-bot\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e \".[dev]\"\n\npytest\nai-tutor-bot next --state examples/learner-state.json\nai-tutor-bot eval --state examples/learner-state.json\n```\n\nExpected: the tests pass, the generated message cites a primary source, and\nthe evaluation label is `pass`.\n\n## Deterministic CLI example\n\nGiven the synthetic state in\n[`examples/learner-state.json`](examples/learner-state.json), the deterministic\npreview produces:\n\n```text\nDon't restart the whole course. Return to “tool use and web search”:\nExplain what the model checked, not only what tool use does. Spend 10 minutes\non one artifact: Rewrite one sentence in notes/tool-use.md.\nCheck: The sentence names both the external action and the returned evidence.\nSource: Deep Dive into LLMs like ChatGPT → https://www.youtube.com/watch?v=7xTGNNLPyMI\n```\n\nThe public CLI makes the core behavior easy to inspect and test; it does not\nreplace the private system that sends the messages automatically. Its `eval`\ncommand checks the current loop, artifact, completion condition, timebox,\nprimary-source URL, response size, and whether the bot avoids imitating a real\nperson.\n\n## Use it as an Agent Skill\n\nInstall the bundled skill without silently merging it into an older copy:\n\n```bash\ndestination=\"$HOME/.codex/skills/ai-tutor-bot\"\nmkdir -p \"$(dirname \"$destination\")\"\nif [ -e \"$destination\" ]; then\n  echo \"Already exists: $destination\"\nelse\n  cp -R skill/ai-tutor-bot \"$destination\"\nfi\n```\n\nThen invoke it with a note or learner-state file:\n\n```text\nUse $ai-tutor-bot to turn this interrupted course note into one\nsource-grounded re-entry point and a small learning artifact.\n```\n\nThe skill supports three modes:\n\n- re-enter an interrupted course or lecture;\n- understand one mechanism through a tiny inspectable artifact;\n- review an artifact using an observable pass/fail check.\n\n## Product and identity boundaries\n\n- The message is a doorway, not the classroom or IDE.\n- The tutor points to a learning discontinuity; it does not act like a boss.\n- Learner history is used to select work, not to perform intimacy.\n- Specific claims cite a primary creator-owned source.\n- Teaching-pattern synthesis is labeled as interpretation.\n- The tutor never claims what Karpathy “would say,” imitates his voice, or\n  invents quotes.\n- Course videos, full transcripts, private notes, and contact metadata are not\n  redistributed.\n\n`AK · Tutor Bot` was the transparent contact label used in the original demo:\n`AK` marked the Karpathy-inspired source context, `Tutor` described the\ncourse-level role, and `Bot` kept the artificial boundary visible. The public\nproject name is **AI Tutor Bot**.\n\n## Repository map\n\n```text\nsrc/ai_tutor_bot/           deterministic state, message, progress, and eval CLI\nskill/ai-tutor-bot/         adaptive Agent Skill\nsource-packs/               curated primary-source learning map\nexamples/                   sanitized loop, learner state, and seed eval cases\ndocs/                       product thesis, architecture, and evaluation rubric\ntests/                      state, CLI, behavior, and source-pack checks\n.github/workflows/          supported-version and installed-wheel verification\nassets/                     anonymized original interaction prototype\n```\n\nFor the deeper reasoning, see\n[`docs/product-thesis.md`](docs/product-thesis.md),\n[`docs/architecture.md`](docs/architecture.md), and\n[`docs/evaluation.md`](docs/evaluation.md).\n\n## Status\n\n`v0.1.0` is a sanitized reference implementation of the AI Tutor Bot. It\ndocuments the original proactive loop and ships its reusable state, Skill,\nsource-grounding, progress, and evaluation layers. It does not ship the private\nObsidian vault, production scheduler, iMessage bridge, or personal message\nhistory.\n\nThe open product question is whether the system selects the right re-entry\npoint and reliably causes one useful learning artifact, not whether it can\nsustain a long chat.\n\n## License and attribution\n\nOriginal code and documentation are MIT licensed. Public source links and\nthird-party titles belong to their respective owners. See [NOTICE.md](NOTICE.md).\n"}