# SparXiv

A quiet arXiv reader that runs on your machine. No home page, no feed, no recommendations. It opens as a single search field on a black screen, and everything else appears only once you have asked for it.

![SparXiv](media/sparxiv.gif)

Papers open as reflowed HTML rather than a PDF page image, so text wraps to the column, math is real MathML, and the whole thing is styled to match the editor you already stare at. The PDF is one key away when you want the figures exactly as typeset.

## Why

Existing readers each get one part right. alphaXiv embeds papers well and has collections but buries them under a social feed. OpenAlex has a genuinely configurable interface and poor previews. arXiv itself has the library and no interface at all. SparXiv takes the embedded reading and the collections, the configurability, and the arXiv API, and drops everything else.

## Reading

![Reader](media/reader.png)

Search results sit in a collapsible sidebar. One click opens a paper beside them, `⌘`-click opens a second paper next to the first when the window is wide enough for two columns.

![Split](media/split.png)

Papers come from arXiv's own LaTeXML build, falling back to ar5iv when a paper has none. Neither is embedded or framed: the server fetches the HTML, extracts the article, drops every script, stylesheet, banner and tracker, rewrites the images through a proxy restricted to arXiv hosts, and hands back markup that this stylesheet owns entirely. A paper with no HTML build anywhere says so and offers the PDF.

![PDF](media/pdf.png)

The PDF renders through pdf.js into the same chrome, inverted for dark by default, pages painted as you approach them.

## Collections

`S` saves the focused paper, `⌘K` files it into a named collection. Collections live in one JSON file and are the point of the whole thing being local:

```bash
cat ~/.sparxiv/collections.json
```

Anything that reads JSON can read your library. The running server also exposes it over HTTP:

| Route | Does |
| --- | --- |
| `GET /api/collections` | every collection with its papers |
| `GET /api/collections/:id` | one collection |
| `GET /api/saved` | every saved paper, flattened, tagged with its collection |
| `POST /api/collections` | create, `{name}` |
| `POST /api/collections/:id/papers` | add a paper object |
| `DELETE /api/collections/:id/papers/:arxivId` | remove, version suffix optional |

### From Claude

`mcp/server.js` speaks MCP over stdio and reads the same file with no server running. It has four tools: `list_collections`, `read_collection`, `search_saved`, and `save_paper`, the last of which pulls metadata from arXiv by id.

```json
{
  "mcpServers": {
    "sparxiv": { "command": "node", "args": ["/absolute/path/to/SparXiv/mcp/server.js"] }
  }
}
```

## Configuration

Everything is one file at `~/.sparxiv/config.json`, editable in the app with `⌘,` and written back live. It carries the colours, the two font stacks, the reading column width and leading, the result density, and every keybinding. Deleting a key restores its default; deleting the file resets everything.

```json
{
  "reader": { "mode": "html", "font": "ui", "width": 720, "fontSize": 17, "invertPdf": true },
  "layout": { "sidebar": true, "sidebarWidth": 340, "splitMinWidth": 1100 },
  "theme": { "bg": "#0d0d0e", "fg": "#d6d6d6", "line": "#1a1a1c" },
  "keys": { "focusSearch": "/", "toggleSidebar": "mod+b", "toggleMode": "p", "save": "s" }
}
```

`mod` is cmd on a Mac and ctrl elsewhere, so one config reads correctly on both. `?` lists every binding as currently configured.

## Searching

Plain words are tried as a phrase first and as an AND over the content words second, because arXiv indexes no stopwords: `sparse mixture of experts` returns nothing ANDed and 252 papers as a phrase, while `transformer protein folding` is the reverse. Field prefixes pass through untouched, so `cat:nlin.CG AND all:lenia` does what it says. An arXiv id or an abs URL goes straight to that paper.

## Running

```bash
npm install && npm start
```

Then open `http://127.0.0.1:7391`. It binds to loopback only. Node 20 or newer, one dependency (pdf.js).

```bash
bash tests/run-tests.sh --smk
```

## Keys

| | |
| --- | --- |
| `/` `Esc` | focus search, back out |
| `J` `K` `↵` | move through results, open |
| `⌘↵` | open beside the current paper |
| `P` | swap between HTML and PDF |
| `S` `⌘K` | save, save into a collection |
| `⌘S` | collections |
| `⌘B` `⌘W` | sidebar, close pane |
| `⌘=` `⌘-` `⌘0` | reading size |
| `⌘,` `?` | config, key list |

## License

MIT