A browser side panel that places the paper or post you're reading in its field: what it builds on, who built on it, who argues with it, who wrote it, and what people said about it. It runs on your own LLM subscription through Claude Code or Codex, and lets you keep what you learn as notes, recall questions, reading lists and Markdown.
- Where this sits. Which ongoing line of work the paper joins, what it claims is new, where it's contested, and 3–5 papers to read first. The model works only from the citation data it's given, so it can't invent references.
- Lineage. Three groups: Builds on, Built upon by, In conversation with. Each paper carries a relation label (extends, uses its method, contrasts, critiques…) and the sentence where the citation appears. The → button re-centres the panel on that paper, so you can follow a line of work.
- Authors. Affiliation at the time of the paper, h-index, research topics, and a short background from a web search, with source links.
- Discussion. Hacker News and Reddit threads with top comments, notable blog posts and critiques found on the web, and a summary of how the work was received. X, Bluesky and alphaXiv appear as search links.
- Graph view. A timeline: earlier work on the left, later work on the right.
It works on arXiv, DOI links, bioRxiv/medRxiv, Semantic Scholar, ACL Anthology, OpenReview, ACM, PubMed and any page with standard citation_* meta tags. Any other page is treated as a blog post, and the papers it links to become its lineage.
- ☆ Save a paper with a copy of its reading, or ☆ any paper in its lineage to add it to a reading list (to read / reading / read).
- Your notes on each paper save as you type.
- Test yourself: three recall questions per paper, with answers hidden until you click.
- Threads collect a rabbit hole: start one from any paper, and everything you save or open while it's active is filed there, including the trail of papers you followed.
- Markdown export of a paper, a thread or the whole library. The files have front matter for Obsidian, and the recall questions use
Q :: Alines that spaced-repetition plugins turn into flashcards.
You need a Chromium browser (Chrome, Brave, Arc, Edge) on macOS, Python 3, and either Claude Code or Codex installed and signed in.
-
Clone this repo.
-
Open
chrome://extensions, turn on Developer mode, click Load unpacked, and pick the cloned folder. -
From the cloned folder, run the one-time setup:
python3 bridge/install.py
It finds the Margin extension you just loaded and registers a small helper that the browser starts on its own whenever Margin needs a model. No server keeps running.
-
Open a paper, click the Margin icon (or press Alt+M), and choose Claude Code or Codex in settings (the gear).
Re-run python3 bridge/install.py after pulling updates. python3 bridge/install.py --uninstall removes the helper.
The browser can't run programs itself, so Margin uses native messaging: bridge/install.py copies bridge/native_host.py to ~/Library/Application Support/Margin and registers it under the name com.margin.bridge. Only the Margin extension ID is allowed to start it. It is copied out of the repo because macOS blocks browsers from reading ~/Desktop and ~/Documents. The installer also records where claude, codex and node live, because browsers start helpers without your shell's PATH. Errors go to ~/Library/Logs/Margin/host.log.
For each request the helper runs one command, claude -p or codex exec, on your subscription. Page text reaches the model, so both are locked down:
- Tools: the reading call has no tools, and the research call can use web search only. There is no shell, no file access and no MCP servers.
- Your own setup is ignored: Claude Code runs with
--safe-mode, which skips your CLAUDE.md, hooks and plugins. Codex runs with--ignore-user-config --ignore-rules, a read-only sandbox, shell and code tools off, and project instructions off. - Nothing is saved: neither CLI keeps a session.
Source links: links from web research are kept only if they appeared in a search result (Claude Code), or if they actually load when fetched (Codex, whose output doesn't include search results).
bridge/margin_bridge.py is an alternative: an HTTP server on 127.0.0.1:8788 that you start yourself. It accepts requests only from an extension page or the dev harness, and only with its custom header, so other websites can't use it. Both paths share bridge/core.py, and none of this needs anything beyond the Python standard library.
- To your model provider (Anthropic or OpenAI), through your own CLI: the page title, abstract, the paper's citation data and discussion snippets, and for blog posts, a text excerpt of the page.
- To Semantic Scholar, OpenAlex, Hacker News, Reddit and arXiv: paper identifiers and titles, to look up the citation graph, authors and discussion.
- Stays in your browser's extension storage: settings, cached results, your library and notes. There is no Margin server.
| Section | Source |
|---|---|
| Lineage, citation intents and context sentences | Semantic Scholar, falling back to OpenAlex when Semantic Scholar rate-limits |
| Reading, relation labels, recall questions, reception summary | Your model, from the listed citations and threads only |
| Affiliations | Publisher citation_author_institution tags, the arXiv HTML author block, Semantic Scholar |
| Author background, web commentary | A second model call with web search |
| Discussion threads | Hacker News (Algolia API), Reddit |
- Rate limits: Semantic Scholar's free public pool rate-limits often. A free API key, added in settings, fixes that.
- OpenAlex fallback: it has no citation-context sentences, thin coverage of preprints, and some arXiv-only papers are missing entirely. The panel says when it's in use.
- Speed: a new page takes 30–90 seconds, depending on the model. Results are cached.
dev.html?url=<paper url> runs the panel as a normal web page without browser extension APIs, talking to the HTTP bridge:
python3 bridge/margin_bridge.py &
python3 -m http.server 8787
open "http://localhost:8787/dev.html?url=https://arxiv.org/abs/2305.18290"There's no build step: plain ES modules, Manifest V3.
MIT