Warraq

Open-source tools for digital heritage libraries

From a folder of scans to a catalogued library in your pocket

Seven tools for librarians, students and researchers. Clean scanned pages without touching their pixels, name every book by one bibliographic rule, match it to the big catalogues with evidence, reorganise files with plans you review before they run and can undo, and carry the whole library as one offline catalogue on your phone.

Start the walk-through Meet the tools

volumes in the library they were built on
16,700
independent tools that fit together
7
open source under
MIT

From scans to shelf

Each step is a tool that works on its own; together they form one pipeline. Start where you are.

  1. A folder of scans

    Scanned PDFs named by uploaders and scan numbers, with black margins, tilted pages and blank leaves. Most personal libraries start here.

  2. Clean the pages

    One crop box for the whole book, deskewed pages, two-page spreads split, extra pages dropped, and every image left exactly as it was.

    safha

  3. Name the books

    One rule for every name (title, author, editor, publisher) with death years and Hijri dates, and an audit that flags what breaks the rule.

    arabic-bib

  4. Match and prove

    Each file is traced to its source by exact size, each book matched to Shamela, Waqfeya and archive.org, and duplicates proven by sampled bytes.

    turath-matchturath-catalog

  5. Reorganise

    Moves, renames and deletes go into a plan you see before it runs, applied to disk, phone or any remote, with a log and an undo.

    planfs

  6. A catalogue in your pocket

    The whole folder becomes one HTML file that the phone's browser opens offline, with search, sections and authors by century.

    pocketshelf

When an AI agent runs the long jobs, agent-workbench keeps you in charge with review pages whose ticks and comments flow back to the agent.

The seven tools

Each tool has full documentation in Arabic, with an English README in its repository.

What no single tool gives you

Every step has good tools. Warraq brings these seven principles together.

  • Arabic first

    Built for Arabic titles, author names with kunya, nisba and laqab, Hijri dates and right-to-left text, while working in any language and script.

  • Lossless

    Cropped pages are never re-encoded: the frame changes, the pixels do not.

  • Planned, logged, reversible

    No move, rename or delete without a plan you see first, an append-only log and a one-command undo.

  • Offline on a phone

    The catalogue is one self-contained file that works in an Android browser with no server and no network.

  • Evidence for every match

    A file is tied to a source only by exact size or sampled bytes, never by a similar title.

  • An open dataset

    Works, editions, authors and editors as open data under CC BY 4.0, metadata only.

  • Proven on a real library

    Built and refined on a 16,700-volume library before being made general.

The usual way and the Warraq way

How each step usually goes when a library is managed by hand, and how it goes with Warraq.

StepThe usual wayWith Warraq
Cleaning pagesCropping page by page, or an export that redraws the imagesOne box per book, images untouched, page drops undoable
NamingUploader names and scan numbers, everyone's own styleOne rule for title, author, editor, publisher, audited
MatchingTitle search on websites; similar titles let wrong books inExact size ties a file to its source; editions matched by editor and publisher
DuplicatesDeleted by name or size aloneDeleted after sampled bytes prove them identical
ReorganisingDrag and drop in a file manager, no recordA reviewed plan, a log of every change, undo
CataloguingA spreadsheet, or an app that needs a serverOne HTML file that works offline on a phone
Working with an agentWatching the terminal, typing notes into the chatA review page whose ticks and comments reach the agent

Born from a real library

Warraq began as a personal library on an Android phone: Arabic scanned books gathered from open sources such as Waqfeya and archive.org, until it passed sixteen thousand volumes in forty sections. A library that size needs tools — to crop margins for small screens, unify names, prove duplicates, keep a record of every move, and carry the whole collection as a catalogue in a pocket. These tools are what came out of that work, made general: every rule specific to the first library became an optional profile called warraq.

The documentation is in Arabic first; each tool's repository has an English README.

Browse the library they were built on