[GUI Plugin] Colophon - AI-assisted EPUB repair+proofreading (alpha, Calibre 9.5+)

jbennion · 06-26-2026, 12:14 PM

Hey everyone. For years I have been frustrated with typos and structural errors in EPUBs that break my reading flow. This is especially distracting with OCR'ed ebooks that have artifacts like extra ~ or numbers in words like Sm1th, etc., etc. Also, there are often broken structures like bad table of contents that make navigating books a problem.

As I searched, I couldn't find a single tool that incorporated fixing epub structure problems with proofreading to remove obvious errors in the actual text. These could be typos from poorly-edited novels I often read, or OCR artifacts that no one has time to read.

As I've learned more and more about LLMS, it's seemed to me that AI was a perfect use case for this. While I am an avid reader, I am not a coder. But it occurred to me I could have the AI's help me in two ways: 1-help me vibe-code an open-source GitHub project and 2-have LLMs read the books to help make sense of and correct obvious errors.

HOW YOU CAN HELP. There are two ways you can help! Right now the Calibre plugin is alpha, so I don't think it's ready to put in the Calibre plugin library yet, but it is on GitHub.

If you are a coder: help review the code, test the code, help me find problems and submit PRs to fix it!
If you are not a coder: If you're here, you're ALSO an avid reader. You can still help this project a TON by contributing epubs that have errors that we can use to improve the proofreading and structural fixes. So if you run it against a book and find there are typos or structural problems it doesn't fix but should be able to, submit that as a PR (bug report) or just reply below and we'll put it in the mix for trying to fix it. It's very early days!

Thanks everyone, here is the project:
https://github.com/JSBinSLC/colophon

JSWolf · 06-26-2026, 02:17 PM

But how can this AI fix the fomatting?

icallaci · 06-26-2026, 10:19 PM

Wow, this is a huge undertaking. You have my utmost best wishes. I am leery of mass search and replace because it can really mess things up, but I will take a look at your github project when I get some time.

rantanplan · 06-27-2026, 05:33 AM

When I install it via python venv, only the init.py is created. This doesn’t seem to install properly.

rantanplan · 06-27-2026, 05:36 AM

By the way, neither this project nor the other project from the day before yesterday have proper claude.md and agent.md.

jbennion · Today, 04:51 PM

Sorry for the delay in my replies!

@JSWolf — most of the formatting/structure work is not the LLM guessing at CSS. Regular code unpacks the EPUB, rebuilds a missing/broken TOC from headings, splits a one-file book into chapters, cleans up junk HTML (calibre spans, inline styles), sanitizes CSS, and re-keys obfuscated fonts if the unique-id drifted. The AI part is mainly for proofreading: OCR junk, inconsistent character names, that kind of thing.

It will not restyle a book into something pretty. If the publisher’s CSS is ugly but valid, it mostly leaves it alone. Happy to take a specific “this formatting is broken” EPUB if you have one.

@icallaci — thank you, and yeah, I am also scared of blind search-and-replace. That’s why it builds a per-book list of names/places first and only then tries to make those consistent. I'm an avid Science Fiction and Fantasy reader; blind spellcheck would destroy most of those books! Low-confidence stuff gets flagged instead of silently rewritten. The plugin also keeps a backup of the original EPUB in the book’s data/ folder (original.epub.orig) unless you turn that off. CLI has --dry-run too. If you do try it and it mangles something, please tell me — that’s exactly the kind of report I need.

@rantanplan — I think I know what happened. pip install colophon from PyPI is a different project (a name reservation, basically just an __init__.py). Mine isn’t on PyPI yet. README is wrong about that, I’ll fix it. Blame hallucinatory AIs again!

For the Calibre plugin:

Preferences → Plugins → Load plugin from file → the zip from GitHub - JSBinSLC/colophon: Your one-stop EPUB fixer with AI smarts — broken navigation, OCR artifacts, proper nouns, font obfuscation, and more, in a single command. · GitHub (build it with python calibre-plugin/build.py, or I can attach a zip here if that’s easier). Needs Calibre 9.5+.

For the CLI from a venv:

git clone GitHub - JSBinSLC/colophon
cd colophon
pip install -e . colophon fix book.epub

On the CLAUDE.md / AGENTS.md point: fair. I’ll add those so coding agents don’t wander. Thanks for flagging it.

