# evil-read-arxiv for Claude Code, Codex, and Obsidian

> evil-read-arxiv is a Python-based paper workflow that connects Claude Code or Codex skills to arXiv, Semantic Scholar, DBLP, Obsidian notes, and an optional Next.js application. It suits researchers who want repeatable search, analysis, image extraction, and note organization, but its AI summaries and recommendations depend on external services and configured research interests.

**juliye2025/evil-read-arxiv** — Claude Code+Obsidian，邪修读论文就是快

- Repository: https://github.com/juliye2025/evil-read-arxiv
- Stars: 1,748 · Forks: 172
- Language: Python
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/juliye2025-evil-read-arxiv

## Why evil-read-arxiv covers more than paper search

evil-read-arxiv addresses the gap between finding a paper and turning it into a useful research record. It targets researchers who work with Claude Code or OpenAI Codex, use Obsidian as a knowledge base, and repeatedly search arXiv, Semantic Scholar, and conference publications. The repository presents itself as a collection of skills rather than a single command-line program, assigning a separate responsibility to each stage of the reading process.

The CLI skills cover daily recommendations, deep analysis, image extraction, note search, and conference-paper discovery. An optional web application adds visual paper browsing, AI summaries, detailed analysis, feedback-based preference adjustment, favorites, bilingual UI, and mobile layouts. This division gives researchers a persistent output rather than a temporary chat response, although setup spans several skill directories, configuration files, runtime environments, and external services.

The intended audience is fairly specific. A researcher with an established Obsidian vault can reuse the workflow for daily reading and individual analysis. Someone who only needs a paper search form may find the CLI skills and vault configuration excessive. The README also does not document a fully offline mode, so the project does not fit a workflow that prohibits external API access.

## How arXiv, Semantic Scholar, and DBLP feed recommendations

The `start-my-day` skill uses two search windows. It queries arXiv for papers from the most recent month and Semantic Scholar for papers from the past year. The README states that candidates are scored across relevance, recency, popularity, and quality. The workflow then produces a daily overview and recommendation list. The first three papers automatically receive detailed analysis and image extraction, and selected keywords are linked to existing notes.

Conference discovery follows a separate route. The `conf-papers` skill searches venues including CVPR, ICCV, ECCV, ICLR, AAAI, NeurIPS, and ICML. According to the README, DBLP supplies the conference paper list, while Semantic Scholar adds citation and abstract information. Filtering happens in two stages. Title keywords make an initial selection, then Semantic Scholar data supports a three-part score composed of relevance at 40 percent, popularity at 40 percent, and quality at 20 percent.

Automatic analysis of the first three conference recommendations applies only when a paper has an arXiv ID. A conference record without that identifier can still appear in the recommendation results, but it cannot enter that specific deep-analysis path. This distinction matters for recent papers whose conference metadata has been indexed before a corresponding arXiv entry exists.

Configuration remains important because these APIs do not know the user's research profile by default. Keywords, exclusions, categories, years, and conferences determine which records enter the ranking pipeline. The scores provide an ordering method, but the README does not define every calculation used for its quality dimension or explain how missing citation and popularity fields are handled.

## Why evil-read-arxiv selects source-specific analysis templates

The `paper-analyze` skill accepts more than arXiv links. The README says it can recognize arXiv identifiers and links, public PDF URLs, local PDFs, research project pages, technical blogs, and ordinary web pages. This makes the workflow useful when a reader discovers a technical explanation or project page before locating the formal paper.

Source handling changes according to type. A research project page is inspected for explicit Paper or PDF links. A direct PDF retains its original source while the workflow attempts to fill in project-page metadata. Papers and PDFs use a research-analysis template, while blogs and general web pages use a source-analysis template. The README explicitly states that the workflow does not fabricate arXiv fields for sources that lack them. That boundary reduces the risk of representing a web article as an indexed arXiv paper.

Generated paper notes include translated abstracts, key points, background, motivation, methods and architecture, experimental results, research value, advantages, limitations, and comparisons with related papers. The skill also extracts images and updates a knowledge graph. This structure makes notes searchable and comparable later, but the README does not claim that every generated analysis is independently checked against the original publication. Researchers still need to inspect claims, equations, tables, and experimental interpretation in the source.

For webpages, “depth” means source analysis rather than paper-level methodology review. Users who expect every URL to produce the same research template may find that distinction inconvenient. It is also a sensible boundary because a blog post can discuss a method without containing the evidence, metadata, or appendices of the corresponding paper.

## How extracted figures become Obsidian knowledge records

The `extract-paper-images` skill uses a documented preference order. It first attempts to extract high-quality images from the arXiv source package. The workflow also supports public PDF links and local PDF files. When suitable source images are unavailable, it can extract images from the PDF itself.

