Socratic Study Mentor

🧠 An AuDHD-aware study toolkit: Socratic questioning, content pipelines, spaced repetition, and AI session tracking.

What Does It Do?

Four things:

1. Socratic AI sessions — Body doubling with AI mentors that ask questions instead of giving answers. Energy-adaptive (low day? shorter chunks, more scaffolding).
2. Content pipeline — Chunk eBooks and Obsidian notes into Google NotebookLM notebooks → generate audio overviews, quizzes, and flashcards.
3. Flashcard review — Spaced repetition (SM-2) via a PWA web app. Works on phone, tablet, laptop.
4. Session tracking — Export AI coding sessions (Claude Code, Codex, Kiro, Gemini, OpenCode, and more) into a searchable SQLite database. Track trends, find struggle topics, search across sessions.

Built by a neurodivergent learner transitioning from networking to data engineering. If you're self-teaching and AuDHD, this might help.

Quick Start

# Install (preferred on macOS)
brew install NetDevAutomate/studyctl/studyctl

# Configure
studyctl setup              # Interactive 3-question wizard
studyctl doctor --fix       # Verify and apply safe fixes

# Use
studyctl content process SOURCE   # Split PDF → upload to NotebookLM
studyctl web                      # Launch flashcard/quiz PWA
session-export                    # Export AI sessions to SQLite
session-query search "decorators" # Search across all sessions

Architecture

graph LR
    subgraph "Study Materials"
        OB[Obsidian Vault]
        NLM[NotebookLM]
    end

    subgraph "CLI Tools"
        SC[studyctl]
        AST[agent-session-tools]
        DB[(SQLite DB)]
    end

    subgraph "AI Agents"
        CA[Claude Code]
        CX[Codex CLI]
        KA[Kiro CLI]
        GA[Gemini CLI]
        OA[OpenCode]
        OL[Ollama]
        LM[LM Studio]
    end

    subgraph "Live Session"
        IPC["IPC Files<br/>(state, topics, parking)"]
        SSE["Web Dashboard<br/>(SSE + HTMX)"]
    end

    OB -->|sync| SC
    SC -->|upload| NLM
    SC -->|spaced repetition| DB
    AST -->|export sessions| DB
    CA -->|Socratic sessions| DB
    CX -->|Socratic sessions| DB
    KA -->|Socratic sessions| DB
    GA -->|Socratic sessions| DB
    OA -->|Socratic sessions| DB
    OL -->|Socratic sessions| DB
    LM -->|Socratic sessions| DB
    CA -->|writes| IPC
    IPC -->|polls| SSE

Loading

CLI Reference

studyctl

# Study sessions (tmux + AI agent + sidebar)
studyctl study "topic" --energy 7      # Full tmux environment in one command
studyctl study "topic" --web           # Also start web dashboard + auto-open browser
studyctl study "topic" --lan           # LAN access with password auth (implies --web)
studyctl study "topic" --lan --password SECRET  # Explicit LAN password
studyctl study --resume                # Resume conversation from history
studyctl study --end                   # End session (quit Claude also works)
studyctl park "question"               # Park tangential topic

# Content pipeline
studyctl content split SOURCE       # Split PDF by chapters
studyctl content process SOURCE     # Split + upload to NotebookLM
studyctl content autopilot          # Generate next pending episode
studyctl content from-obsidian DIR  # Markdown → PDF → NotebookLM

# Review
studyctl review                     # Check spaced repetition due dates
studyctl struggles --days 30        # Find recurring struggle topics
studyctl web                        # Launch flashcard/quiz PWA

# Sync
studyctl sync [TOPIC] --all        # Sync notes to NotebookLM
studyctl status                     # Show sync status
studyctl topics                     # List configured topics

# Health & metrics
studyctl doctor                     # Check installation health
studyctl doctor --fix               # Apply safe automatic fixes
studyctl install agents             # Install AI agent definitions from source checkout
studyctl setup                      # Interactive configuration
studyctl session effectiveness      # Persona effectiveness over time

agent-session-tools

session-export                       # Export AI sessions to SQLite
session-export --sources claude codex
session-query search QUERY           # Full-text search across sessions
session-query list --since 7d        # List recent sessions
session-query stats                  # Database statistics
session-sync push/pull/sync HOST     # Cross-machine sync

Agent Support

Platform	Agent	Start With
Claude Code	socratic-mentor	/agent socratic-mentor
Codex CLI	AGENTS.md	codex in the project root
Kiro CLI	study-mentor	kiro-cli chat --agent study-mentor
Gemini CLI	study-mentor	gemini (auto-detected)
OpenCode	study-mentor	Tab to switch agent
Ollama	(local LLM)	studyctl study "topic" --agent ollama
LM Studio	(local LLM)	studyctl study "topic" --agent lmstudio

Web PWA

Launch with studyctl web. Accessible from any device on the network.

Flashcard review:

• SM-2 spaced repetition with source/chapter filter
• Session history with 90-day study heatmap
• Pomodoro timer, voice output, OpenDyslexic font toggle
• PWA installable — add to home screen

Live session dashboard (/session):

• Real-time activity feed via SSE (Server-Sent Events)
• Timer with energy-adaptive colour phases (green/amber/red)
• Topic counters (wins, parked, review)
• Session summary on completion
• Terminal panel — embedded ttyd iframe proxied same-origin at /terminal/ with draggable split-pane (stacked or side-by-side). Pop-out to new window and seamless return. HTTP Basic Auth when using --lan. Requires ttyd (optional but recommended).
• HTMX + Alpine.js — no build step

Optional Extras

pip install 'studyctl[all]'          # Everything
pip install 'studyctl[web]'          # FastAPI web UI
pip install 'studyctl[content]'      # PDF splitting + NotebookLM
pip install 'studyctl[notebooklm]'   # NotebookLM API client

# ttyd — web terminal (enables the terminal panel in the live dashboard)
brew install ttyd            # macOS
sudo apt install ttyd        # Linux (or build from source)

Documentation

• Setup Guide — installation and configuration
• Architecture — C4 diagrams and repo code map
• Content Pipeline — PDF/Obsidian to flashcards via NotebookLM
• TUI Sidebar Guide — terminal sidebar layout, timer, key bindings
• Web UI Guide — flashcards, quizzes, session dashboard, ttyd
• Agent Installation — per-platform agent setup
• System Overview — architecture and data flow diagrams
• AuDHD Learning Philosophy
• Voice Output Guide
• Contributing

Maintainer Tasks

For local contributor and release workflows, use just:

just test
just lint
just typecheck
just docs
just build-release
just release-check

Install just with:

brew install just

Generated Artefacts

🔍 Explore this project — AI-generated overviews via Google NotebookLM

🎧 Listen to the Audio Overview	Two AI hosts discuss the project — great for commutes
🎬 Watch the Video Overview	Visual walkthrough of architecture and concepts
🖼️ View the Infographic	Architecture and flow at a glance
📊 Browse the Slide Deck	Presentation-ready project overview

Generated by notebooklm-repo-artefacts

License

MIT