A Terminal User Interface (TUI) application to stay up to date with recent arXiv submissions. Built with Python and Textual, featuring a persistent SQLite database. This tool was built with the help of AI to test AI capabilities and to build something useful for myself. The code is not pretty and I simply wanted to create a usable tool for myself.
The main goal of the tool is to stay up to date with recent publications in your field
This tool is not associated with arXiv and we thank arXiv for use of its open access interoperability. We also thank INSPIRE for providing their API free of charge for educational and informational use. The tool has been developed with the help of a mix of Claude Sonnet 4 and Gemini 2.5 Pro.
Stay up to date with recent publications in your field. New arXiv articles get fetched automatically according to predefined categories, and can be further filtered using custom filters. Read something you like? Save it for future reading right in your local PDF reader!
- 🚀 Smart Fetching: Automatic background fetching of recent arXiv articles (last 7 days)
- 🔍 Advanced Filtering: Configure custom filters with category and text-based criteria
- 📖 Reading Status: Track viewed articles automatically
- 🗃️ Persistent Database: All articles stored locally in SQLite for fast offline access
- 📁 Category Management: Organize articles by arXiv categories (cs.AI, hep-th, etc.)
- 🏷️ Tag Management: Add custom tags to articles and filter by tags
- 📝 Notes Management: Create and edit markdown notes for articles
- 📚 Citations Information: Fetch and view BibTeX citations from Inspire-HEP & browse references and citations
- 💾 Save System: Save and organize your favorite articles
- 📱 Modern TUI: Beautiful, responsive terminal interface with mouse support
- 📄 PDF Integration: Download and open PDFs directly from the application
- 🔎 Full-Text Search: Search across titles, authors, and abstracts
The ArXiv Reader interface showing the category sidebar, article list, and abstract panel
The Notes interface showing the markdown editor for taking notes on articles
The INSPIRE citation interface showing BibTeX citation information
- Feed Configuration: Categories and filters are configured in the YAML config file, which determines what articles appear in your personalized feed
- Stay Current: Browse articles from your feed to keep up with the latest publications in your field
- Save for Later: Mark articles you want to revisit by saving them to your Library using the "save" key
- Automatic Cleanup: Read articles in your feed are automatically removed after a retention period (default: 30 days) to keep your feed fresh
- Permanent Library: Saved articles remain in your library indefinitely and can be enhanced with custom tags and markdown notes
- Global Discovery: Search the entire arXiv database using "Global search" and add interesting articles directly to your library
- Citation Network: Explore the academic network by browsing papers that reference a given article or papers that cite it
- Python 3.8+
- Internet connection for fetching articles
- Clone the repository:
git clone <repository-url>
cd arxivreader- Install locally with pip:
# Install in development mode (recommended for local development)
pip install -e .
# Or install normally
pip install .- Run the application:
artui- First time setup: After opening the application for the first time, press the 'r' button to refresh and populate the database with recent articles.
ArTui stores all user data in a centralized location for better organization and portability:
Default Location: ~/.artui/
Directory Structure:
~/.artui/
├── config.yaml # Configuration file
├── arxiv_articles.db # SQLite database
├── articles/ # Downloaded PDF files
└── notes/ # Article notes (markdown files)
You can customize the user data directory location in several ways:
- Environment Variable:
export ARTUI_DATA_DIR="/path/to/custom/directory"
artui- Command Line Parameter:
artui --user-dir "/path/to/custom/directory"View user directory information:
artui userdir infoMigrate existing data from current directory:
artui userdir migrateCreate or edit config.yaml in your user data directory to configure categories and filters:
# Feed retention period in days - articles older than this are hidden from feed views unless unread
feed_retention_days: 30
categories:
# Display Name: arXiv category code
"Machine Learning": "cs.LG"
"Artificial Intelligence": "cs.AI"
"HEP Theory": "hep-th"
"HEP Experiments": "hep-ex"
"Quantum Physics": "quant-ph"
filters:
# Custom filters with advanced criteria
"ALICE Experiment":
categories:
- hep-ex
- hep-ph
query: "ALICE"
"Deep Learning":
categories:
- cs.LG
- cs.CV
query: "deep learning OR neural network"
"COVID Research":
query: "COVID-19 OR coronavirus OR SARS-CoV-2"artuiThe application will:
- Create the database file if it doesn't exist
- Start the TUI interface
- Automatically refresh articles (same as pressing 'r') - fetching recent articles (last 7 days)
- Load the first configured category/filter automatically
| Key | Action |
|---|---|
s |
Save/Unsave the selected article |
u |
Mark article as unread |
o |
Download and open PDF |
i |
Show BibTeX citation from Inspire-HEP |
t |
Manage tags for the selected article |
n |
Create/edit notes for the selected article |
f |
Focus search box |
g |
Enable web search and focus search box |
c |
Show category/filter selection popup |
r |
Refresh and fetch new articles |
q |
Quit application |
Ctrl+d |
Toggle dark/light mode |
↑/↓ |
Navigate article list |
Enter |
Select article (shows abstract) |
Mouse |
Click to navigate and select |
In the article list, the first column shows status:
●- New/unread articles- Article is saved/bookmarkedt- Article has tagsn- Article has note
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright 2025 Florian Jonas
For issues and feature requests, please use the GitHub issue tracker.
This project depends on the following Python packages: