inleaf-reader

KO | EN

gitlite — search

#react #developer-tools #claude-code #openai #reactjs #ai-agents #sql #svg #nextjs #postgresql

(★ 9)

A focused, local-first PDF reader for VS Code—read, annotate, translate, save words, and keep portable sidecar data.

File Explorer

ZIP Download

- inleaf-reader-example.png
- inleaf-reader-icon.png
- inleaf-reader-logo.png
- inleaf-reader-toolbar-dark.svg
- inleaf-reader-toolbar-light.svg
- - pdf.worker.min.mjs
- reader-app.css
- reader-app.js
- reader-pdf_viewer.js
- - 00.json.gz
  - 01.json.gz
  - 02.json.gz
  - 03.json.gz
  - 04.json.gz
  - 05.json.gz
  - 06.json.gz
  - 07.json.gz
  - 08.json.gz
  - 09.json.gz
  - 0a.json.gz
  - 0b.json.gz
  - 0c.json.gz
  - 0d.json.gz
  - 0e.json.gz
  - 0f.json.gz
  - 10.json.gz
  - 11.json.gz
  - 12.json.gz
  - 13.json.gz
  - 14.json.gz
  - 15.json.gz
  - 16.json.gz
  - 17.json.gz
  - 18.json.gz
  - 19.json.gz
  - 1a.json.gz
  - 1b.json.gz
  - 1c.json.gz
  - 1d.json.gz
  - 1e.json.gz
  - 1f.json.gz
  - 20.json.gz
  - 21.json.gz
  - 22.json.gz
  - 23.json.gz
  - 24.json.gz
  - 25.json.gz
  - 26.json.gz
  - 27.json.gz
  - 28.json.gz
  - 29.json.gz
  - 2a.json.gz
  - 2b.json.gz
  - 2c.json.gz
  - 2d.json.gz
  - 2e.json.gz
  - 2f.json.gz
  - 30.json.gz
  - 31.json.gz
  - 32.json.gz
  - 33.json.gz
  - 34.json.gz
  - 35.json.gz
  - 36.json.gz
  - 37.json.gz
  - 38.json.gz
  - 39.json.gz
  - 3a.json.gz
  - 3b.json.gz
  - 3c.json.gz
  - 3d.json.gz
  - 3e.json.gz
  - 3f.json.gz
  - manifest.json
- argos_translate_daemon.py
- build_ecdict_compact.py
- copy_pdfjs_assets.mjs
- test-annotation-exports.mjs
- test-capability-framework.mjs
- test-command-icon.mjs
- test-ecdict-worker.mjs
- test-inline-annotation-editor.mjs
- test-pdf-identity.mjs
- test-reader-concurrency.mjs
- test-reader-storage.mjs
- test-reading-notes.mjs
- test-translation-contract.mjs
- test-webview-resilience.mjs
- test-webview-worker.mjs
- - contracts.ts
  - hostRegistry.ts
  - hostTypes.ts
  - preferences.ts
  - protocol.ts
- annotationExports.ts
- annotationTypes.ts
- argosTranslationDaemon.ts
- ecdictClient.ts
- ecdictWorker.ts
- extension.ts
- identity.ts
- paperReaderPanel.ts
- pdfIdentity.ts
- readerDataTypes.ts
- readerMessages.ts
- readerStorage.ts
- readingNotes.ts
- sidecarSchemas.ts
- translationContract.ts
- translationService.ts
- translationTypes.ts
- - annotationModel.ts
  - main.tsx
  - messages.ts
  - pdfSelection.ts
  - selectionShade.ts
  - styles.css
  - types.ts
  - vscodeApi.ts
.gitignore
.nvmrc
.vscodeignore
AGENTS.md
CONTRIBUTING.md
LICENSE
NOTICE
package-lock.json
package.json
project_map.md
README.md
README.zh-CN.md
THIRD_PARTY_NOTICES.md
tsconfig.json
tsconfig.webview.json
vite.webview.config.mts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <img src="assets/inleaf-reader-logo.png" width="112" alt="Inleaf Reader logo">
  <h1>Inleaf Reader</h1>
  <p><strong>Your Books. Your AI. Your Flow.</strong></p>
  <p>Read PDFs in VS Code, ask your own AI, and keep your thoughts flowing.</p>
</div>

[English](README.md) | [简体中文](README.zh-CN.md)