Extracted files are placed in an `images` subdirectory under the note directory. The skill also creates an image index, which gives each note a local reference point for its figures. This arrangement fits Obsidian because the Markdown note, figure files, and existing vault directory can remain part of one research workspace.

`paper-search` operates over notes already stored in that workspace. The README lists title, author, keyword, and domain as supported search fields, with results ordered by relevance. It is therefore a search layer over the saved note collection, not an independent academic index. A paper that was discovered but never saved as a note will not become part of this local search path.

The CLI scripts read the Obsidian location through the `OBSIDIAN_VAULT_PATH` environment variable. The README recommends this method because it avoids editing paths inside individual scripts. The configuration example also includes `vault_path`, but environment-based configuration is the documented path used across the scripts. A per-call path override is mentioned in the README, although it does not give a complete command example.

The graph update is another less visible output. `paper-analyze` updates a knowledge graph after analysis, but the README does not specify the graph file format, matching rules, merge behavior, or recovery procedure. Teams with an established graph schema should inspect those implementation details before allowing automated updates.

## Installing the CLI skills and starting the web application

The CLI workflow requires Claude Code or OpenAI Codex and Python 3.8 or later. The optional web application also requires Node.js 20 or later and an Anthropic API key for its Claude features. From the repository root, install the declared Python packages first:

```bash
pip install -r requirements.txt
```

The `requirements.txt` file declares `PyYAML`, `requests`, `PyMuPDF`, `arxiv`, and `pymed`. The listed packages support YAML parsing, HTTP requests, PDF handling, arXiv access, and PubMed-related functions. After that command completes, the Python packages listed by the repository will be present in the active Python environment.

For Claude Code, install the skills by copying their directories into the personal skills folder. On macOS or Linux, the documented commands are:

```bash
cp -r evil-read-arxiv/start-my-day ~/.claude/skills/
cp -r evil-read-arxiv/paper-analyze ~/.claude/skills/
cp -r evil-read-arxiv/extract-paper-images ~/.claude/skills/
cp -r evil-read-arxiv/paper-search ~/.claude/skills/
cp -r evil-read-arxiv/conf-papers ~/.claude/skills/
```

After copying the directories and completing configuration, restart the Claude Code CLI. The README also documents equivalent Windows PowerShell commands using `Copy-Item -Recurse`. Codex uses a different personal skill directory:

```bash
mkdir -p ~/.agents/skills
cp -r evil-read-arxiv/{start-my-day,paper-analyze,extract-paper-images,paper-search,conf-papers} ~/.agents/skills/
```

In Codex, start a new task and select a skill with `$`, or name `$paper-analyze` explicitly in the prompt. The README says to restart Codex if the copied skills do not appear immediately.

## Configuring the vault, web application, and first paper view

The simplest CLI configuration is an environment variable that points to the Obsidian vault. On macOS or Linux, the README shows this shell assignment:

```bash
export OBSIDIAN_VAULT_PATH="/Users/yourname/Documents/Obsidian Vault"
```

The repository also supplies a YAML template. Copy it and replace the sample interests with the research domains, keywords, and arXiv categories used by your work:

```bash
cp config.example.yaml config.yaml
```

A minimal edited structure follows the template's `research_domains` and `arxiv_categories` fields. The paths and categories below are illustrative values, not default installation paths:

```yaml
research_domains:
  "your research domain":
    keywords:
      - "keyword1"
      - "keyword2"
    arxiv_categories:
      - "cs.AI"
      - "cs.LG"
```

For the web application, install its Node.js dependencies from the `web` directory. After that, return to the repository root and create the local YAML configuration.

```bash
cd web
npm install
cd ..
cp config.example.yaml config.yaml
```

The web application's Claude features can use settings from `data/api_settings.json`, `web/.env.local`, or source defaults, in that order. The settings page at `/settings` can also populate the application. The README shows this JSON structure for the settings file:

```json
{
  "model": "claude-sonnet-4-6",
  "api_key": "sk-ant-your-key",
  "base_url": "https://api.anthropic.com"
}
```

Start the development server from the `web` directory:

```bash
cd web
npm run dev
```

Open `http://localhost:3000`. The README says the application redirects to the paper page, which is the first practical check that the local web process has started. Do not commit a populated API settings file, and verify whether your vault already ignores local configuration before using real credentials.

## Recommendation limits and external-service failure points

The ranking system depends on accurate user configuration. `config.yaml` defines research domains, keywords, and arXiv categories, while `conf-papers.yaml` has its own keywords, exclusions, default years, and conference settings. A narrow configuration can omit relevant work before ranking begins. A broad configuration can admit records that match common terminology but not the intended research problem.

The web application adds preference learning after ten ratings. Users can mark papers as liked, neutral, or not interesting. According to the README, the AI then analyzes those responses and adjusts recommendation weights. This belongs to the web application. The README does not state that the daily CLI recommendations learn from the same ratings, so the two recommendation behaviors should not be treated as identical.

