Verbatim — Notas de Livros com Citações Verificadas
yousefh409/verbatim
Converte livros em notas verificadas com citações 100% corretas
Ver no GitHubSkill que transforma PDFs em notas estruturadas por capítulo com todas as citações mecanicamente verificadas contra o texto original. Usa ripgrep e busca exata/fuzzy para garantir que cada página citada é real, sem alucinações. Ideal para pesquisa acadêmica, escrita de artigos e gestão de bibliografias.
Instalação
npx convez-ai yousefh409/verbatim1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preparar notas de leitura para trabalhos acadêmicos
- Gerenciar bibliografia com citações página-exatas
- Validar e lintear rascunhos contra fontes originais
- Construir base de conhecimento local e consultável de PDFs
Veredito

Ferramenta robusta para quem precisa de rigor acadêmico: elimina alucinações de IA via verificação mecânica exata. Excelente para pesquisa séria, mas requer investimento inicial em OCR e calibração de páginas.
README
A tradução para o português deste README ainda está na fila.
verbatim
Hand it a book. Get the notes. Keep the receipts.
What it is
verbatim is a Claude Code skill that turns books (PDFs) into verified, per-chapter
notes and a quote-accurate citation engine. The differentiator is that it does not
hallucinate: every quote is mechanically checked against the source text before it
is allowed into a note or an answer, and every page number it cites is real. No
vector database, no embeddings, no fine-tuning. It is ripgrep, the agent, and a
small Python stdlib engine doing exact-and-fuzzy text matching against the book you
actually loaded.
The story
verbatim was built to manage the bibliography for a real university term paper. The
author handed it 15 dense books, turned them into a page-accurate, grep-able
knowledge base, generated 121 verified chapter notes, and wrote the paper citing
real pages with mechanically-checked quotes. This repo generalizes that system so
anyone can do the same with any reading list.
What you can do
The loop:
- Hand it one or more books — a PDF, a link, or just a title. It ingests each one into a persistent local library, OCRs scanned pages if needed, and calibrates page numbering so printed-page citations are correct.
- Get verified notes — one note per chapter (TL;DR, full digest, the argument, key terms, key quotes with real pages), plus a single self-contained HTML viewer.
- Keep working with the book — it stays loaded across sessions for quote-accurate Q&A, ready-to-paste citations, and linting any draft you are writing.
Headline commands once a book is loaded:
kb.py ingest book.pdf --slug my-book # load a book into the library
kb.py calibrate --book my-book # detect the printed-page offset
kb.py search "term" # find pages across the library
kb.py verify "<exact quote>" --book my-book # confirm a quote + get its page
kb.py lint draft.md # re-check every quote in a draft
kb.py list # show the loaded library
In practice you do not type these. You talk to the skill: "take notes on this PDF", "what does this book say about X", "verify this quote", "lint my draft". The CLI is there when you want it (see How it works).
Demo
demo/ is a real, reproducible run of the skill on two short
public-domain books: The Communist Manifesto and A Modest Proposal. Every quote
in every note there was run through kb.py verify against the source text before it
was written down and tagged [✓ verified].
What is in the folder:
demo/Notes/— five chapter notes across the two books.demo/Notes Viewer.html— the generated viewer, a single self-contained HTML file. Open it in any browser; it needs no server and no internet.demo/sample-draft.md— a tiny draft used to demonstrate the linter (two genuine quotes plus one deliberately altered one).demo/README.md— the exact fetch, convert, ingest, calibrate, and build commands, so the whole run is reproducible from the Project Gutenberg sources.
The worked lint example, run against demo/sample-draft.md:
$ kb.py lint demo/sample-draft.md
OK line 7: "The history of all hitherto existing societies is the histor…"
-> [communist-manifesto] p.1 (PDF sequential page -- this edition has no printed pagination)
OK line 10: "It is a melancholy object to those, who walk through this gr…"
-> [a-modest-proposal] p.1 (PDF sequential page -- this edition has no printed pagination)
NOT FOUND line 14: "The proletarians have nothing to lose but their chains. They…"
Closest (86%) [communist-manifesto] p.23 (PDF sequential page -- this edition has no printed pagination):
>>revolution.<< The proletarians have nothing to lose but their chains. They have a >>world<< to
3 quotes: 2 OK, 0 page mismatches, 1 not found
The altered quote ("a planet to win" in the draft, against the real "a world to win") is caught with a fuzzy diff pointing at the true wording on p.23, and the linter exits nonzero so a bad draft cannot pass silently.
Install
verbatim is a Claude Code skill. Clone the repo into your skills directory:
git clone <repo-url> ~/.claude/skills/verbatim
(or wherever your Claude Code plugin/skill path points). Dependencies, installed once:
- Python 3.9+ — the engine is pure stdlib, nothing to
pip install. - poppler — provides
pdftotextandpdfinfo(macOS:brew install poppler). - ocrmypdf — only needed for scanned books (macOS:
brew install ocrmypdf).
Once it is in place, you just talk to it: "take notes on this PDF", "verify this quote", "lint my draft". The skill handles ingest, calibration, note-writing, and the viewer build for you.
The engine also works standalone, no agent required:
python3 scripts/kb.py ingest /path/to/book.pdf --slug my-book
python3 scripts/kb.py calibrate --book my-book
python3 scripts/kb.py verify "an exact sentence from the book" --book my-book
python3 scripts/kb.py list
Books live under $VERBATIM_HOME (default ~/.verbatim/) and persist across sessions.
How it works
- Per-book library. Each ingested book becomes
~/.verbatim/<slug>/: form-feed delimited page text plus ameta.jsonholding the page model and citation. The user never edits it. - Page model.
printed = pdf_page + offset.calibrateauto-detects the offset from the PDF's PageLabels metadata and a printed-page-1 heuristic, and only asks for a visual confirm when the result is genuinely ambiguous. - Quirk flags. Books are tagged
linear,sequential,2up,low-res, orvisualso citations adapt to the edition (e.g. a Gutenberg.txt-derived PDF with no printed numbers getssequentialand is cited by PDF page). - Verify normalization. Matching is diacritic- and whitespace-insensitive, so a quote still verifies across line breaks, hyphenation, and accent differences, while remaining exact about the actual words.
- Retrieval. ripgrep over the page text, with the agent as the semantic layer. There is no index to rebuild and nothing to embed.
Anti-hallucination guarantee
This is the whole point of the project.
- Quote, then locate. No quote enters a note or an answer until
kb.py verifyfinds it in the loaded source. On a miss,verifyprints the closest real passage with the differing words marked, so the wording gets corrected to what the book actually says, or the quote is dropped. An unverified quote never ships. - Real pages only. The page number on a citation is the one
verifyreturns from the source, never one invented to look plausible. - Lint gates a draft.
kb.py lint draft.mdre-checks every quoted passage in a document against the library and exits nonzero on any unverifiable quote or wrong page number. A draft with a bad citation cannot pass the check silently.
Status and scope
This is v1. Intentionally out of scope for now:
- BibTeX / Zotero import
- exam-prep mode
- cross-book synthesis recipes
- an MCP server
- pip packaging
These are deferrals, not missing pieces. The core loop (ingest → calibrate → verified
notes → Q&A / citations / lint) is complete and tested (236 passing tests under
tests/).
License
MIT. See LICENSE. The repo bundles no copyrighted books; the demo uses public-domain texts from Project Gutenberg.