linXiv

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 39 Open GitHub ↗

A local-first database of your academic papers built to support arXiv papers and more

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# linXiv

A local-first desktop application for discovering, managing, and visualizing academic papers from arXiv and other sources. It bundles a native Rust backend (bundled SQLite storage, arXiv/OpenAlex/CrossRef sources, PDF text extraction, BibTeX/Obsidian export) with a React + TypeScript frontend and an interactive paper–author graph, all wrapped in a Tauri v2 desktop shell.

Upload your PDFs, create projects, manage notes, tags, and annotations to organize your library; all locally. linXiv aims to be a one-stop shop for researchers managing their literature, with the near-term goal of extending to research groups who want to share knowledge without going to the web.

> **Development status:** Pre-1.0 (current version `0.3.0`). The database schema is still evolving, but migration structure is in-place.

> **Licensing:** linXiv is GPLv3. The vendored [`linxiv-p2p`](https://github.com/linxiv-dev/linxiv-p2p) submodule (`src-tauri/crates/p2p`) is licensed separately under Apache-2.0.

<a href="https://youtu.be/t3aH28353P4">
 <img src="https://img.youtube.com/vi/t3aH28353P4/maxresdefault.jpg" width="800" alt="Watch the linXiv demo">
 </a>
 
 <a href="https://youtu.be/t3aH28353P4">▶ Watch the full demo (3:16)</a>

## Install

Prebuilt installers for Linux, macOS, and Windows are on the [releases page](https://github.com/linxiv-dev/linXiv/releases/latest):

| Platform | Download |
| --- | --- |
| Linux | `.deb`, `.rpm`, or `.AppImage` |
| macOS (Apple silicon) | `.dmg` |
| Windows | `.exe` (NSIS) or `.msi` |

The macOS and Windows builds are unsigned. On macOS, right-click the app → **Open** to get past Gatekeeper the first time. On Windows, click **More info** → **Run anyway** on the SmartScreen prompt.

### Installing via pip install

You can install linxiv via pip! It ships with a small API to programatically control your database in python and can be installedi as such

```sh
pip install linxiv          # everything below
pip install "linxiv[app]"   # same, extras are opt-in markers only
pip install "linxiv[cli]"
```

To build from source instead, start at [Clone](#clone).

## Clone

This repo has git submodules (`docs/adr`, `src-tauri/crates/p2p`). The npm scripts that touch Rust (`tauri`, `dev:api`, `build:all`) init them for you, so a plain `git clone` is fine if you build through npm. Cloning with submodules up front is still the fastest path, and is required if you run `cargo` directly inside `src-tauri/`:

```bash
git clone --recurse-submodules https://github.com/linxiv-dev/linXiv.git
# already cloned without --recurse-submodules?
git submodule update --init --recursive
```

## Table of Contents

- [Install](#install)
- [Clone](#clone)
- [Features](#features)
- [Architecture](#architecture)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install dependencies](#install-dependencies)
  - [Run in development](#run-in-development)
- [Building the desktop app](#building-the-desktop-app)
- [CLI](#cli)
- [MCP server](#mcp-server)
- [Graph visualization](#graph-visualization)
- [Data location](#data-location)
- [Acknowledgements](#acknowledgements)

## Features

- **Paper search & fetch** — Search arXiv, OpenAlex, or CrossRef by keyword; fetch by ID; resolve by DOI (arXiv → Semantic Scholar → CrossRef fallback). Results are saved to a local SQLite database with per-paper version tracking.
- **Projects** — Organize papers into projects; scope notes and highlight annotations to a paper within a project; archive, restore, and trash with soft-delete.
- **Notes & PDF annotations** — Attach freeform notes and PDF highlight annotations to papers, optionally scoped to a project.
- **Tags** — Tag papers and projects; list and manage the full tag set.
- **PDF management** — Download PDFs, import local PDFs (with first-page text and metadata extraction via native PDFium), and track total storage usage.
- **Full-text search** — Pull an arXiv paper's TeX source into a local SQLite FTS5 index, from the paper page, the CLI (`linxiv paper fetch-source` / `index-sources`), or the `fetch_full_text` MCP tool; library search then matches the paper's body, not just its metadata.
- **Import / export** — Import and export projects as `.lxproj` archives, import BibTeX (`.bib`), and export projects to BibTeX or Obsidian-flavored Markdown.
- **Interactive graph** — Force-directed network of papers and authors (Cytoscape rendering with an fCoSE / D3 layout), with real-time force controls.
- **TeX rendering** — MathJax renders LaTeX math in titles and abstracts, bundled locally for full offline use.
- **CLI & MCP server** — A headless `linxiv` CLI and an `linxiv-mcp` MCP server expose the same library over the terminal and to LLM clients such as Claude.
- **Peer-to-peer project sharing** — Share a project over [iroh](https://www.iroh.computer/) (QUIC + node tickets, no relay server to run) with end-to-end encrypted sync via keyhive + beelay CRDTs; you're the Hoster or a Reader of a share, and a Hoster can invite members as Editor or Viewer; join with a pasted ticket, mirror shared projects into your local library, and sync on your own schedule.

## Architecture

linXiv is a Tauri v2 app. The frontend is React 18 + TypeScript (Vite); the backend is native Rust and runs **in-process** inside the app — the webview calls it through a single `api` Tauri command over IPC, and streams PDFs and graph assets over a custom `linxiv://` scheme. There is no HTTP server and no Python in the packaged app. SQLite (bundled, FTS5) and PDF extraction (native `libpdfium`) are compiled in — see [docs/architecture.md](docs/architecture.md) for the full workspace layout.

## Setup

### Prerequisites

- [Rust toolchain](https://rustup.rs/) (stable, 1.85+) — builds the backend, CLI, MCP server, and Tauri shell
- [Node.js](https://nodejs.org/) 20.16+ (22+ recommended) — frontend / Tauri tooling
- System libraries — GTK 3, WebKit2GTK 4.1, and GLib on Linux; Xcode Command Line Tools on macOS; Microsoft C++ Build Tools on Windows

**See [docs/requirements.md](docs/requirements.md) for the copy-pasteable install commands per OS**, exact version reasoning, and what to do when `pkg-config` reports `gdk-3.0` missing.

### Install dependencies

```bash
npm install                       # frontend dependencies
bash scripts/fetch_pdfium.sh      # native libpdfium (PDF import/extraction; also a bundled Tauri resource, see below)
bash scripts/stage_rust_bins.sh   # builds + stages the linxiv/linxiv-mcp sidecars (see below)
```

Rust crates are fetched automatically on first `cargo`/`tauri` build.

> **Both scripts above are required before `cargo check`/`cargo build`/`tauri dev` will even compile — not just for a full `tauri build`** (they stage gitignored paths that `tauri-build` validates at compile time). See [docs/build.md](docs/build.md) if you hit a `resource path ... doesn't exist` error.

### Run in development

Native desktop window (recommended — runs the in-process Rust backend, hot-reloads the frontend):

```bash
npm run tauri dev
```

Browser-only dev loop (no native window; uses a dev-only HTTP shim that serves the backend over `/api`):

```bash
# terminal 1 — dev backend (linxiv-dev-server, HTTP shim over the Rust core)
npm run dev:api

# terminal 2 — Vite dev server on :5180 (proxies /api to the shim)
npm run dev
```

## Building the desktop app

The `linxiv` (CLI) and `linxiv-mcp` (MCP server) binaries ship inside the app as Tauri sidecars.

```bash
npm run build:sidecar   # fetch libpdfium + build/stage the CLI & MCP sidecars into src-tauri/binaries/
npm run tauri build     # build the app and bundle it
```

Or run both in one step:

```bash
npm run build:all
```

The installer/bundle is written to `src-tauri/target/release/bundle/`.

After installing the app, open **Settings** to:
- **Install CLI** — symlinks the bundled `linxiv` binary to `~/.local/bin/linxiv` (Linux/macOS) or writes a PATH shim on Windows.
- **Integrations** — register the bundled MCP server with a detected client (Claude Desktop, Claude Code, and others) by writing its config file.

## CLI

The `linxiv` binary is a headless interface to the same library the app uses. In a checkout you can run it without installing:

```bash
# from src-tauri/
cargo run -p linxiv-cli -- --help
```

Installed (via the app's **Install CLI**, or a staged/bundled build), invoke it directly as `linxiv`. All commands print JSON to stdout; pass `--help` to any command or subcommand for full options.

```bash
linxiv --version
linxiv search "attention is all you need" --max 5
linxiv fetch 2204.12985
linxiv paper get 2204.12985
```

Covers papers, tags, projects, notes, PDF annotations, PDFs, DOI resolution, authors, BibTeX import, trash, and library maintenance — see [docs/cli_ref/](docs/cli_ref/) for the full command reference.

## MCP server

`linxiv-mcp` is a stdio MCP server exposing ~60 tools (search, fetch, papers, projects, tags, notes, annotations, PDFs, trash, authors, import/export, settings, stats) so an MCP client like Claude can drive your library directly.

The simplest path is to install the desktop app and use **Settings → Integrations**, which registers the bundled server with a detected client.

To register manually with the Claude Code CLI, point it at the built or bundled binary:

```bash
claude mcp add linxiv -- /path/to/linxiv-mcp
```

Or add it to a client's MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "linxiv": {
      "command": "/path/to/linxiv-mcp"
    }
  }
}
```

In a checkout you can run it straight from source with `cargo run -p linxiv-mcp` (from `src-tauri/`).

## Graph visualization

Papers and authors form a force-directed network: papers connect to their authors and tags, laid out by a D3 force simulation and rendered with Cytoscape. The control panel exposes real-time sliders to control how the nodes and connections interact. The viewer, MathJax, D3, and the UI font are all bundled locally.

## Data location

The database (`papers.db`), managed PDFs, and the Obsidian vault live in the per-user app data directory for `com.linxiv.app` (e.g. `~/.local/share/com.linxiv.app` on Linux, `~/Library/Application Support/com.linxiv.app` on macOS). Set the `LINXIV_DATA_DIR` environment variable to override the location — the app, CLI, and MCP server all honor it, so they share one library.

## Acknowledgements

Thank you to arXiv for use of its open access interoperability!

linXiv owes a debt to [Qiqqa](https://github.com/jimmejardine/qiqqa-open-source), the open-source research management tool originally created by Jimme Jardine.

PDF text and metadata extraction is currently powered by [PDFium](https://pdfium.googlesource.com/pdfium/) (Google's PDF rendering library) via the [`pdfium-render`](https://github.com/ajrcarey/pdfium-render) Rust bindings.

linXiv

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README