External services form a larger failure boundary. Discovery depends on arXiv, Semantic Scholar, and DBLP. PDF or source acquisition depends on the target URL remaining accessible. Web summaries and deep analysis depend on a configured Claude-compatible provider. The README does not document retry behavior, rate-limit handling, cache duration, or offline fallback for failed requests.

AI-generated analysis is another boundary. The workflow is designed to translate abstracts, explain methods, and assess results, but the README does not claim citation-grade verification of every generated statement. It is therefore the wrong tool for an automated evidence pipeline where every sentence must be traceable to an exact passage or table without review.

## How evil-read-arxiv compares with a conventional paper reader

A conventional paper reader usually centers on opening a PDF, highlighting text, and taking notes manually. evil-read-arxiv instead defines several automatable stages: source discovery, candidate scoring, detailed analysis, image extraction, Markdown note creation, graph updates, and later search across the vault. The important difference is the workflow structure, not access to a proprietary paper collection.

The CLI skills favor a text-first workspace. They depend on the host agent, write through configurable paths, and use Obsidian as the durable research layer. The optional Next.js application favors visual browsing, with AI summaries, a favorites interface, feedback controls, bilingual labels, and responsive layouts. Both approaches can use external paper services, but neither is documented as a fully local reading archive.

Compared with a plain semantic search interface, evil-read-arxiv offers more output management but also introduces more setup and more moving parts. It is a better fit for researchers who already accept Markdown notes and agent-driven automation. It is a worse fit for readers who only want a fast PDF viewer, require fully deterministic extraction, or cannot send source material and prompts to external services.

Before adoption, a small test should check one saved paper rather than the entire recommendation pipeline. Verify note placement, image storage, keyword links, graph updates, and source attribution. If those outputs are coherent in the user's own vault, the broader workflow is worth configuring; otherwise, a conventional reader will require less setup.

## Maintenance signals, upgrade work, and licensing uncertainty

The repository is not archived, and its last push was on 2026-09-15. This indicates recent repository activity, but it does not guarantee compatibility for every external API change. The repository has no GitHub releases. Its README contains a dated change log instead, listing v1.0 on 2026-03-01, v1.1 on 2026-03-13, v2.0 on 2026-04-24, and v2.1 on 2026-07-16.

Those entries show a shift from CLI skills to an added Next.js 16 web application. The current top-level layout contains separate directories for `start-my-day`, `paper-analyze`, `extract-paper-images`, `paper-search`, and `conf-papers`, plus `web/`, `tests/`, configuration templates, and Python dependency files. Upgrading therefore means reviewing both Python scripts and the separate Node.js application rather than updating one installed package.

External API compatibility is an unavoidable upgrade concern. Changes to arXiv, Semantic Scholar, DBLP, or the configured Claude endpoint could affect searches, metadata, summaries, or analysis even when the local repository remains unchanged. The README does not publish a formal support window or an upgrade policy for these services.

The repository has no identified license in the stated project metadata. Users should resolve the repository's current license before copying, redistributing, modifying, or incorporating the code into a product. The absence of a stated license is a concrete boundary for adoption and distribution.

## Conclusion

Researchers already using Claude Code or Codex and maintaining an Obsidian vault should adopt evil-read-arxiv if its configurable search and note structure match their routine. It is a poor fit for a strictly offline system because paper discovery calls external APIs and the web application requires Claude-compatible AI access. Before adoption, verify `config.yaml`, `OBSIDIAN_VAULT_PATH`, the intended note destination, and the external service requirements. The repository is not archived and its last push was on 2026-09-15, while its license remains unspecified.

## FAQ

### Does evil-read-arxiv work with both Claude Code and OpenAI Codex?

Yes. The README documents installation for Claude Code under `~/.claude/skills/` and Codex under `$HOME/.agents/skills`, with separate copy commands for each environment.

### Does the evil-read-arxiv web application require an API key?

Its AI features require an Anthropic API key. Configuration can be supplied through `data/api_settings.json`, `web/.env.local`, source defaults, or the `/settings` page.

### Can evil-read-arxiv analyze sources other than arXiv papers?

Yes. `paper-analyze` recognizes public PDF URLs, local PDFs, research project pages, technical blogs, and ordinary web pages, while selecting a source-appropriate analysis template.

### Where does evil-read-arxiv store papers and extracted images?

CLI scripts read the Obsidian vault location from `OBSIDIAN_VAULT_PATH`. Extracted figures go into an `images` subdirectory under the note directory, and the image-extraction skill creates an image index.

## Sources

- [Issues](https://github.com/juliye2025/evil-read-arxiv/issues)
- [juliye2025/evil-read-arxiv on GitHub](https://github.com/juliye2025/evil-read-arxiv)
- [README](https://github.com/juliye2025/evil-read-arxiv/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/juliye2025-evil-read-arxiv