Your course. Your patterns. Your errors. Your cheatsheet.
A Codex plugin that turns your own materials into a permanent, editable, per-course study graph — every artifact shaped by you, not by a generic syllabus.
Original PAIDEIA coverage and interactive demo.
한국어 README · taewoopark.com — author site
The PAIDEIA family — one study engine, every agentic runtime
| Platform | Repository | What it is |
|---|---|---|
 |
PAIDEIA | The original — a Claude Code plugin. |
 |
PAIDEIA-codex | OpenAI Codex skills + bundled MCP server. |
 |
PAIDEIA-opencode | Command-line harness driving opencode. |
 |
PAIDEIA-Hermes | Hermes Agent plugin: CLI commands + gateway routing. |
 |
PAIDEIA-mcp | Standalone local MCP server — drive PAIDEIA from Alt local models. |
 |
PAIDEIA-Alt | Exam Radar — the Alt lecture-capture plugin (altalt.org). |
Generic study tools teach you the average syllabus. Paideia teaches you your syllabus —
from your professor's notes, your HW emphases, your handwriting, your errors. Every artifact is a markdown file you can edit.
In ancient Greece, Παιδεία was never the deposit of facts into a passive student. It was the lifelong formation of a complete human being — through structured encounter with primary texts, guided practice under a master, and reflective dialogue that folds feedback into deeper revision.
This plugin implements that cycle for the specific, bounded problem of exam preparation in math, physics, and engineering courses:
ingest ──▶ analyze ──▶ drill ──▶ grade ──▶ weakmap ──▶ cheatsheet
▲ │
└────────────────── feedback loop ───────────────────────┘
The study stages save Markdown artifacts in your course folder. You can keep reading, editing, and versioning those files independently of the agent. Generating new artifacts still requires the runtime, tools, and model used by the chosen stage.
Paideia starts with your course, your professor's assignments, and your mistakes. The input is the folder you bring: lecture notes, textbook chapters, homework, solutions, and scanned attempts.
Generic curricula and manually curated flashcards can be useful companions. Paideia adds a specific workflow: extract recurring moves from your solutions, rank practice by homework coverage, and feed recorded errors into the next drill. The table describes that workflow, rather than the features or subscription terms of every learning service.
| Axis | Paideia | A generic course or an unstructured chat |
|---|---|---|
Solution patterns (P1..Pk) |
Extracted from your course's solutions, with source citations | Requires course-specific material and instructions |
| Drill priority | Weighted by your professor's HW emphasis | Must be selected and maintained separately |
| Cheatsheet | Errors shape the traps section; the course index supplies references | Must be assembled and revised separately |
| Per-course state across sessions | Markdown + metadata files in the course folder | Depends on the service and how context is supplied |
| Editing an artifact you disagree with | Open the .md in any editor and save |
Depends on the tool's editing and export support |
| Carrying prep into another semester | Copy the course folder and revise the changed material | Requires moving the relevant material and history |
| Version history of your understanding | git log / git diff, when you commit the files |
Depends on the tool's versioning support |
| Where the artifacts live | Your disk, as text | Depends on the service |
The runner does the model work; the study graph remains yours to open, read, edit, and diff. Changing providers or pausing a subscription does not remove the files already produced.
Default answer OCR is codex-native: page images are read through the runner's vision path. For local answer OCR, install Ollama and qwen3-vl:8b, then explicitly select OCR_ENGINE: qwen3-vl in .course-meta or pass --ocr=qwen3-vl to grade. Downloading the model alone does not change the engine. tesseract is the other local option. Local OCR keeps that transcription step local; subsequent analysis and grading still use the configured model and may send it the transcribed text.
Homework is Paideia's primary signal for allocating exam-prep time. Sections with more assigned problems get more practice; sections without homework remain reference material by default. These are study-priority tiers, not measured probabilities or a guarantee of what the professor will test.
| Tier | HW count on section | Treatment | Target share of mock-exam points |
|---|---|---|---|
| 🔥🔥 Exam-primary | 3+ | Drill hardest | ≥70% |
| 🔥 Exam-likely | 2 | Drill next | ~25% |
| 🟡 Exam-possible | 1 | Warm-pass review | ≤5% |
| ⚪ Low-risk | 0 | Reference only | 0 by default |
$paideia-quiz all, $paideia-mock 90, and $paideia-hwmap hot use this ranking. These allocations are instructions to the generating agent; inspect the resulting mock before relying on its exact distribution. Explicit requests and imported Exam Radar signals can inform what you choose to review.
The Codex desktop app displays the generated Markdown artifacts alongside the conversation.
summary.md — $paideia-analyze
|
patterns.md — $paideia-analyze
|
coverage.md — $paideia-analyze
|
derivations/*.md — $paideia-derive
|
Type $paideia-… in a Codex conversation. The plugin supplies 16 skills and four MCP tools. The MCP server handles file inventory, PDF rendering, local OCR, baseline indexes, and phase detection; Codex performs native-vision transcription and the course-specific analysis, drills, and grading. $paideia-phase is the on-demand progress display. This package does not install PAIDEIA's Claude statusline or session-start hook.
| Stage | What it does | Verbs | Produces |
|---|---|---|---|
| Encounter | Read the professor's signal | $paideia-ingest |
converted/**/*.md — every lecture, textbook chapter, HW, solution, as clean markdown |
| Structure | Extract the grammar of the course | $paideia-analyze |
course-index/{summary,patterns,coverage}.md — topic tree, recurring solution patterns (P1..Pk), HW-density exam-tier ranking |
| Practice | Active recall weighted by assigned homework | $paideia-quiz, $paideia-twin, $paideia-blind, $paideia-chain, $paideia-mock |
quizzes/, twins/, chain/, mock/ — problems you solve on paper |
| Reflection | Your hand-written work becomes a grade | $paideia-grade |
answers/converted/<name>.md + errors/log.md — OCR via Codex's bundled vision (default), Qwen3-VL, or Tesseract; then strategy-based grading |
| Diagnosis | Errors compressed into a priority-ranked weakness report | $paideia-weakmap |
weakmap/weakmap_<ts>.md — append-only history |
| Distillation | One page, error-driven, printable | $paideia-cheatsheet, $paideia-derive, $paideia-pattern |
cheatsheet/final.md, derivations/<slug>.md — reference only what you actually need |
Supporting: $paideia-hwmap shows homework-based study priorities, $paideia-init-course bootstraps a fresh course folder, $paideia-phase reports which stage of the cycle the folder is in.
- Codex, with
codexonPATHand a working sign-in. The plugin reuses the session's model and vision access; it does not need a separate OCR API key. Normal account usage limits and billing still apply. - Python 3.10+ and a Unix-style shell (
bash/zsh). On Windows, use WSL2 for the shell workflow. - PDF rendering: macOS
brew install poppler; Debian/Ubuntuapt-get install poppler-utils. - For Tesseract OCR or fallback: install
tesseract tesseract-langwith Homebrew, ortesseract-ocr tesseract-ocr-eng tesseract-ocr-korwith apt. - For local Qwen OCR: install Ollama, run its local server, and
ollama pull qwen3-vl:8b(about 6 GB). Selectqwen3-vlexplicitly during bootstrap or grading.
The bundled MCP launcher checks Python imports and attempts to install its dependencies. If that fails, use a Python 3.10+ virtual environment and install mcp pdf2image pillow pypdf pytesseract reportlab httpx into the interpreter used as python3 by .mcp.json. The first server startup may need network access. Local Qwen OCR needs access to localhost:11434 under your Codex permissions.
Use the Codex desktop app to read generated Markdown beside the conversation. Install the plugin from a terminal:
codex plugin marketplace add https://github.com/OPTIMETA/PAIDEIA-codex.git
codex plugin add paideia@paideia-marketplaceOpen a fresh Codex task in your course folder after installation. The plugin supplies 16 $paideia-… skills and the paideia-mcp server configuration; Codex manages that server's lifecycle. If a session changes course folders, pass the new absolute project_root to MCP calls or start a fresh task in that course.
Run the same two marketplace commands above, then start codex inside the course folder. Type $paideia-init-course in the Codex conversation, not at your shell prompt. Pair the CLI with Obsidian for reading math.
$paideia-init-course
The skill checks dependencies, asks for the course name, exam date, exam type, weak zones, and OCR engine (codex-native / qwen3-vl / tesseract). It then:
- Creates the course directories and seeds
errors/log.md. - Writes
.course-metawithCOURSE_NAME,EXAM_DATE,EXAM_TYPE,USER_WEAK_ZONES, andOCR_ENGINE. - Creates
AGENTS.mdif absent, merges the managed.gitignoreentries, and initializes Git if needed.
Override answer OCR per call: $paideia-grade --ocr=codex-native answers/answer.pdf. The ingest skill also accepts --ocr=<engine>, --only=<categories>, and --force.
The study artifacts share the PAIDEIA layout, but runtime settings need review. Keep the existing Markdown and error history, add Codex's AGENTS.md, and select one of this edition's engine names. Map Claude's claude to codex-native and ollama to qwen3-vl.
This edition's bootstrap does not offer the original en/ko picker or write INTERFACE_LANG. Its bundled context and many skills request Korean prose. For another language, state that preference in the conversation and align AGENTS.md; adding INTERFACE_LANG alone does not implement a language switch. Re-running bootstrap rewrites .course-meta, leaves existing AGENTS.md intact, and preserves the existing error log.
After $paideia-init-course, your course folder looks like this:
my-course/
├── .course-meta # course name, exam date, OCR engine
├── AGENTS.md # project rules Codex reads every turn
├── .gitignore # hides raw answer PDFs, OCR scratch, optional PDF export
│
├── materials/ # YOU DROP RAW FILES HERE (PDF or MD)
│ ├── lectures/ # professor's notes, slide decks
│ ├── textbook/ # textbook chapters
│ ├── homework/ # HW problem sets
│ └── solutions/ # HW solutions / worked examples
│
├── converted/ # generated Markdown — back up edits before re-ingest
│ ├── lectures/ # output of $paideia-ingest (vision-transcribed LaTeX)
│ ├── textbook/
│ ├── homework/
│ └── solutions/
│
├── course-index/ # knowledge base — built by $paideia-analyze
│ ├── summary.md # topic tree (§1, §1.1, §2, …)
│ ├── patterns.md # recurring solution patterns, labeled P1, P2, …
│ ├── coverage.md # HW ↔ § map with 🔥🔥 / 🔥 / 🟡 / ⚪ exam tiers
│ └── radar.md # lecture-emphasis signal — imported by $paideia-alt
│
├── answers/ # YOU DROP HAND-WRITTEN SCAN PDFs HERE
│ └── converted/ # $paideia-grade writes OCR'd markdown here
│
├── errors/
│ └── log.md # append-only YAML error log (seed for /weakmap + /cheatsheet)
│
├── quizzes/ # $paideia-quiz — each problem has a hidden _answers.md sibling
├── mock/ # $paideia-mock — full mock exams (hidden _sol.md siblings)
├── twins/ # $paideia-twin — same pattern, new surface
├── chain/ # $paideia-chain — multi-pattern integration problems
├── derivations/ # $paideia-derive — clean reference derivations
├── cheatsheet/ # $paideia-cheatsheet — error-driven one-pager (+ optional PDF)
└── weakmap/ # $paideia-weakmap — timestamped, append-only history
Drop source files in materials/ and answer scans in answers/. All Markdown artifacts are editable; generation can overwrite derived files, so commit edits you want to preserve. Keep errors/log.md and the weakmap history: they record personal attempts that cannot be reconstructed from the source PDFs alone. Runtime context files and OCR engine names differ between editions; see the migration notes.
If you run Paideia from the Codex CLI rather than the Codex desktop app, this is the recommended companion. Paideia writes everything as plain markdown with LaTeX math ($...$, $$...$$); you can read it in any editor, but Obsidian is the natural choice:
- Renders
$...$and$$...$$math via MathJax with zero configuration - Backlinks let you click from
quizzes/q_<ts>.mdstraight into the citedconverted/lectures/chN.md §K - The whole course folder is just a vault — point Obsidian at
~/courses/my-course, and everything is a searchable graph - Works entirely offline, free, local. Consistent with Paideia's philosophy: your notes, your disk, your tool
VS Code with a markdown-math extension works too. The terminal — even with a markdown preview — is bad for math; don't fight that.
Obsidian is the companion at the reading end. Alt is the companion at the other end — where the lectures come in. Alt records and transcribes your lectures, and OPTIMETA's Exam Radar plugin runs inside it to rank topics by how strongly the professor emphasized them out loud. Send that into Paideia with $paideia-alt, and the loop closes: attend the lecture → capture it → extract the exam signal → study what matters. Lectures live in Alt, deep personal study lives in Paideia, and Exam Radar is the bridge — finally one continuous workflow instead of scattered tools.
cp ~/textbooks/ch*.pdf ~/courses/my-course/materials/textbook/
cp ~/lecture-notes/wk*.pdf ~/courses/my-course/materials/lectures/
cp ~/hw/hw*.pdf ~/courses/my-course/materials/homework/
cp ~/hw/hw*_sol.pdf ~/courses/my-course/materials/solutions/In Codex CLI:
$paideia-ingest # render PDFs via MCP, then transcribe with the selected engine
$paideia-analyze <weak-zone hints> # build patterns + coverage + summary
$paideia-hwmap hot # surface 🔥🔥 exam-primary zones
$paideia-quiz all 20 # broad diagnostic, 20 problems
# solve on paper (40 min), scan to answers/diagnostic.pdf
$paideia-grade # codex-native OCR (Codex reads the page images) + strategy grade
$paideia-weakmap # priority-ranked weakness report
$paideia-blind hw3-p2 # strategy-only drill on a known problem
$paideia-twin hw3-p2 # variant with same pattern, new surface
$paideia-chain 3 # multi-pattern integration problem
$paideia-quiz weakmap 5 # 5 problems targeting the latest weakmap
$paideia-mock 90 # full 90-min mock weighted by HW density
# solve on paper, scan, upload to answers/mock_<ts>.pdf
$paideia-grade # grade the mock
$paideia-cheatsheet --pdf # error-driven one-pager
$paideia-weakmap # review weak zones one more time
$paideia-weakmap # top 3 only. Do not learn new things.
This is the installed command inventory for this edition. It does not include the original's doctor, reindex, or graph commands.
| Verb | Purpose |
|---|---|
$paideia-init-course |
Bootstrap a fresh course folder (dep check, skeleton, metadata prompt, background ollama pull) |
$paideia-ingest [--force] |
PDF/MD materials → converted/**; MCP renders PDFs, then Codex vision or local OCR transcribes them |
$paideia-analyze [hints] |
Build course-index/{summary,patterns,coverage}.md |
$paideia-phase |
Show the current artifact-derived phase snapshot (setup → cool) |
$paideia-hwmap hot|<§> |
Surface 🔥🔥 Exam-primary sections ranked by HW density |
$paideia-pattern <§|Pk|keyword> |
Show pattern cards from course-index |
$paideia-derive <target> |
Clean reference derivation to derivations/<slug>.md |
$paideia-quiz <topic|§|weakmap> [N] |
N practice problems, answers hidden in sibling _answers.md |
$paideia-blind <problem-id> |
Strategy-check drill on a known problem (no re-solve, describe approach) |
$paideia-twin <problem-id> |
Variant of a known problem — same pattern, new surface |
$paideia-chain <N> |
Multi-pattern integration problem combining N patterns |
$paideia-mock <minutes> |
Full mock exam, HW-density weighted |
$paideia-grade [--ocr=<engine>] [path] |
OCR answer PDF via the engine set in .course-meta (Codex-native vision / Qwen3-VL / Tesseract), strategy-grade, append errors/log.md |
$paideia-weakmap [concept] |
Priority-ranked weakness report saved to weakmap/weakmap_<ts>.md |
$paideia-cheatsheet [--pdf] |
Error-driven one-pager |
$paideia-alt [paste] |
Import an OPTIMETA Exam Radar (Alt plugin) export → course-index/radar.md + a lecture-emphasis column on coverage.md + a gold-zone weakmap |
The plugin bundles four stdio MCP tools. Each accepts an explicit project_root; otherwise it uses the server's working directory.
| Tool | Responsibility |
|---|---|
ingest_pdfs |
Discover materials, copy Markdown, render PDFs, and run in-process OCR or return a page manifest. |
grade_pdf |
Render/OCR an answer PDF and return transcription data. The calling Codex skill performs strategy grading and error logging. |
build_course_index |
Write a deterministic draft index from the available documents. Codex refines course-specific patterns and coverage. |
course_phase |
Return phase, days until the exam, and top-miss pattern from course artifacts. |
codex-native returns mode: "rasterize-only": Codex must open the returned page images and write the transcription. The MCP does not perform native-vision recognition or model-based grading itself. grade_pdf archives the source scan during preparation, including the native path, before Codex completes the strategy grade. qwen3-vl and tesseract return mode: "ocr-complete" after writing Markdown locally.
PDFs are rendered into page images before transcription. Markdown sources are copied with a provenance header. Ingest writes the converted material; analyze then creates summary.md, patterns.md, and coverage.md from those sources.
Ingest uses 160 dpi and caps the long edge at 1800 px. For local OCR, a process pool distributes PDFs; Qwen's in-process OCR also uses a small thread pool for pages. Native vision is handled by the skill, sequentially within a PDF. Already-converted targets are skipped unless --force is requested.
Solve on paper, scan to answers/, then run $paideia-grade. Engine choice is per course and can be overridden with --ocr=<engine>.
| Engine | Default? | How it runs | When to pick it |
|---|---|---|---|
codex-native |
Yes | Render pages, then read them through the agent's vision path. | A working vision-capable model/tool configuration. |
qwen3-vl |
Optional | Local Ollama qwen3-vl:8b, with Tesseract fallback. |
Keep the answer's OCR page images local. |
tesseract |
Optional | Local pytesseract. |
Typed scans; handwriting and math need careful review. |
Default answer OCR is codex-native: page images are read through the runner's vision path. For local answer OCR, install Ollama and qwen3-vl:8b, then explicitly select OCR_ENGINE: qwen3-vl in .course-meta or pass --ocr=qwen3-vl to grade. Downloading the model alone does not change the engine. tesseract is the other local option. Local OCR keeps that transcription step local; subsequent analysis and grading still use the configured model and may send it the transcribed text.
The grading instructions check (1) the selected pattern Pk, (2) the variables, substitution, basis, or contour, and (3) the final expression's form. Review the transcription and grade when OCR is uncertain. Errors are appended to errors/log.md using problem_id, pattern, error_type, summary, source, and date. Error types include pattern-missed, wrong-variable, wrong-end-form, algebraic, sign, and definition.
The cheatsheet uses the course index and error history together: patterns/formulas provide reference material, while your errors drive the traps and corrections. --pdf also requests a printable cheatsheet/final.pdf; inspect the rendered equations before printing.
$paideia-analyze reads the course's solutions and worked examples, labels recurring moves P1, P2, …, and cites the source files under converted/. The resulting pattern cards and HW coverage are the context for later drills. The model-generated index should be checked against your assignments.
Commands append attempts to errors/log.md and save dated reports under weakmap/. Keep that history when re-ingesting or migrating. Generated problem sets have separate answer/solution siblings; solve the problems before opening them.
$paideia-phase calls course_phase; this package installs no PAIDEIA statusline or session-start hook. The detector returns setup when patterns.md is absent, diag when it exists without a recognized pattern: Pk error entry, and drill when such an entry exists. A source: containing mock selects mock; cheatsheet/final.md or .pdf selects cram; exam day (D-0) selects cool. An empty patterns.md still satisfies the file-existence check, so the phase is a filesystem heuristic, not evidence of learning.
PAIDEIA-codex/
├── .agents/plugins/marketplace.json # marketplace manifest (Codex)
├── LICENSE # MIT
├── README.md # this file
├── README.ko.md # Korean mirror
└── plugins/paideia/
├── .codex-plugin/plugin.json # plugin manifest (name, version, author)
├── .mcp.json # spawn config for paideia-mcp
├── paideia-mcp/ # bundled stdio MCP server
│ ├── pyproject.toml
│ ├── README.md
│ └── paideia_mcp/
│ ├── server.py # stdio entrypoint, tool registration
│ ├── ingest.py # ingest_pdfs tool
│ ├── grade.py # grade_pdf tool
│ ├── analyze.py # build_course_index tool
│ ├── phase.py # course_phase tool
│ └── ocr/
│ ├── qwen3vl.py # local Ollama Qwen3-VL 8B
│ └── tesseract.py # pytesseract eng / kor (auto-detected)
└── skills/ # 16 verb-skills (paideia-ingest, paideia-grade, paideia-phase, ...)
├── paideia-init-course/
│ ├── SKILL.md
│ ├── scripts/bootstrap.py
│ └── assets/AGENTS.md.template
├── paideia-ingest/SKILL.md
├── paideia-grade/SKILL.md
├── paideia-phase/SKILL.md
├── paideia-analyze/SKILL.md
├── paideia-hwmap/SKILL.md
├── paideia-pattern/SKILL.md
├── paideia-derive/SKILL.md
├── paideia-quiz/SKILL.md
├── paideia-blind/SKILL.md
├── paideia-twin/SKILL.md
├── paideia-chain/SKILL.md
├── paideia-mock/SKILL.md
├── paideia-weakmap/SKILL.md
├── paideia-cheatsheet/SKILL.md
└── paideia-alt/SKILL.md
- Read the math as Markdown. Open the course in Obsidian or a Markdown-capable desktop view.
- Solve on paper. Scan the answer and choose the OCR path that fits your setup.
- Review strategy and transcription. Pattern, variables, and final form guide grading; OCR and model judgments can need correction.
- Extract patterns from your course. Cite the supplied solutions and worked examples.
- Learn from recorded errors. Let them shape practice and the cheatsheet's traps.
- Use homework to prioritize. Treat its density as a study signal and check it against the announced exam scope.
- Keep the study graph yours. Editable Markdown, preserved error history, and version control across sessions.
Does this work for non-math courses? Ingest and summarization can help, but the practice workflow assumes recurring problem-solving patterns. It is designed for math, physics, engineering, and related quantitative courses.
How does the next session remember my work? The course context, index, and error history are files. Later commands read them again; your study record is not dependent on chat history alone.
Can I edit the patterns or cheatsheet? Yes. Save changes in any Markdown editor and commit the files you want to preserve before regenerating them. Keep the error log and weakmap history.
Korean and English mixed materials?
Codex can read both. This port currently ships Korean-oriented skill/context instructions and no en/ko bootstrap picker. Ask for your preferred language and align AGENTS.md. Tesseract uses whichever eng/kor traineddata is installed.
Do I need Ollama, and is the whole workflow offline? Ollama is optional. The default uses the runtime’s vision path. Local OCR keeps image transcription on your machine, but analysis and grading still use your configured model. See the OCR engine table above for the required setup.
Can I move a course between PAIDEIA editions?
The Markdown study artifacts share a layout. Review the destination's context file and engine names first: CLAUDE.md / AGENTS.md / PAIDEIA.md, and claude / codex-native / vision or ollama / qwen3-vl. Preserve your existing metadata and personal history; the versions do not have identical configuration or command sets.
Does model-generated grading need review? Yes. The source scan, transcription, referenced patterns, and YAML log let you inspect and correct an assessment. The status indicator is a file-based workflow cue, not an independent measurement of understanding.
Does PAIDEIA require a separate OPENAI_API_KEY?
The default native OCR path does not call a separate OCR API. It uses the current Codex session's authentication, usage allowance, and billing. Local OCR does not remove the model calls used for analysis and grading.
MIT. Use freely. Fork and modify for your own courses — the point of the plugin is that the study graph it builds is yours to shape, not a fixed product you have to live with.
Generic curricula teach the average student. Παιδεία — formation, one student at a time.