<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="Resources/Brand/wordmark-dark.svg">
<img src="Resources/Brand/wordmark.svg" alt="Bookside" width="360">
</picture>
</p>
[](Resources/Design/evidence/readme-demo.mp4)
# Bookside / 서재
**Read your PDFs. Keep your thoughts beside them. Bring the context to your AI client.**
Bookside is a native macOS PDF reader with per-book notebooks, local OCR, a built-in
learning chat, and a CLI plus read-only MCP server for agents such as Claude Code and Codex. Your PDFs stay in
their folders; notes, bookmarks, and reading progress live in a local SQLite database.
[한국어](README.ko.md) | [Get started](docs/01-getting-started.md) |
[User guide](docs/02-reading-and-notes.md) | [CLI & MCP](docs/03-cli-and-mcp.md) |
[Contribute](CONTRIBUTING.md)
The demo is recorded from the running app; the [full video with English narration and captions](Resources/Design/evidence/readme-demo.mp4)
runs 1:54. It reads Franz Kafka's *The Metamorphosis* in Ian Johnston's public-domain translation:
it saves an excerpt and notes, asks Pi to compare Gregor's family, and runs OCR on scanned pages.
The interface currently uses Korean labels; the guides explain the relevant controls in English.
## What you can do
- **Read and resume.** PDFKit rendering, text view, keyboard navigation, and three
shelves for not started, reading and finished books, with dated read-through history.
- **Organize your reading.** Note-count badges and sorting by title, activity, notes
or read-through count; the last order survives relaunch.
- **Write beside the book.** Autosaved notebooks, quoted passages with comments,
persistent highlights, bookmarks, and Markdown export.
- **Find text through OCR spacing.** Korean and English keyword search ignores
extra spaces and line breaks by default, with an exact-spacing option.
- **Recognize scanned pages locally.** Optional OCRmyPDF + AppleOCR creates a new
PDF using Apple Vision. Review it before connecting it to the same book and notes.
- **Ask your own AI client.** `bookside-cli` and its agent skill give agents books, pages,
search results, and notes; five read-only MCP tools also expose the saved reading context.
Model calls happen in the client.
- **Use a native workspace.** SwiftUI/AppKit, light and dark appearance, resizable
side panels, and system accessibility preferences.
<details>
<summary>More native app screenshots</summary>
**Reading view and notebook**
**Reading shelves and history**
**Dark appearance**
**OCR review**
Screenshots use authored fixtures; the demo uses a public-domain book. See [capture provenance and verification](docs/06-development.md#screenshots-and-ui-verification).
</details>
## Quick start
### Install with Homebrew
```sh
brew install --cask nomadamas/bookside/bookside
```
The [NomaDamas tap](https://github.com/NomaDamas/homebrew-bookside) selects the DMG
for your Mac, checks its SHA-256, installs `Bookside.app`, and adds `bookside-cli`
to your Homebrew `bin` directory. This installs the same developer preview described
below. See [Homebrew installation and updates](docs/01-getting-started.md#install-with-homebrew).
### Download a DMG
Download the [v0.3.0 developer preview](https://github.com/NomaDamas/bookside/releases/tag/v0.3.0)
for macOS 14 or later:
| Mac | Download |
| --- | --- |
| Apple Silicon (M series) | [Apple Silicon DMG](https://github.com/NomaDamas/bookside/releases/download/v0.3.0/Bookside-0.3.0-macos-arm64.dmg) |
| Intel | [Intel DMG](https://github.com/NomaDamas/bookside/releases/download/v0.3.0/Bookside-0.3.0-macos-x86_64.dmg) |
Verify the matching SHA-256 file on the release page, open the DMG, and drag
`Bookside.app` to Applications. Quit the old app before replacing it; your library
data stays outside the app. These previews are **ad-hoc signed and not notarized by
Apple**, so macOS may block the first launch. See [installation and Gatekeeper](docs/01-getting-started.md#install-the-developer-preview).
### Build from source
You need a compatible Xcode/Swift toolchain, Python 3 for the build helpers, and
Node.js 22.19 or later, pnpm and Bun for the learning chat bridge.
Native UI verification has used macOS 26.6.2 with Xcode 27 / Swift 6.4 on Apple
Silicon. Both architectures pass build and copied-CLI checks in CI; this does not
establish native UI compatibility with every supported Mac.
```sh
git clone https://github.com/NomaDamas/bookside.git
cd bookside
./scripts/build-app.sh
./scripts/open-app.command
```
Choose **PDF 추가…** (`Command-O`) or **폴더 추가…** (`Command-Shift-O`), open a
book, and write in **메모**. Reading and notes work without OCR or an AI account.
To install the built app in `~/Applications/Bookside.app`:
```sh
./scripts/install-local.command
```
To package a verified local DMG, run `python3 scripts/release.py package`. See the
[release guide](docs/09-releasing.md) for versions, architecture-specific assets,
signing, and draft GitHub Releases.
The local app is ad-hoc signed by default. See [setup and troubleshooting](docs/01-getting-started.md)
for toolchain selection, updates, and an isolated sample library.
## Learning chat
Bookside has a dedicated AI panel, **Pi**, beside a Preview-style reading
workspace. Page thumbnails, notes, excerpts and search live on the left. Pi manages the
conversation through official Claude Code/Codex executors, with model selection and
English learning instructions. Questions can search and read the selected book, using the
current page as the reading location. Current-page and explicit page-range scopes are available.
Replies show verified source-page links and how much of the permitted range was read.
The default automatic mode chooses text, tables or visual explanations for the question.
Codex can also generate images through its official image tool and keep them in the chat.
The conversation reads as a transcript: each question, the pages the agent searched and
read, the answer, and how long the reply took with which executor and model.
The panel renders Mermaid, SVG and isolated HTML and plays user-selected audio/media.
Questions can be edited in place and retried; conversation edits and clearing can be undone.
If Node.js or an account connection is missing, the panel says so and links to
**Settings > Pi**, which manages accounts, models and the direct-request option.
Replies stay with each book.
The chat needs Node.js 22.19 or later and the official Claude Code or Codex executable.
The rest of the app works without them, and the panel says what is missing.
Read [the chat's scope, official account routes and verification](Resources/Design/PI-AGENT.md)
before connecting. Verification evidence distinguishes local tests and native interactions
from live Claude/Codex requests and image generation. Each user signs in through the
official account flow; provider availability and limits still apply.
## Optional: connect an AI client
Agents that run shell commands can use the library through `bookside-cli`. Install the bundled
[`bookside` skill](skills/bookside/SKILL.md) with `npx skills add NomaDamas/bookside --skill bookside`
(or `bunx`). It covers finding books, searching and reading pages, and changing
notes, bookmarks or OCR copies only when you ask.
Clients that use MCP can connect to the read-only server instead. After installing the
app, run this helper from a cloned repository:
```sh
./scripts/register-mcp.command
```
This registers the installed CLI with available Codex and Claude Code clients,
preserving existing `bookside` entries. Restart the clients and verify the tools.
For example: “Find my book, search for attention, and cite the PDF pages.”
The CLI and MCP can read your library and notes. Your agent may send those results to its model
provider, according to its configuration. **AI로 이어가기** in the book title menu
copies a context prompt to the clipboard. See the [CLI and MCP reference](docs/03-cli-and-mcp.md)
and [data and privacy guide](docs/07-data-and-privacy.md).
## Documentation
| I want to… | Read |
| --- | --- |
| Build, launch, or update the app | [Getting started](docs/01-getting-started.md) |
| Read, search, take notes, and use shortcuts | [Reading and notes](docs/02-reading-and-notes.md) |
| Use the CLI or connect an MCP client | [CLI and MCP reference](docs/03-cli-and-mcp.md) |
| Install OCR, review a copy, or return to the original | [OCR guide](docs/04-ocr.md) |
| Understand the modules, book identity, and storage | [Architecture](docs/05-architecture.md) |
| Build changes and run the relevant checks | [Development and testing](docs/06-development.md) |
| Back up data or understand privacy boundaries | [Data and privacy](docs/07-data-and-privacy.md) |
| Audit and repair an existing OCR text layer | [Advanced PDF maintenance](docs/08-pdf-maintenance.md) |
| Package a DMG or prepare a version/tag/release | [Release guide](docs/09-releasing.md) |
| Report a bug or submit a pull request | [Contributing](CONTRIBUTING.md) |
| Work on this repository with a coding agent | [AGENTS.md](AGENTS.md) |
The [documentation index](docs/README.md) also links the design reference,
performance measurements, and historical native verification records.
## Current scope
Bookside reads PDFs on macOS. EPUB support, semantic search, a built-in model,
and cross-device note sync are not implemented. iCloud PDFs can be indexed without
bulk downloads; download a file in Finder before reading it. The deployment target
does not imply that every earlier macOS version has been tested.
Search normalization leaves the source text unchanged. OCR quality reports identify
review risks; they do not certify that every word is correct. [OCR limitations](docs/04-ocr.md#quality-checks-and-limitations)
describe the checks and their coverage.
## License
[MIT](LICENSE) for the app and core code. Dependency notices are included in the
built app. External OCR tools retain their own licenses and are installed separately.
The source distribution excludes users' books, extracted book text, and personal notes.