███████╗████████╗██╗ ██╗██████╗ ██╗ ██╗ ██╗ ██████╗ ██████╗██╗ ██╗
██╔════╝╚══██╔══╝██║ ██║██╔══██╗╚██╗ ██╔╝ ██║ ██╔═══██╗██╔════╝██║ ██╔╝
███████╗ ██║ ██║ ██║██║ ██║ ╚████╔╝ ██║ ██║ ██║██║ █████╔╝
╚════██║ ██║ ██║ ██║██║ ██║ ╚██╔╝ ██║ ██║ ██║██║ ██╔═██╗
███████║ ██║ ╚██████╔╝██████╔╝ ██║ ███████╗╚██████╔╝╚██████╗██║ ██╗
╚══════╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚══════╝ ╚═════╝ ╚═════╝╚═╝ ╚═╝
The AI study agent that locks you in, teaches you properly, and won't let you leave until you actually understand it. Runs 100% locally. No cloud. No subscription. No excuses.
You know that feeling where you open a YouTube tutorial, watch 4 minutes, think "wait let me just check one thing", and then 45 minutes later you're watching a video about why cats hate water?
That's not a willpower problem. That's a missing accountability loop.
Study Lock is a terminal app that:
- Takes any learning resource — a YouTube video, a PDF, a website, raw notes
- Reads it completely and chunks it into digestible topic sections
- Locks your terminal into fullscreen (you can't
Ctrl+Cyour way out) - Assigns you one of 4 AI teacher personas who teach each chunk their way
- Won't let you advance until you score 70+ on a comprehension question
- Tracks exactly which concepts you're weak on and hammers those specifically
- Unlocks you when the session is done — with a full breakdown of what you know and what needs work
The timer is a soft deadline. If it runs out mid-chunk, you still have to clear that chunk. The material wins. Always.
_ _____ __________ * . * . *
__/ \__ [=o=o=] [##########] . ( ) .
/ o o \ / \___/ \ | > < | * ( o . o ) *
| w | | ' ___ ' | | ____ | . \ ___ / .
\_______/ | ( ) | | ( __ ) | * . . *
| | \_______/ |__________| * * * * *
~~| |~~ | | | | | |
/ \ _|___|_ _|_|_
Sensei Sam Prof. Maya Drill Sgt. Rex The Oracle
────────── ────────── ────────────── ──────────
Gentle Rigorous Demanding Adaptive
Calm analogies, Socratic method, Dense. Direct. Watches your
walks you through expects you to No fluff. Calls answers and
it like a friend reason, not out vague answers adjusts the
over coffee just recall immediately whole session
Pick one at the start. Your choice sets the entire tone of the session — how concepts are explained, how questions are framed, how feedback lands.
You paste a resource
│
▼
┌─────────────────────────────────────────────────────────────┐
│ INGEST │
│ YouTube → transcript API │
│ Website → article extraction (strips nav, ads, footer) │
│ PDF → full text via PyMuPDF │
│ DOCX → paragraph extraction │
│ Text → used directly │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SMART CHUNKER │
│ Strips filler words, timestamps, transcript noise │
│ Detects topic transitions ("now let's look at...", │
│ "the next thing...", "in other words...") │
│ Groups into ~700-word topic chunks with 80-word overlap │
│ Labels each chunk with a topic hint │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SESSION LOCK │
│ Terminal goes fullscreen via AppleScript │
│ Ctrl+C blocked with a reminder message │
│ Background timer thread starts countdown │
└─────────────────────┬───────────────────────────────────────┘
│
┌────┴────┐
│ CHUNK │ ◄──────────────────────────────┐
└────┬────┘ │
│ │
┌───────────▼───────────┐ │
│ TEACH │ │
│ Persona reads chunk │ │
│ Teaches from OWN │ │
│ knowledge (material │ │
│ is a reference, not │ │
│ a script) │ │
│ Streams token-by- │ │
│ token live │ │
└───────────┬───────────┘ │
│ │
┌───────────▼───────────┐ │
│ QUESTION │ │
│ Generated based on │ │
│ concept + your known │ │
│ weak areas │ │
└───────────┬───────────┘ │
│ │
┌───────────▼───────────┐ │
│ YOUR ANSWER │ │
└───────────┬───────────┘ │
│ │
┌───────────▼───────────┐ score < 70 │
│ EVALUATE ├─────────────────────────┤
│ Score 0–100 │ rephrase question │
│ Specific feedback │ every 3 fails │
│ Records weak areas │ │
└───────────┬───────────┘ │
│ score ≥ 70 │
▼ │
┌───────────────────────┐ more chunks? │
│ CHUNK CLEARED ✓ ├──── yes ─────────────────┘
└───────────────────────┘
│ no more chunks
▼
SESSION SUMMARY + UNLOCK
- macOS (fullscreen lock uses AppleScript — on other OS the session still works, just no forced fullscreen)
- Python 3.11+
- Ollama (runs Gemma locally — no internet needed after initial setup)
- ~10GB disk space for the Gemma model
# Install Ollama (macOS)
brew install ollama
# Start the Ollama server in the background
ollama serve &
# Pull Gemma 4 (~10GB, one-time download — go make a coffee)
ollama pull gemma4Why Gemma? It's Google's open-weights model that runs well on consumer hardware. If you have a different model already pulled, you can use that instead — see the Model Options section below.
# Navigate into the project folder
cd study-lock-v2-improved
# Create a virtual environment (keeps your system Python clean)
python3 -m venv venv
# Activate it
source venv/bin/activate
# Install all dependencies
pip install -r requirements.txtYou'll see (venv) appear in your terminal prompt. That means you're inside the virtual environment. Every time you open a new terminal to use Study Lock, run source venv/bin/activate again first.
python main.pyThat's it. The app takes over from here.
What's your name? → Ray
Source? → https://youtu.be/lfmg-EJ8gm4
→ /Users/ray/notes.pdf
→ https://docs.python.org/3/tutorial/
→ (paste raw text directly)
Duration? → 30 (minutes)
Teacher? → 1 (Sensei Sam)
→ 2 (Prof. Maya)
→ 3 (Drill Sgt. Rex)
→ 4 (The Oracle)
Then you're locked in.
By default the app uses gemma4. You can swap any Ollama model in:
# Use Gemma 3 (smaller, faster)
STUDY_MODEL=gemma3 python main.py
# Use Llama 3.2
STUDY_MODEL=llama3.2 python main.py
# Use Mistral
STUDY_MODEL=mistral python main.pyOr change the default permanently — open main.py and find this line near the top:
MODEL = os.environ.get("STUDY_MODEL", "gemma4")Replace "gemma4" with whatever model you want.
To see what models you have pulled:
ollama listWhen a session starts, the app fires an AppleScript that sets AXFullScreen = true on whatever terminal window is active. This works with Terminal.app and iTerm2.
For this to work, you need to grant Accessibility access once:
System Settings → Privacy & Security → Accessibility → enable Terminal (or iTerm2)
If you skip this, the session still runs — it just won't force fullscreen. You'd be on the honour system.
During the session, Ctrl+C is intercepted. Instead of killing the process, it prints:
⚡ Ctrl+C blocked during study session.
To exit early, type: "i commit to finishing"
Yes, the exit phrase is ironic on purpose.
| Type | Example |
|---|---|
| YouTube | https://youtu.be/dQw4w9WgXcQ · https://youtube.com/watch?v=... |
| Website | https://docs.python.org/3/tutorial/ · any article URL |
/Users/ray/Downloads/lecture.pdf |
|
| Word doc | /Users/ray/notes.docx |
| Plain text | Just paste it directly at the source prompt |
YouTube note: The video needs English captions enabled (auto-generated is fine). If a video has no captions at all, you'll get an error — paste the transcript manually instead.
study-lock-v2-improved/
│
├── main.py ← Entry point. Onboarding, persona picker, session loop
│
├── requirements.txt ← All Python dependencies
│
├── content/
│ ├── ingester.py ← Pulls text from YouTube / websites / PDFs / DOCX / text
│ └── chunker.py ← Cleans transcript noise, detects topic boundaries,
│ groups into ~700-word chunks with topic labels
│
├── agents/
│ ├── personas.py ← 4 persona definitions: prompts, ASCII art, difficulty
│ └── study_agent.py ← Core loop: teach → question → evaluate → gate
│ Also contains WeaknessTracker
│
└── session/
└── manager.py ← Timer thread, fullscreen AppleScript,
Ctrl+C signal trap, session state
This is the part that makes Study Lock actually adaptive rather than just a fancy flashcard app.
Every time you answer a question, the app:
- Extracts a "concept label" from the question (strips stop words, keeps the 5 most meaningful words)
- Records your score against that concept
- On every subsequent
teachandquestioncall, if you have weak concepts (score < 65), that context is injected into the prompt:
Student has struggled with: 'recursion base case' (score: 32),
'stack frame allocation' (score: 45). Address these proactively.
The Oracle persona responds to this most aggressively — it'll pivot the entire explanation toward your gaps. Drill Sergeant Rex will specifically target your weak spots in the question. At the end of the session, your weak areas are listed in the summary so you know exactly what to review.
When you're done, you get a breakdown:
╭─────────────────── Session Summary ───────────────────╮
│ │
│ Ray — session complete! │
│ │
│ Material: Python Tutorial for Beginners │
│ Teacher: 🧘 Sensei Sam │
│ Time: 28.4 min │
│ Chunks: 4 / 6 │
│ Questions: 3 cleared / 4 asked │
│ Score: 75% — Good │
│ │
│ Solid session. Keep the momentum. │
│ │
│ Watch out for: 'variable scope closures' (score 41) │
│ │
╰────────────────────────────────────────────────────────╯
| Package | What it does |
|---|---|
ollama |
Talks to your local Ollama server |
rich |
All the terminal UI — panels, spinners, score bars, colour |
youtube-transcript-api |
Pulls captions from YouTube videos |
requests + beautifulsoup4 |
Fetches and parses websites |
readability-lxml |
Extracts the article content from a webpage (strips nav, ads, sidebars) |
PyMuPDF |
Extracts text from PDFs page by page |
python-docx |
Reads Word documents |
Everything runs locally. After the initial pip install and model pull, this works fully offline.
Could not connect to Ollama
# Ollama isn't running. Start it:
ollama serve
# (run this in a separate terminal tab, or add & to background it)Model 'gemma4' not found
ollama pull gemma4
# or check what you have:
ollama list
# then run with a model you actually have:
STUDY_MODEL=gemma3 python main.pyNo English transcript available
The video doesn't have English captions. Either find a video that does, or copy-paste the transcript manually at the source prompt.
Fullscreen doesn't work
Go to System Settings → Privacy & Security → Accessibility and enable your terminal app. Or just manually fullscreen your terminal before starting — same effect.
(venv) disappeared from my prompt
Your virtual environment got deactivated (new terminal tab, shell restart). Run:
source venv/bin/activateMost study tools optimise for engagement. Study Lock optimises for one thing: did you actually understand it?
The comprehension gate (score 70+ to advance) means you can't passively consume. The weakness tracker means the session responds to your actual gaps, not a generic curriculum. The fullscreen lock means your phone-checking reflex has to fight the OS rather than just your willpower.
It's not supposed to be fun the way scrolling is fun. It's supposed to feel like the good kind of hard — the kind where you close the terminal and actually know something you didn't know before.
MIT — do whatever you want with it.
Built with Ollama + Gemma + Rich. Runs entirely on your machine.