06-26-2026, 12:14 PM	#1
jbennion Enthusiast Posts: 25 Karma: 17972 Join Date: Nov 2010 Device: Sony reader PRS-650	[GUI Plugin] Colophon - AI-assisted EPUB repair+proofreading (alpha, Calibre 9.5+) Hey everyone. For years I have been frustrated with typos and structural errors in EPUBs that break my reading flow. This is especially distracting with OCR'ed ebooks that have artifacts like extra ~ or numbers in words like Sm1th, etc., etc. Also, there are often broken structures like bad table of contents that make navigating books a problem. As I searched, I couldn't find a single tool that incorporated fixing epub structure problems with proofreading to remove obvious errors in the actual text. These could be typos from poorly-edited novels I often read, or OCR artifacts that no one has time to read. As I've learned more and more about LLMS, it's seemed to me that AI was a perfect use case for this. While I am an avid reader, I am not a coder. But it occurred to me I could have the AI's help me in two ways: 1-help me vibe-code an open-source GitHub project and 2-have LLMs read the books to help make sense of and correct obvious errors. HOW YOU CAN HELP. There are two ways you can help! Right now the Calibre plugin is alpha, so I don't think it's ready to put in the Calibre plugin library yet, but it is on GitHub. If you are a coder: help review the code, test the code, help me find problems and submit PRs to fix it! If you are not a coder: If you're here, you're ALSO an avid reader. You can still help this project a TON by contributing epubs that have errors that we can use to improve the proofreading and structural fixes. So if you run it against a book and find there are typos or structural problems it doesn't fix but should be able to, submit that as a PR (bug report) or just reply below and we'll put it in the mix for trying to fix it. It's very early days! Thanks everyone, here is the project: https://github.com/JSBinSLC/colophon

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
[GUI Plugin] ePub Extended Metadata	un_pogaz	Plugins	68	06-30-2026 02:49 AM
[GUI Plugin] Streamer - RSVP Speed Reader plugin for Calibre	npapadacis	Plugins	6	04-24-2026 03:00 AM
[GUI Plugin] Modify ePub	kiwidude	Plugins	1800	04-08-2026 08:54 PM
[GUI Plugin] BiB/i EPUB reader plug-in for calibre	dcato	Plugins	0	11-30-2016 02:56 PM

06-26-2026, 02:17 PM	#2
JSWolf Resident Curmudgeon Posts: 84,589 Karma: 153744815 Join Date: Nov 2006 Location: Roslindale, Massachusetts Device: Kobo Libra 2, Kobo Aura H2O, PRS-650, PRS-T1, nook STR, PW3	But how can this AI fix the fomatting?

06-26-2026, 10:19 PM	#3
icallaci Guru Posts: 849 Karma: 6528026 Join Date: Sep 2012 Device: Kobo Elipsa	Wow, this is a huge undertaking. You have my utmost best wishes. I am leery of mass search and replace because it can really mess things up, but I will take a look at your github project when I get some time.

06-27-2026, 05:33 AM	#4
rantanplan Weirdo Posts: 1,231 Karma: 13516840 Join Date: Nov 2019 Location: Wuppertal, Germany Device: Kobo Libra 2, Kobo Sage, Kobo Aura H2O, reMarkable PaperPro	When I install it via python venv, only the init.py is created. This doesn’t seem to install properly.

06-27-2026, 05:36 AM	#5
rantanplan Weirdo Posts: 1,231 Karma: 13516840 Join Date: Nov 2019 Location: Wuppertal, Germany Device: Kobo Libra 2, Kobo Sage, Kobo Aura H2O, reMarkable PaperPro	By the way, neither this project nor the other project from the day before yesterday have proper claude.md and agent.md.

Today, 04:51 PM	#6
jbennion Enthusiast Posts: 25 Karma: 17972 Join Date: Nov 2010 Device: Sony reader PRS-650	Sorry for the delay in my replies! @JSWolf — most of the formatting/structure work is not the LLM guessing at CSS. Regular code unpacks the EPUB, rebuilds a missing/broken TOC from headings, splits a one-file book into chapters, cleans up junk HTML (calibre spans, inline styles), sanitizes CSS, and re-keys obfuscated fonts if the unique-id drifted. The AI part is mainly for proofreading: OCR junk, inconsistent character names, that kind of thing. It will not restyle a book into something pretty. If the publisher’s CSS is ugly but valid, it mostly leaves it alone. Happy to take a specific “this formatting is broken” EPUB if you have one. @icallaci — thank you, and yeah, I am also scared of blind search-and-replace. That’s why it builds a per-book list of names/places first and only then tries to make those consistent. I'm an avid Science Fiction and Fantasy reader; blind spellcheck would destroy most of those books! Low-confidence stuff gets flagged instead of silently rewritten. The plugin also keeps a backup of the original EPUB in the book’s data/ folder (original.epub.orig) unless you turn that off. CLI has --dry-run too. If you do try it and it mangles something, please tell me — that’s exactly the kind of report I need. @rantanplan — I think I know what happened. pip install colophon from PyPI is a different project (a name reservation, basically just an __init__.py). Mine isn’t on PyPI yet. README is wrong about that, I’ll fix it. Blame hallucinatory AIs again! For the Calibre plugin: Preferences → Plugins → Load plugin from file → the zip from GitHub - JSBinSLC/colophon: Your one-stop EPUB fixer with AI smarts — broken navigation, OCR artifacts, proper nouns, font obfuscation, and more, in a single command. · GitHub (build it with python calibre-plugin/build.py, or I can attach a zip here if that’s easier). Needs Calibre 9.5+. For the CLI from a venv: git clone GitHub - JSBinSLC/colophon cd colophon pip install -e . colophon fix book.epub On the CLAUDE.md / AGENTS.md point: fair. I’ll add those so coding agents don’t wander. Thanks for flagging it.

Advert

Advert