Read beside the evidence. Remember what matters.
A local-first desktop companion for reading research papers. Your PDF reader stays where it is. Margin keeps what you decided was important.
Researchers already have good PDF readers, reference managers, and assistants that answer questions about papers. What is missing is a low-friction place to preserve only the parts a reader decided were worth keeping.
Margin is that place. It sits beside the reader you already use, pulls the paper's figures, tables, and section structure into a browsable form, and lets you attach durable Markdown notes to that evidence.
The PDF stays evidence. Your confirmed notes stay the source of truth.
Margin gives every paper three views and a note composer that never leaves the screen.
Every figure and table is detected from the page itself, cropped with its label and caption intact, and kept in the paper's own order. One click links a figure to the note you are writing, and the same click on a section or a page works the same way.
Notes are plain Markdown and yours to change. Write one, paste an excerpt from another assistant and let AI tighten it, attach the evidence it came from, then find it again months later.
Evidence is whatever you were looking at: a figure, a table, a section, or a bare page. A note can carry several at once, and search and filters reach all of them.
A polished draft never replaces what you wrote. It arrives as a proposal you can edit, compare against your original word by word, ask to be redone in your own words, or throw away. Save stays available the whole time, so a slow or failing model never costs you the note.
Every note can be edited, deleted, and copied. Search runs over note text, and the evidence filter narrows the list to a single figure or table, or to notes with no evidence attached at all.
Paper metadata and the section structure, with a rendered page preview. Sections and visuals can be corrected by hand when automatic extraction gets something wrong, and your corrections survive re-analysis.
~/Library/Application Support/Margin/
margin.sqlite
papers/<paper-id>/source.pdf
papers/<paper-id>/visuals/
papers/<paper-id>/pages/
logs/
- Registered PDFs become immutable local snapshots. The original file is never modified.
- Duplicates are recognised by SHA-256, so the same paper never lands twice.
- Notes, sections, and crops stay usable with no network connection.
- Deleting a paper removes its PDF, derived assets, analysis, and notes after confirmation.
- Margin never reads or stores your authentication tokens.
Margin uses the local codex app-server and the GPT-5.6 model advertised to your own ChatGPT account.
- Authentication belongs to Codex, through Sign in with ChatGPT. There is no API key to manage.
- Model calls use ephemeral, read-only threads. They are not treated as Margin's memory.
- Candidate pages are chosen locally before any image is sent.
- Crop geometry is decided by deterministic code from the page's own text and pixels. The model contributes judgement, not coordinates.
- Each task picks its own model: the strongest advertised one for extraction, whose results are stored without review, and the fast one for rewriting a note, where you read every draft before keeping it.
- A polished draft is checked by code before you see it. Numbers, names, length, and language are compared against what you wrote, and any drift is reported on the draft itself.
- If AI is unavailable, every paper, note, and export keeps working.
You bring your own ChatGPT account and use the Codex usage already included with it. Margin adds no billing and buys nothing on your behalf.
- macOS
- Node.js 22.12 or newer
- A current Codex CLI, for the AI-assisted actions only
No API key, paid SDK, or Apple Developer Program membership is required.
git clone https://github.com/junjunjunbong/Margin.git
cd Margin
npm install
npm run devMargin opens with a built-in, Apache-2.0 licensed sample paper, so the whole workflow is available before you add anything of your own. Drag in a text-based PDF, or use + Add PDF.
Run every check the project holds itself to:
npm run check| Library, search, metadata editing, confirmed deletion | Available |
| PDF validation, immutable snapshots, duplicate detection | Available |
| Section and figure/table extraction, resume, retry | Available |
| Manual correction of sections and visuals | Available |
| Markdown notes with evidence links | Available |
| Note editing, deletion, copying, search, evidence filter | Available |
| Export all notes as Markdown | Available |
| Organize saved notes with AI, as a one-time result that is never written back | Available |
| Restored paper, tab, scroll, zoom, and window state | Available |
| Polishing a note with AI, with an editable draft, a diff, and revision requests | Available |
| Linking a note to any figure, table, section, or page | Available |
| Editing the organized result, asking for it again, and saving it as Markdown | Available |
| A signed, double-clickable application | Not planned; see below |
Margin supports academic PDFs with a real text layer. Scanned, encrypted, and text-inaccessible files are refused at registration, with the reason stated. There is no OCR.
For figures and tables, Margin renders the page, locates the printed label and caption, and keeps the complete visual together with that caption. Subfigures are treated as one parent figure, and a table continuing across pages stays one visual with several page crops. Algorithms, equations, listings, and external supplementary files are out of scope.
Extraction is measured against a private corpus of the maintainer's own reading, and against papers the code has never seen, using an automated checker that verifies label coverage, caption completeness, and that no crop edge cuts through a glyph or rule. It is good, not infallible: when it is wrong, the correction tools are one click away and your fix is preserved.
- No telemetry, no analytics, no account.
- Papers and notes never leave the machine except as page images sent to your own Codex session for the actions you start.
- This repository contains no research PDFs, rendered pages, crops, or ground-truth data. A boundary check (
npm run corpus:guard) enforces that on every run.
Electron, React, TypeScript, and Vite. PDF.js for parsing, text coordinates, rendering, and previews. SQLite for local persistence. The Codex App Server over local JSON-RPC. No Python worker and no standalone backend.
Margin runs from source. There is no signed, notarized .dmg, because producing one requires an Apple Developer Program membership, which the project's zero-cost policy rules out. If you want to hand the app to someone who will not run npm, that policy is the decision to revisit first.
- General paper Q&A or web search
- Cross-paper research memory or recommendations
- A replacement PDF reader or annotation system
- Live synchronisation with other readers
- OCR and guaranteed non-English support
- Cloud sync and collaboration
- Signed or notarized binary distribution
Apache-2.0. Runtime and development dependencies are restricted to approved permissive licenses; GPL, AGPL, non-commercial, source-available restrictions, and paid SDKs are not allowed. See THIRD_PARTY_NOTICES.md and run npm run license:check for the installed graph.