Your personal PDF library — beautifully managed, intelligently advised.
Named after Ogma — the Celtic Irish deity who invented the Ogham alphabet, the first writing system native to the British Isles. Your collection, carved into stone.
Ogma Library turns a folder full of PDF files into a living, curated personal library. It scans your collection, enriches every book's metadata from global book databases, generates cover thumbnails, and presents your library in a stunning 3D virtual bookshelf. Its defining feature: describe what you want to read in plain language and the built-in AI reading advisor finds the best matching books from your own collection — and explains exactly why each one fits.
Status: Active development. Core scanning, metadata, and reader are being built in Phase 1–3. The 3D bookshelf and AI advisor follow in Phase 4–5. See the Roadmap for current progress.
- Features
- Screenshots
- Architecture
- Project structure
- Getting started
- Network drive support
- Database portability
- AI reading advisor
- Metadata enrichment
- Roadmap
- Contributing
- Third-party acknowledgements
- About
- License
- Scan any local folder or network drive (Windows + macOS) as your library root
- Automatic incremental rescans — only processes files that have changed
- Portable database: move
ogma.dbto any machine, point it at the same books, and everything — metadata, covers, reading progress, bookmarks, shelves — loads instantly with no rescanning - Supports local drives, NAS shares, mapped drives, UNC paths (
\\server\share), and macOS SMB/AFP mounts (/Volumes/...) - Graceful offline mode when a network drive is unavailable — full catalogue still browsable
- Automatic ISBN detection from PDF text content, XMP metadata, and filenames
- One-click enrichment from Open Library (free, no key), Google Books (free with API key), ISBNdb (premium), and WorldCat
- Write metadata back into the PDF file — title, authors, publisher, categories written to XMP and DocInfo via PdfSharp. Non-destructive: original file backed up before any modification
- Fields stored: title, subtitle, authors, publisher, year, edition, language, page count, description, ISBN-10/13, categories, tags, series, cover source, and external database IDs
| View | Description |
|---|---|
| 3D Bookshelf | Photorealistic book spines on wooden shelves rendered with Three.js. Hover to tilt forward, click to inspect, double-click to read. Four shelf themes. |
| Grid | Cover cards in a resizable masonry layout — the natural way to browse a visual collection. |
| List | Sortable, filterable DataGrid with all metadata columns. Best for finding specific books and bulk operations. |
| Directory | Split-pane view of your folder tree and the books inside each folder. |
Built on PDFium — the same rendering engine as Google Chrome.
- All zoom modes: fit to width, fit to page, actual size, custom percentage
- Single page, two-page spread (book mode), and continuous scroll layouts
- Full-screen mode — all UI hidden, minimal toolbar on mouse approach
- In-document text search — all matches highlighted across all pages
- Bookmarks — create, label, and jump to bookmarks stored in the database
- Highlights and annotations — 5 highlight colours, text notes pinned to any position. Stored in the database, never modifying the PDF file
- Reading progress — last page saved on every turn, restored on every reopen
- Cumulative reading time tracked per book
- Night mode and sepia mode
- Describe what you want to read in plain language — the AI analyses your entire library and returns 12 best-matching books with a personalised explanation for each
- Supports OpenAI, Anthropic Claude, DeepSeek, and Ollama (fully local — no data leaves your machine)
- Two-pass strategy for large libraries: efficient even with 2,000+ books
- API keys stored in the OS credential manager (Windows Credential Manager / macOS Keychain) — never in config files or the database
- Query history saved: re-run previous queries instantly
- Optional reading plan: suggests an order to read the recommended books
- Virtual shelves — named collections independent of folder structure
- Built-in system shelves: Favorites, Currently Reading, Finished
- Tags — free-form user labels per book
- Star ratings (0–5)
- Reading statistics — books per month chart, pages per day, reading streak, genre breakdown
Coming with the first public release — Phase 4.
| Component | Technology |
|---|---|
| UI framework | Avalonia UI 11 (.NET 10) — native Windows and macOS from one codebase |
| MVVM | CommunityToolkit.Mvvm |
| 3D bookshelf | Three.js in an embedded WebView2 (Windows) / WKWebView (macOS) |
| PDF rendering | PDFium via Pdfium.Net.SDK |
| PDF metadata write | PdfSharp |
| PDF parsing / extraction | PdfPig |
| Database | SQLite via Entity Framework Core 10 |
| Image processing | SkiaSharp |
| HTTP / external APIs | System.Net.Http.HttpClient + System.Text.Json |
| Credential storage | OS credential manager via Microsoft.Extensions.SecretManagement |
| Auto-update | Velopack (direct download) · MSIX (Microsoft Store) |
OgmaLibrary.sln
│
├── OgmaLibrary.App/ ← Avalonia UI project
│ ├── Views/ ← All application screens (AXAML)
│ ├── ViewModels/ ← CommunityToolkit.Mvvm ViewModels
│ ├── Controls/ ← PdfiumView, WebView3DControl, CoverCard, StarRating
│ └── Assets/
│ ├── bookshelf.html ← Self-contained Three.js bookshelf scene
│ ├── Fonts/ ← DM Sans, JetBrains Mono
│ └── Themes/ ← Light.axaml, Dark.axaml
│
├── OgmaLibrary.Core/ ← Business logic (no Avalonia dependency)
│ ├── Models/ ← Book, ReadingProgress, Bookmark, Annotation, Shelf
│ ├── Services/
│ │ ├── LibraryScannerService ← File walk, relative path, SHA256 hash
│ │ ├── ThumbnailService ← PDFium → SkiaSharp → WebP
│ │ ├── SpineTextureService ← Cover + title → Three.js spine texture
│ │ ├── MetadataService ← In-PDF XMP and DocInfo extraction
│ │ ├── IsbnLookupService ← Google Books, Open Library, ISBNdb
│ │ ├── PdfMetadataWriterService ← PdfSharp write-back to PDF file
│ │ ├── AiAdvisorService ← Prompt builder and provider routing
│ │ ├── ReadingProgressService ← Last page, %, time tracking
│ │ └── CredentialService ← OS credential store abstraction
│ └── Data/
│ ├── OgmaDbContext.cs ← EF Core DbContext
│ ├── Migrations/
│ └── Repositories/
│
└── OgmaLibrary.Tests/ ← xUnit tests for Core services
- .NET 10 SDK or later
- Windows 10 version 1903+ or macOS 12 Monterey+
- (Optional) A Google Books API key for metadata enrichment
- (Optional) An API key for your preferred AI provider — OpenAI, Anthropic, or DeepSeek
git clone https://github.com/peterbamuhigire/ogma-library.git
cd ogma-library
dotnet restore
dotnet build
dotnet run --project OgmaLibrary.App- On first launch, click Set library root and select the folder (or network path) containing your PDF books
- Ogma scans the folder and generates cover thumbnails — this runs once; subsequent scans are incremental and fast
- Browse your library using the view toggle in the toolbar: 3D Bookshelf, Grid, List, or Directory
- Click any book to open the inspector panel — cover, all metadata, reading progress, quick actions
- Click Read Now to open the book in the built-in PDF reader
- Go to Settings → Metadata
- Add a Google Books API key (free — get one here)
- Back in the library, right-click any book → Fetch metadata, or select multiple books → Bulk enrich
- Go to Settings → AI Advisor
- Choose your provider (OpenAI, Anthropic, DeepSeek, or Ollama for fully local)
- Paste your API key — it is stored in the OS credential manager, never in a file
- Open the Ogma AI panel from the sidebar and start describing what you want to read
Ogma Library works with PDF libraries stored on a network-attached storage device (NAS) or any shared folder on your local network.
Set your library root to a UNC path or a mapped drive letter:
\\192.168.1.100\books\
\\NAS-NAME\library\
Z:\Books\
Mount the SMB share first in Finder (⌘K → smb://192.168.1.100/books), then set the library root to the mount point:
/Volumes/Books/
/Volumes/NAS/Library/
- The PDF files live on the network drive
- The database (
ogma.db) and thumbnails (.ogma/thumbnails/) live in a sidecar folder on the network drive alongside the books — any machine that mounts the same share has instant access to all metadata and covers without rescanning - If the network drive is offline when Ogma starts, the app enters offline mode: your full catalogue is browsable from a local cache, PDF reading resumes automatically when the drive reconnects
- A background monitor checks for reconnection every 30 seconds and triggers an incremental scan automatically
Multiple machines, same user: place
ogma.dbon the network drive so reading progress stays consistent between your desktop and laptop. See the full network architecture specification indocs/network-drive-support.md.
Everything Ogma knows about your library lives in a single, portable SQLite file.
~/Documents/OgmaLibrary/
├── ogma.db ← all metadata, reading progress, bookmarks, shelves
└── .ogma/
└── thumbnails/ ← WebP cover thumbnails, one per book
To move your library to another machine:
- Copy
ogma.dband the.ogma/sidecar folder - Copy your book files (or point to the same network share)
- Install Ogma Library on the new machine
- Set the library root to where the books are
- Everything loads instantly — no rescanning
How matching works:
Books are matched to their database records by relative path within the library root. If the directory structure is preserved when copying, every book matches immediately. If files were reorganised, Ogma falls back to matching by SHA256 content hash — reading progress is never lost even if you renamed a folder.
The AI advisor is the feature that separates Ogma Library from every other PDF manager.
I want to understand how the human brain forms and changes habits
Something practical about building and scaling a software startup — people, product, and growth
Deep technical content on distributed systems, consensus algorithms, and fault tolerance
A gripping biography — someone who changed the course of history through sheer force of will
I have a job interview at a tech company next week, help me prepare fast
The AI reads your entire library catalogue — titles, authors, categories, descriptions — and returns the 12 books that best match your intent, with a specific, personalised explanation for each recommendation. It never recommends a book that is not in your library.
| Provider | Models | Data sent |
|---|---|---|
| OpenAI | gpt-4o, gpt-4o-mini |
Book titles, authors, categories to OpenAI API |
| Anthropic | claude-sonnet-4-6 |
Book titles, authors, categories to Anthropic API |
| DeepSeek | deepseek-chat |
Book titles, authors, categories to DeepSeek API |
| Ollama (local) | llama3.1:8b, mistral:7b, any installed model |
Nothing — runs entirely on your machine |
Privacy: The AI advisor sends only book metadata (titles, authors, categories). Your PDF file contents never leave your machine regardless of which provider you use.
All API keys are stored in the OS credential manager. They are never written to config files, the database, or log files.
Most PDF books have poor or missing metadata. A scanned book may have Title = "Untitled" and Author = "". Ogma fixes this.
Ogma searches for the book's ISBN automatically in:
- The PDF's XMP metadata and DocInfo dictionary
- The text content of the first 10 pages (where copyright pages typically appear)
- The filename itself
| Database | Key required | Best for |
|---|---|---|
| Open Library | None — always free | Starting point for all books. No rate limits. |
| Google Books | Free Google API key | Mainstream and technical books. Richer descriptions. |
| ISBNdb | Paid subscription | Older, academic, and obscure titles. Most comprehensive. |
| WorldCat | Free OCLC key | Academic and library-catalogued books. |
Strategy: Ogma tries Open Library first, then Google Books. If your library has ISBNdb or WorldCat keys configured, they are used as fallbacks for books neither free database covers.
After enriching from an online database, Ogma can write the metadata into the actual PDF file — title, authors, publisher, categories — via PdfSharp. This makes the files properly tagged in any other application.
- Original file is backed up as
filename.pdf.ogma.bakbefore modification - Modification is non-destructive and reversible
- Works on individual books or as a bulk operation on selected books
| Phase | Timeline | Deliverables | Status |
|---|---|---|---|
| 1 — Foundation | Weeks 1–3 | Avalonia shell, EF Core database, library scanner, thumbnail generation, basic list view, portable database verified | 🔨 In progress |
| 2 — Metadata | Weeks 4–6 | ISBN detection, Open Library + Google Books, bulk enrichment, PdfSharp write-back, inspector panel | ⏳ Planned |
| 3 — Reader | Weeks 7–9 | PDFium reader, all zoom modes, full-screen, reading progress, bookmarks, highlights, annotations | ⏳ Planned |
| 4 — 3D Bookshelf | Weeks 10–12 | Three.js scene, spine textures, hover/click animations, four shelf themes, view toggle | ⏳ Planned |
| 5 — AI Advisor | Weeks 13–14 | All four AI providers, two-pass prompting, 12-book result grid, reading plan, query history | ⏳ Planned |
| 6 — Polish + Launch | Weeks 15–16 | Virtual shelves, reading stats, MSIX packaging, notarized macOS DMG | ⏳ Planned |
Post-launch:
- EPUB and CBZ support
- Full-text search index (search inside all books)
- Shared library across multiple machines with Litestream sync
- Multi-user shared catalogue (NAS + per-user local databases)
- In-app SMB share mounting (macOS)
- Goodreads CSV import
Ogma Library is developed by Peter Bamuhigire under Chwezi Core Systems. Contributions, issues, and feature suggestions are welcome.
To contribute:
- Fork the repository
- Create a feature branch:
git checkout -b feat/your-feature - Commit with a descriptive message:
git commit -m 'feat: add reading streak chart to stats view' - Push:
git push origin feat/your-feature - Open a pull request against
main
Code standards:
- C# latest, .NET 10, nullable reference types enabled
async/awaitthroughout — no blocking calls on the UI thread- No raw SQL — use EF Core repositories in
OgmaLibrary.Core - Business logic in
OgmaLibrary.Coreonly — no Avalonia dependencies in Core - New services should have corresponding xUnit tests in
OgmaLibrary.Tests
Ogma Library is built on the shoulders of excellent open-source projects:
| Project | License | Purpose |
|---|---|---|
| Avalonia UI | MIT | Cross-platform .NET UI framework |
| PDFium | BSD 3-Clause | PDF rendering engine |
| Three.js | MIT | 3D graphics for the bookshelf scene |
| PdfPig | Apache 2.0 | In-PDF text and metadata extraction |
| PdfSharp | MIT | PDF metadata write-back |
| QRCoder | MIT | LAN Host QR join-code generation |
| SkiaSharp | MIT | Thumbnail and spine texture generation |
| CommunityToolkit.Mvvm | MIT | MVVM framework |
| Entity Framework Core | MIT | SQLite ORM |
| Velopack | MIT | Cross-platform installer and auto-updater |
Metadata sourced from Open Library (Internet Archive) and Google Books.
Ogma (also Ogmios in Gaulish tradition) is the Irish deity of eloquence, literacy, and the written word, from the Ulster Cycle — the great body of pre-Christian Irish mythology. He is credited with inventing the Ogham alphabet: an ancient script cut as strokes and notches along the edges of standing stones across Ireland, Scotland, Wales, and the Isle of Man. Thousands of Ogham stones survive to this day — a permanent, carved record that has outlasted kingdoms, languages, and civilisations.
Your library deserves the same permanence.