![Inleaf Reader open beside an AI assistant, with PDF highlights and annotations](https://raw.githubusercontent.com/WORMMMMMM/inleaf-reader/main/assets/inleaf-reader-example.png)

## What is Inleaf Reader?

Inleaf Reader turns VS Code into a focused reading space for papers and books.
It keeps frequent actions close to the page and lets you use the AI tools you
already trust beside your document. You can ask for background, investigate a
question, annotate a passage, translate text, or save a word without repeatedly
leaving the reading context.

Your reading data stays in ordinary files next to the PDF. This means it remains
under your control, can be backed up or synchronized with the tools you already
use, and is straightforward for AI tools to inspect and work with.

### At a glance

- **Read comfortably:** continuous scrolling, page progress, fit controls, and trackpad zoom.
- **Bring your own AI:** work beside Codex, Claude Code, or another assistant instead of being locked into a paid reader-specific AI.
- **Annotate in place:** highlight, underline, add notes and tags, then edit them beside the original text.
- **Translate as you read:** use the bundled offline dictionary, local Argos Translate, DeepSeek, or LibreTranslate.
- **Build a wordbook:** save useful English words and their structured definitions for each PDF.
- **Keep data AI-ready:** annotations, vocabulary, exports, and progress use portable files beside the document.
- **Stay focused:** the side panel starts hidden and appears only when you ask for it.

## Organize reading notes (preview)

Open the annotations panel and click **整理阅读笔记** (Organize reading notes).
Choose the current PDF or multiple PDFs, enter PDF page ranges for each
(such as `1-5, 8`; leave blank for all pages), and choose tags, whether to include
only highlights with comments, and an output style: faithful excerpts, thematic
notes, or a shareable article. Confirm the annotation count and choose a folder
to export `notes.md`, `notes.json`, and `整理说明.md`. Cross-page annotations
are preserved in full rather than truncated.

Give the packet to your own AI to produce a preview before writing to Notion.
The extension does not connect to or automatically upload to Notion. Exports
include original text, personal notes, and source identifiers, but no absolute
local paths. Unidentified titles, authors, and printed page numbers remain unknown.

## Who is it for?

Inleaf Reader is especially useful if you:

- read papers or technical books while working in VS Code;
- want annotations and progress to stay with the original PDF;
- use coding assistants such as Codex or Claude Code beside your reading window;
- prefer offline or user-controlled tools over a mandatory cloud account.

## Install

### From a VSIX

Download the VSIX from the
[latest GitHub release](https://github.com/WORMMMMMM/inleaf-reader/releases/latest),
then choose **Extensions: Install from VSIX...** in VS Code.

You can also install it from a terminal:

```bash
code --install-extension inleaf-reader-0.1.3.vsix
```

After installation, run **Developer: Reload Window** once if the reader command
does not appear immediately.

> **Moving from an earlier pre-Inleaf build?** VS Code treats the current
> `ziming.inleaf-reader` identity as a separate extension. Install Inleaf Reader,
> remove the earlier extension, and reopen each PDF once. Existing local
> sidecars beside that PDF are copied into `.inleaf-reader/` without overwriting
> current files. Provider settings and API keys should be configured again.

### From the VS Code Marketplace

When the public Marketplace release is available, search for **Inleaf Reader**
in the Extensions view and select **Install**.

## Start reading in three steps

1. Open a PDF in VS Code, then click the blue nested-book icon in the editor title bar. You can also right-click the PDF and choose **Inleaf Reader: Open Paper Reader**.
2. Select text to highlight it, underline it, write a note, translate it, or save a word.
3. Continue reading. Annotations and page progress are saved automatically—there is no separate Save button.

The right panel stays hidden at startup. Use **Show panel** to browse
annotations, saved words, and translation results. Use the adjacent
**Settings** button to enable or hide reading capabilities, change their panel
order, and configure translation without leaving the reader.

## What happens to my data?

For a document named `paper.pdf`, Inleaf Reader automatically maintains these
versioned JSON files in a `.inleaf-reader` folder beside it:

```text
.inleaf-reader/
  paper.pdf.annotations.json   # highlights, underlines, notes, and tags
  paper.pdf.wordbook.json      # saved words
  paper.pdf.progress.json      # last reading position
```

The following files are created only when you choose the matching export
action:

```text
paper.pdf.annotations.md     # Markdown export
paper.pdf.annotated.pdf      # PDF export with visible marks and comments
```

These are normal local files. You can copy or synchronize them through Git,
iCloud Drive, Dropbox, Syncthing, or another file-sync tool. JSON updates are
written atomically, validated when read, and versioned with `schemaVersion`.
Previous valid JSON is kept as a `.bak` recovery file. If the current file is
invalid, Inleaf Reader restores the backup and preserves the unreadable copy
with a `.corrupt-<timestamp>` suffix. Legacy array-based sidecars are migrated
automatically. Because the formats are structured and documented, an AI tool
with access to your workspace can reuse your annotations and vocabulary without
depending on a proprietary cloud database.

The top-level JSON shapes are intentionally simple:

```json
{ "schemaVersion": 1, "annotations": [] }
{ "schemaVersion": 1, "words": [] }
{ "schemaVersion": 1, "progress": { "page": 12, "updatedAt": "..." } }
```

If a PDF is moved or renamed, a lightweight content fingerprint helps Inleaf
Reader find and copy its missing sidecar files. Existing files at the new
location are never overwritten.

## Translation choices

| Mode | Best for | Network or setup |
| --- | --- | --- |
| Bundled ECDICT | Looking up one English word | Offline, no setup |
| Argos Translate | Local sentence and paragraph translation | Offline after installing Python and a language model |
| DeepSeek | Higher-quality academic translation | Uses your own API key and sends selected text to DeepSeek |
| LibreTranslate | A self-hosted or compatible translation service | Sends selected text to the endpoint you configure |

Single English words always prefer the bundled ECDICT dictionary, which contains
about 770,000 entries and can show phonetics, Chinese meanings, English
definitions, parts of speech, and word forms. The dictionary is split into
compressed shards; a background worker loads only the shard needed for the
current word, so ordinary PDF startup and lookup do not require the full
dictionary in memory.

### DeepSeek

Run **Inleaf Reader: Set DeepSeek API Key** or select DeepSeek from the reader's
**Settings** page. The key is stored in VS Code SecretStorage and is never
written to the Webview, settings, sidecar files, or logs.

Run **Inleaf Reader: Clear DeepSeek API Key** to remove it.

### LibreTranslate

Choose LibreTranslate and provide a compatible endpoint from the reader's
**Settings** page. Advanced users may set `inleafReader.translationProvider`
and `inleafReader.libreTranslateEndpoint` directly.

<details>
<summary><strong>Optional: set up local Argos Translate</strong></summary>

The VSIX does not include Python or the Argos neural model because those
dependencies are specific to each operating system.

On macOS or Linux:

```bash
python3 -m venv ~/.inleaf-reader-argos
source ~/.inleaf-reader-argos/bin/activate
python -m pip install --upgrade pip argostranslate
```

On Windows PowerShell:

```powershell
py -m venv $HOME\.inleaf-reader-argos
& $HOME\.inleaf-reader-argos\Scripts\Activate.ps1
python -m pip install --upgrade pip argostranslate
```

Install the English-to-Chinese model with the
[official Argos package API](https://github.com/argosopentech/argos-translate):

```python
import argostranslate.package

argostranslate.package.update_package_index()
packages = argostranslate.package.get_available_packages()
package = next(
    item for item in packages
    if item.from_code == "en" and item.to_code == "zh"
)
argostranslate.package.install_from_path(package.download())
```

Then set the Argos Python path from the reader's **Settings** page. Advanced
users may set `inleafReader.argosPythonPath` directly. For example:

```json
{
  "inleafReader.translationProvider": "argos",
  "inleafReader.argosPythonPath": "/Users/you/.inleaf-reader-argos/bin/python"
}
```

The first sentence translation starts the local daemon and loads the model.
Later requests reuse that process.

</details>

If translation does not work, run
**Inleaf Reader: Diagnose Translation Setup** to see what is available.

## Privacy

- Inleaf Reader does not currently collect telemetry or analytics.
- PDFs and all reading sidecars stay in paths you choose.
- Offline ECDICT lookup and local Argos translation stay on your machine.
- DeepSeek and LibreTranslate receive selected text only when you choose those providers.
- A lightweight path index is stored in VS Code global state for move/rename recovery; annotation and wordbook content is not stored there.

Review the privacy terms of any external translation provider before sending
sensitive text.

## Current limitations

- Scanned PDFs without a text layer cannot be selected unless OCR is performed separately.
- Header, footer, page-number, and figure exclusion is heuristic because many PDFs do not expose reliable document structure.
- Argos Translate requires separate Python and language-model installation.
- The current dictionary and local translation workflow are optimized for English-to-Chinese reading.
- Inleaf Reader is still in preview; keep important PDFs and sidecar data backed up.

## Commands

| Command | What it does |
| --- | --- |
| `Inleaf Reader: Open Paper Reader` | Opens the active PDF or lets you choose one. |
| `Inleaf Reader: Set DeepSeek API Key` | Stores or replaces a DeepSeek key securely. |
| `Inleaf Reader: Clear DeepSeek API Key` | Removes the stored DeepSeek key. |
| `Inleaf Reader: Diagnose Translation Setup` | Checks dictionary and translation readiness. |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, tests, and the manual
reader checklist. Issues and pull requests are welcome on
[GitHub](https://github.com/WORMMMMMM/inleaf-reader).

## Built with

- [PDF.js](https://mozilla.github.io/pdf.js/)
- [react-pdf-highlighter-plus](https://github.com/QuocVietHa08/react-pdf-highlighter-plus)
- [pdf-lib](https://pdf-lib.js.org/)
- [Argos Translate](https://www.argosopentech.com/)
- [ECDICT](https://github.com/skywind3000/ECDICT)

Third-party components and bundled assets remain subject to their respective
licenses. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for attribution.

## License

Inleaf Reader is open-source software released under the
[Apache License 2.0](LICENSE). You may use, modify, distribute, and use the
software commercially under the license terms. The license also provides an
explicit patent grant and requires applicable copyright and attribution
notices to be preserved.

inleaf-reader

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README