genius

README

░█▀▀░█▀▀░█▀█░▀█▀░█░█░█▀▀
░█░█░█▀▀░█░█░░█░░█░█░▀▀█
░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀▀▀

A dedicated terminal study environment. Run genius and you are in a place built for studying — not issuing commands inside a general-purpose shell. It takes your raw course material (PDF/PPT lectures) and turns it into study guides, revision Q&A, and interactive quizzes, all inside one cohesive, gradient-styled terminal UI.

---

Why

Studying from raw lecture files is manual and fragmented: PDFs aren't skimmable or revisable, hand-making guides and Q&A is slow, and a generic chatbot gives answers ungrounded in your course — off-syllabus or wrong. genius owns a study workspace and gives you one immersive loop: ingest → generate → revise, with every generation grounded strictly in the supplied material. I designed it the way I study most of the time for my CS tests to get the best marks with low effort.

Features

• Ingest — convert PDF/PPT/documents to markdown (via markitdown), filed per course. Figures are extracted (poppler) and vision-captioned.
• Notation-faithful — text extraction silently drops Boolean complement bars (X̄); genius detects this and re-transcribes the affected pages with a vision model, since the bars are graphics no text extractor can recover.
• Study guides — structured guides (summary, key concepts, formulas, common traps) generated from the full course markdown.
• Revision Q&A — Q&A pairs for revision, in a format the quiz loop consumes.
• Interactive quiz — the signature feature: ask → answer → reveal → self-grade → advance, with a running score.
• Exercise tutoring — enumerate a problem set, pick exercises (or sub-parts), and get worked solutions grounded only in the course; solved as stated, with gaps in the material flagged rather than fabricated.
• In-place rendering — guides/Q&A shown as styled, scrollable markdown (Glamour), never leaving the environment.
• Swappable engines — claude (default) or codex, behind one interface, identical workflow.

Requirements

Tool	Purpose	Install
Go 1.25+	build	—
markitdown	PDF/PPT → markdown	pip install 'markitdown[pdf]'
poppler (pdfimages, pdftoppm, pdfinfo)	figure extraction, page rasterize	system package
claude or codex	generation engine	their respective CLIs

markitdown installs to ~/.local/bin — make sure it's on PATH. claude has no vision support; figure captioning / notation repair needs codex.

Install

# install the binary directly
go install github.com/mibienpanjoe/genius@latest

# …or build from a clone
git clone https://github.com/mibienpanjoe/genius && cd genius
go build -o genius .
install -m 0755 genius ~/.local/bin/genius   # onto your PATH

genius is a personal study setup: it shells out to markitdown, claude, and codex, and assumes the workspace convention below. Installing the binary is not enough on its own — see Requirements.

Usage

Launch the environment (home dashboard rooted at your study workspace):

genius

Or script the actions with subcommands:

genius ingest lecture.pdf              # → courses/lecture/lecture.md (+ assets)
genius ingest td.pdf --kind exercise --course logic
genius guide logic                     # → guides/logic.md
genius qa logic --count 15 --scope "Boolean algebra"
genius solve logic --set td            # list the set's exercises
genius solve logic --set td --ex 2,3.1 # work specific exercises, grounded
genius guide logic --engine codex      # swap the generation engine

Keys (TUI)

Key	Action
↑/↓ j/k	move between courses
g / enter	open the study guide
q	open the Q&A
r	start a revision quiz
s	solve exercises (pick set → pick exercises)
esc	back
ctrl+c	quit

In a quiz: type your answer → enter reveals → y/n (or space) self-grades → advance. In solve: pick a set → space toggles exercises → enter solves the selection (or the highlighted one) and shows the worked solution in the reader.

Organising courses

A course is a directory of markdown under courses/<name>/; genius reads every .md there as grounding. The course name and the document filename are separate, which makes a few layouts fall out naturally.

Single-file course — one lecture, one course. The course name defaults to the filename slug.

