studyOS

Plugin Claude Code pour réviser ses cours : il transforme les PDF de cours en notes Obsidian, génère des quiz de révision à partir de ces notes, les fait passer dans une page web locale, les corrige et suit ta progression.

Pensé pour des cours EPFL (semestres Ba1…Ma4), en français, testé sous Linux.

Skill	Rôle	Comment l'utiliser
obsidian-lecture-notes	PDF de cours → section # Week N dense et structurée dans le Notes.md du cours, avec les figures utiles	« Fais les notes de <chemin du PDF> »
course-quiz	Notes d'une ou plusieurs semaines → quiz en deux parties (Concept puis Approfondir) avec correction ; corrige aussi une tentative	« Fais-moi un quiz sur Micro semaine 2 », « Corrige mon quiz »
launch-quizz	Lance le serveur local des quiz et ouvre le navigateur	/launch-quizz
stop-quizz	Arrête le serveur	/stop-quizz

PDF du cours ──obsidian-lecture-notes──▶ Notes.md (vault Obsidian)
                                            │
                                       course-quiz
                                            ▼
                     quizzes/W02/quiz.json ──/launch-quizz──▶ page web : passer le quiz
                                                                   │
                                                          attempts/*.json
                                                                   │
                                         « corrige mon quiz » ◀────┘
                                                   ▼
                                  feedback + tableau de bord de maîtrise

Prérequis

• Claude Code avec le support des plugins (testé avec la version 2.1.276).
• Python 3 (testé avec 3.12). Les scripts n'utilisent que la bibliothèque standard, sauf figure.py, qui a besoin de Pillow.
• poppler-utils (pdfinfo, pdftotext, pdftoppm) pour lire les PDF.
• jq pour les hooks de /launch-quizz et /stop-quizz.
• Un vault Obsidian organisé comme décrit plus bas.

Sous Ubuntu / Debian :

sudo apt install python3 python3-pil poppler-utils jq

Installation

Choisis une des deux méthodes (pas les deux, sinon les skills apparaissent en double).

Méthode A : depuis GitHub (pour l'utiliser)

Dans Claude Code :

/plugin marketplace add ssidimoto/studyOS
/plugin install studyOS@studyOS
/reload-plugins

Ou depuis un terminal :

claude plugin marketplace add ssidimoto/studyOS
claude plugin install studyOS@studyOS

Mise à jour : claude plugin marketplace update studyOS && claude plugin update studyOS@studyOS.

Méthode B : en clonant le dépôt (pour le modifier)

Claude Code charge automatiquement tout plugin placé dans ~/.claude/skills/ :

git clone git@github.com:ssidimoto/studyOS.git ~/.claude/skills/studyOS

Puis /reload-plugins (ou une nouvelle session). Le plugin apparaît comme studyOS@skills-dir, et tes modifications sont prises en compte directement. Mise à jour : git pull.

Optionnel, pour avoir launch-quizz et stop-quizz comme commandes du terminal :

ln -s ~/.claude/skills/studyOS/bin/launch-quizz ~/.local/bin/launch-quizz
ln -s ~/.claude/skills/studyOS/bin/stop-quizz ~/.local/bin/stop-quizz

Vérifier l'installation

claude plugin details studyOS@studyOS      # méthode A
claude plugin details studyOS@skills-dir   # méthode B

Tu dois voir 4 skills et 2 hooks. Dans Claude Code, les skills s'appellent studyOS:course-quiz, studyOS:obsidian-lecture-notes, etc.

Organisation des dossiers attendue

Le plugin travaille avec deux dossiers : le dossier des cours (PDF et quiz) et le vault Obsidian (notes).

~/Documents/EPFL/                      ← dossier des cours (QUIZ_ROOT)
├── Ma1/                               ← semestre : Ba1…Ba6, Ma1…Ma4 (facultatif)
│   └── Micro/                         ← un dossier par cours
│       ├── Micro_Ch1_Intro.pdf
│       └── quizzes/                   ← créé par course-quiz
│           └── W01/
│               ├── quiz.json          ← source de vérité du quiz
│               ├── quiz.md
│               ├── correction.md
│               └── attempts/*.json    ← tes tentatives
└── .course-quiz/                      ← conversations du chat (créé automatiquement)

~/Documents/obsidian-repo/             ← vault Obsidian (QUIZ_VAULT)
├── Index & MOCs/
│   └── 0201 Micro MOC.md              ← une MOC par cours : « 02NN <Cours> MOC.md »
├── My very Big Second Brain/EPFL/Ma1/Micro/
│   └── Notes.md                       ← sections « # Week 1 », « # Week 2 »…
└── attachments/Micro/                 ← figures extraites des PDF

Quelques règles importantes :

• Dossiers de cours. Un dossier de cours se trouve soit directement dans le dossier des cours, soit dans un dossier de semestre dont le nom commence par Ba ou Ma suivi d'un chiffre.
• MOC. Chaque cours a une MOC (Map of Content) dans Index & MOCs/, nommée 02NN <Cours> MOC.md (0200 est réservé). Son nom doit ressembler à celui du dossier du cours : c'est ce qui permet à course-quiz de faire le lien.
• Notes. Une note est rattachée à un cours si ses 6 premières lignes contiennent links [[02NN <Cours> MOC]], ou si la MOC contient un lien vers elle.
• Semaines. Chaque semaine de cours est une section de premier niveau # Week N. obsidian-lecture-notes les crée dans ce format, et course-quiz s'en sert pour choisir la matière d'un quiz.

Configuration

course-quiz

Les chemins et réglages se changent avec des variables d'environnement :

Variable	Défaut	Rôle
QUIZ_ROOT	~/Documents/EPFL	dossier des cours
QUIZ_VAULT	~/Documents/obsidian-repo	vault Obsidian
QUIZ_CHAT_MODEL	sonnet	modèle utilisé par le chat de la page web
QUIZ_CHAT_EFFORT	(aucun)	niveau d'effort du chat
QUIZ_CHAT_TIMEOUT	600	durée maximale d'une réponse du chat, en secondes
QUIZ_CHAT_MAX_PROCS	2	nombre de réponses du chat en parallèle
QUIZ_CHAT_MAX_TURNS	12	--max-turns passé à Claude pour le chat
QUIZ_CHAT_CWD	<QUIZ_ROOT>/.course-quiz	dossier de travail des conversations
QUIZ_CLAUDE_BIN	(recherche automatique)	chemin de l'exécutable claude

Mets-les dans le bloc env de ~/.claude/settings.json, pour Claude Code et les hooks :

{
  "env": {
    "QUIZ_ROOT": "/home/moi/Cours",
    "QUIZ_VAULT": "/home/moi/Obsidian"
  }
}

Si tu lances launch-quizz depuis un terminal, exporte-les aussi dans ton ~/.bashrc.

obsidian-lecture-notes

Ce skill ne lit pas de variables d'environnement : ses chemins sont écrits dans la section Chemins de skills/obsidian-lecture-notes/SKILL.md (vault, emplacement de Notes.md, figures, MOC). Si ton vault est organisé autrement, modifie cette section (méthode B).

Tutoriel

1. Prendre des notes à partir d'un PDF

Dans Claude Code :

Fais les notes de ~/Documents/EPFL/Ma1/Micro/Micro_Ch2_Demand.pdf

Claude :

1. propose un numéro de semaine (la dernière # Week N du Notes.md + 1) et te demande de le confirmer ;
2. lit le PDF page par page ;
3. ajoute une section # Week 2 à la fin du Notes.md du cours, ou crée la note si elle n'existe pas ;
4. extrait les figures qui portent de l'information dans attachments/Micro/ ;
5. vérifie la note (figures présentes, formules bien fermées, titres).

Les règles d'écriture des notes sont dans skills/obsidian-lecture-notes/writing-rules.md.

2. Générer un quiz

Fais-moi un quiz sur Micro semaine 2

Claude retrouve le cours et la note, lit toute la section de la semaine et prépare un plan de couverture. Il écrit ensuite le quiz dans ~/Documents/EPFL/Ma1/Micro/quizzes/W02/ :

• Concept : définitions et notions, pour vérifier que tu connais le cours ;
• Approfondir : intuition, mécanismes, application à un cas nouveau, pour vérifier que tu l'as compris.

Autres formulations possibles : « quiz sur Micro semaines 1 à 3 », « un quiz court sur la semaine 4 ». Si la note n'a pas de titre # Week N, Claude te montre les titres existants et te demande quelle partie prendre.

3. Passer le quiz

/launch-quizz

Le serveur démarre et ton navigateur s'ouvre sur http://127.0.0.1:8765 :

• Index : tous tes quiz, tous cours confondus, et tes tentatives.
• Parties : tu passes Concept, Approfondir, ou les deux d'un coup. Ton brouillon est sauvegardé dans le navigateur.
• 💡 Indice : sur chaque question. Claude n'a pas accès à la correction dans ce mode, et les indices demandés sont comptés dans la tentative.
• Fin du quiz : tu vois la correction et tu t'auto-corriges avec le barème. La tentative est enregistrée dans attempts/.

Le serveur n'écoute que sur ta machine (127.0.0.1). Un seul serveur sert tous les quiz, et les nouveaux quiz apparaissent sans le redémarrer.

4. Faire corriger par Claude

Corrige mon quiz de Micro

Claude note les questions ouvertes et écrit son retour dans le fichier de la tentative. Il te donne :

• ton score par partie ;
• tes 3 concepts les plus faibles, avec les sections et les pages à relire ;
• l'écart entre ton auto-correction et la sienne ;
• une prochaine étape conseillée ;
• le lien vers la page de résultats.

5. Suivre ta progression

• /dashboard : maîtrise par thématique et sous-thématique, progression dans le temps, quiz complétés.
• 💬 : ouvre un chat avec ton Claude Code local, en lecture seule, qui connaît tes quiz, tes tentatives et tes notes. Tu peux discuter d'une question corrigée ou d'une thématique depuis le tableau de bord. Les conversations se reprennent avec claude --resume depuis <QUIZ_ROOT>/.course-quiz/.

Le chat utilise ta CLI claude : il consomme ton quota Claude Code.

6. Arrêter le serveur

/stop-quizz

Comment marchent /launch-quizz et /stop-quizz

Ces deux commandes ne passent pas par le modèle : elles répondent instantanément et ne consomment aucun token. Deux hooks (hooks/hooks.json) interceptent la commande :

• UserPromptSubmit : se déclenche à chaque message envoyé, avant Claude. Le script regarde si le texte entier est /launch-quizz (ou /studyOS:launch-quizz).
• UserPromptExpansion : se déclenche quand une commande slash est remplacée par le contenu de son skill. Le script regarde le nom de la commande.

Si c'est la bonne commande, le script lance bin/launch-quizz (ou bin/stop-quizz) et renvoie {"decision": "block", "reason": "<sortie>"} : le message n'est pas envoyé au modèle et la sortie du script s'affiche. Sinon, il ne fait rien.

Si les hooks ne fonctionnent pas (par exemple parce que jq manque), le skill prend le relais : Claude lance le script lui-même. Ça marche, mais c'est plus lent et ça consomme des tokens.

Le log du serveur est dans ~/.cache/course-quiz/serve.log.

Structure du dépôt

studyOS/
├── .claude-plugin/
│   ├── plugin.json            ← manifeste du plugin
│   └── marketplace.json       ← permet « /plugin marketplace add ssidimoto/studyOS »
├── bin/
│   ├── launch-quizz           ← lance serve.py en arrière-plan et ouvre le navigateur
│   └── stop-quizz             ← arrête serve.py
├── hooks/
│   ├── hooks.json
│   ├── launch-quizz-hook.sh
│   └── stop-quizz-hook.sh
└── skills/
    ├── course-quiz/
    │   ├── SKILL.md           ← instructions pour Claude
    │   ├── question-design.md ← règles de conception des questions
    │   ├── schema.md          ← format des fichiers et API du serveur
    │   ├── scripts/           ← quiz.py (CLI), serve.py (serveur), stats, chat…
    │   ├── assets/            ← page web (HTML, JS, CSS, KaTeX)
    │   └── tests/
    ├── obsidian-lecture-notes/
    │   ├── SKILL.md
    │   ├── writing-rules.md   ← règles d'écriture des notes
    │   └── scripts/           ← prep.sh, figure.py, check.py
    ├── launch-quizz/SKILL.md
    └── stop-quizz/SKILL.md

Tests

python3 -m unittest discover skills/course-quiz/tests

Les tests écrivent uniquement dans des dossiers temporaires et utilisent une fausse CLI claude : ils ne modifient ni tes cours ni ton historique Claude Code.

Limites

• Les skills et la page web sont en français.
• Les conventions (semestres Ba/Ma, MOC 02NN, sections # Week N) viennent d'un vault précis : adapte l'organisation de tes dossiers ou les chemins décrits plus haut.
• bin/launch-quizz et bin/stop-quizz utilisent setsid et pgrep : ils sont prévus pour Linux.