genius ingest lecture.pdf            # → courses/lecture/lecture.md
genius guide lecture

Multi-chapter course — one course split across several PDFs (a chapter per file). Point them all at one course with --name; each keeps its own .md. Zero-pad the names so they sort in reading order (the grounding concatenates files lexically).

genius ingest chap01.pdf --name algebra      # → courses/algebra/chap01.md
genius ingest chap02.pdf --name algebra      # → courses/algebra/chap02.md
genius ingest chap03.pdf --name algebra

genius guide algebra                         # grounded on ALL chapters
genius guide algebra --files chap03.md       # grounded on one chapter
genius guide algebra --files chap01.md,chap02.md   # a span of chapters

--files works the same on qa. Without it, generation always grounds on the whole course.

Topic focus vs. file scope — two different knobs:

• --files <a.md,b.md> chooses which source material is fed to the model (file-level grounding).
• qa --scope "<text>" is a free-text instruction ("focus on Karnaugh maps"), not a filename — the grounding is unchanged, the model just narrows its attention.

genius qa algebra --count 15 --scope "Karnaugh maps"
genius qa algebra --files chap03.md --scope "don't-care conditions"

Your own notes — drop hand-written .md straight into courses/<name>/; genius reads it as grounding alongside ingested files. Only markdown counts — never copy a raw .pdf into the workspace; run it through ingest first.

Exercises — exercise sets are filed under a course but kept apart from the lecture material (so problems never pollute the guide/Q&A grounding):

genius ingest td1.pdf --kind exercise --course algebra   # → exercises/algebra/td1.md

Then solve enumerates the set and works the exercises you pick, grounded only in the course. The tutor solves each one as stated and flags any gap in the material rather than inventing a method.

genius solve algebra --set td1                 # list the exercises (and sub-parts)
genius solve algebra --set td1 --ex 2,3.1      # work exercise 2 and sub-part 3.1
genius solve algebra --set td1 --ex 2 --save   # also write td1.solutions.md (source untouched)

Sub-parts are addressed <exercise>.<part> — 3.1, 3.a. In the TUI, press s to do the same: pick a set, toggle exercises with space, enter to solve.

Workspace

genius owns a study home, resolved as $GENIUS_HOME, else ~/study:

~/study/
  courses/<name>/*.md       ingested / source markdown
  courses/<name>/assets/    figures extracted during ingest
  guides/<name>.md          generated study guides
  qa/<name>.md              generated revision Q&A
  exercises/<name>/*         exercise sets (+ assets/)

Courses are referenced by name; genius reads all markdown under courses/<name>/ as grounding. Config lives at ~/.config/genius/config.toml (study_root, default_engine, model).

How it works

• Grounding — the full course markdown is stuffed into the generation prompt (typical lectures fit in context). Chunking/retrieval is deferred until a course overflows.
• Engines — claude -p / codex exec run as swappable subprocesses behind an Engine interface; only the final assistant text is captured.
• Architecture — Go + the Charm stack (Bubble Tea / Lip Gloss / Bubbles), Glamour for rendering, Cobra for subcommands. Design docs live in docs/.

Project layout

main.go                 entrypoint → cli.Execute
internal/
  cli/                  cobra subcommands + TUI launch
  workspace/            study-root resolution, course scan, writes
  engine/               Engine interface + claude / codex / fake
  convert/              markitdown ingest, figure extraction, notation repair
  generate/             grounded guide / qa / solve prompt assembly + enumerate
  render/               Glamour helper (markdown → styled string)
  tui/                  Bubble Tea: home / reader / quiz / solve
  quiz/                 qa-markdown parser
docs/                   01–07 design docs (PRD, SRS, architecture, …)

Status

Ingest, guide, qa, reader, quiz, and exercise solving (solve) all work end-to-end against real material, in both the CLI and the TUI. Post-MVP: TUI-driven guide/qa generation and quiz weak-spot tracking.

License

MIT. A personal / educational tool — generation cost is borne by your own claude / codex subscriptions.