ArxivJS VSCode ExtensionA VS Code extension for browsing papers organized in an arxivjs data folder. If you turn on write support in the settings, you can also edit the data folder.
With the default settings, the extension does not modify any file in the data folder. If you turn on The data folder (arxivjsdata) follows the format of the arxivjs app. Write support works without the arxivjs app. Highlights are still edited in that app. To pick up changes made in the arxivjs app, press this extension's Reload button.
Table of Contents
User GuideRequirements
InstallationUse one of the following three options. Option 1. Install from the Marketplace
From the command line, install it with Option 2. Install from a
|
| Button location | Reload scope |
|---|---|
TOPICS title bar ⟳ |
Everything (topic list and papers of expanded topics) |
Home ⟳ |
Everything |
⟳ next to a topic node |
That topic's paper list |
Topic panel ⟳ |
That topic's paper list |
Paper panel ⟳ |
That paper's metadata and document |
- Topic and paper management (write support)
- Requires
arxivjs.enableWriteto be on. When it is off, all of the menus and buttons below disappear and the extension only reads the data folder. - Write support works without the arxivjs app. Only arXiv lookups use the internet (
export.arxiv.org). - Add topic: Click the
+button in the TOPICS title bar or+ Add Topicon Home, then enter a name. Names may contain English letters, digits, Hangul (Korean), spaces, parentheses, and hyphens. The folder name is created by replacing spaces with_(Reinforcement Learning→Reinforcement_Learning). The resulting folder name is shown below the input box. - Rename topic: Choose it from the topic node's context menu. Only the folder name changes; file names inside stay the same. Paper tabs from that topic are closed.
- Delete topic: Choose it from the topic node's context menu. The folder is deleted only if it is completely empty. Even if no papers are shown, if files such as
.txtor.bakremain, it is not deleted and the remaining files are reported. - You cannot create a topic whose name differs from an existing one only in case, or that has the same display name.
- Add paper: Click the topic node's context menu or
+ Add Paperin the Topic panel, then choose a method.Search arXiv: Enter a query to see up to 50 papers containing all the words, sorted by relevance. You can select several papers and add them at once. Papers already in this topic are markedAlready added.arXiv URL/ID: Enter a value such as2310.16485orhttps://arxiv.org/abs/2310.16485.Manual Entry: Fill in a form with title, authors, year, URL, abstract, citation count, and source. If the title contains no English letters or digits, you must also enter a file name (a-z, 0-9,_).- The file name is derived from the title (
Attention Is All You Need→attention_is_all_you_need.json). If a paper with the same name already exists, you are asked whether to overwrite it. The default is to skip.
- Edit metadata: From the paper node's context menu or
Edit Metadatain the Paper panel. Only changed fields are saved, and fields unknown to this extension are kept. Changing the title does not rename the file. - Move paper to another topic: From the paper node's context menu.
.json,.md,.hlt, and.txtare moved together. If the target topic has a paper with the same file name, you are told first, and one side is kept following the same rules as the arxivjs app. - Delete paper: From the paper node's context menu. Deletes
.json,.md,.hlt, and.txt. This cannot be undone. - Delete summary: From the paper node's context menu or
Delete Summaryin the Paper panel. Deletes.mdand.hlt. Unlike the arxivjs app, no.bakbackup is kept. If the data folder is a git repository, the.mdcan be restored with git. - Papers without metadata (
.json), i.e. papers with only a summary document, cannot be edited, moved, or deleted. - ⚠️ When the arxivjs app is using the same folder, do not edit the same topic or paper in both at the same time. There is no locking, so the last write wins.
- Requires
- AI summaries (write support)
- Setup
- The data folder must contain
userprompt.txt. This is the same file the arxivjs app uses. Put{context}where the paper text should go (only the first occurrence is replaced). To edit it in VS Code, runArxivJS: Open Summary Prompt (userprompt.txt)or click the Open userprompt.txt link in thearxivjs.llm.enginesetting. If the file does not exist, you are asked whether to create it with the default prompt (a Markdown summary in Korean). - Choose an engine (
arxivjs.llm.engine).- Gemini: Enter your key with the
ArxivJS: Set Gemini API Keycommand. The key is stored in the OS credential store (SecretStorage), not insettings.json. The model isarxivjs.gemini.model(defaultgemini-2.5-flash). - Claude: Enter your key with the
ArxivJS: Set Claude API Keycommand. The key is stored in SecretStorage, like the Gemini key. The model isarxivjs.claude.model(defaultclaude-opus-5-5;claude-sonnet-5-5costs less). If your API key is not scoped to a workspace, setarxivjs.claude.workspaceId. If the model declines a request, the API retries it on a fallback model. A response that is cut off at the output limit or declined is not saved. - Ollama: Set
arxivjs.ollama.url(defaulthttp://localhost:11434) andarxivjs.ollama.model(e.g.gemma4:31b). If Ollama's default context length is short, the latter part of long papers is cut off before summarization, so increasenum_ctxin your Modelfile or Ollama settings.
- Gemini: Enter your key with the
- The data folder must contain
- Generate summary: From the paper node's context menu or
Generate Summaryin the Paper panel (Regenerate Summaryif a summary already exists).- For the full text,
<paper>.txtis used if it exists. Otherwise the PDF is downloaded, its text is extracted, and saved as.txt. For arXiv papers the abs URL is converted to the pdf URL; forsource: pdfthe URL is used as is. Manually added papers (manual) require a.txtfile. - The progress notification shows the number of characters received. Clicking
Cancelleaves the summary document unchanged. - The
.mdis saved only after the response completes. An existing summary is replaced without a backup (you are asked to confirm before regenerating).
- For the full text,
- Summarize all papers without summaries: From the topic node's context menu. Papers without an
.mdare summarized one at a time. After each PDF download it waits 3 seconds (arXiv request interval). Failed papers are skipped and the results are reported at the end. Failure reasons are in theArxivJSoutput channel.
- Setup
Settings
| Setting | Default | Description |
|---|---|---|
arxivjs.dataFolder |
"" |
Absolute path to the data folder |
arxivjs.language |
en |
Display language of messages, the tree, and panels: en (English), ko (Korean), auto (follows the VS Code display language). Reload the window to apply a change. |
arxivjs.paperSort |
citation |
Paper sort order: citation (citation count), year (year), title (title) |
arxivjs.openInNewTab |
true |
If true, opens a new tab for each paper. If false, reuses a single paper tab. |
arxivjs.paperPanelLocation |
sameGroup |
Editor group in which to open papers. sameGroup uses the same group as the paper list, so the screen is not split. beside uses the group next to the list. |
arxivjs.openHomeOnStartup |
true |
Opens the topic list (Home) when the ArxivJS view is first opened. |
arxivjs.enableWrite |
false |
Enables writing to the data folder. When off, the extension only reads. |
arxivjs.llm.engine |
gemini |
AI summary engine: gemini, ollama, claude |
arxivjs.gemini.model |
gemini-2.5-flash |
Gemini model. Set the API key with the ArxivJS: Set Gemini API Key command (SecretStorage). |
arxivjs.ollama.url |
http://localhost:11434 |
Ollama server URL |
arxivjs.ollama.model |
"" |
Ollama model (e.g. gemma4:31b) |
arxivjs.claude.model |
claude-opus-5-5 |
Claude model. Set the API key with the ArxivJS: Set Claude API Key command (SecretStorage). |
arxivjs.claude.workspaceId |
"" |
Optional workspace ID, sent as the anthropic-workspace-id header. Needed only for keys not scoped to a workspace. |
The UI is in English by default. To see messages, the tree, and panels in Korean, set arxivjs.language to ko and reload the window. Command titles and setting descriptions are always shown in English.
Commands
Search for ArxivJS in the Command Palette (Ctrl+Shift+P).
| Command | Description |
|---|---|
ArxivJS: Select Data Folder |
Sets the data folder. |
ArxivJS: Reload |
Reloads all data. |
ArxivJS: Open Settings |
Opens this extension's settings. |
ArxivJS: Open Topic |
Searches for a topic and opens it in the Topic panel. |
ArxivJS: Open Paper |
Selects a topic, then searches for a paper and opens it. |
ArxivJS: Open Original URL |
Opens the selected paper's URL in a browser. |
ArxivJS: Copy Paper Info |
Copies the title, authors, year, and URL to the clipboard. |
ArxivJS: Add Topic |
Creates a new topic folder. (write support) |
ArxivJS: Rename Topic |
Renames a topic folder. (write support) |
ArxivJS: Delete Topic |
Deletes an empty topic folder. (write support) |
ArxivJS: Add Paper |
Adds papers via arXiv search, arXiv URL/ID, or manual entry. (write support) |
ArxivJS: Edit Metadata |
Edits a paper's metadata (.json). (write support) |
ArxivJS: Move Paper to Another Topic |
Moves paper files to another topic. (write support) |
ArxivJS: Delete Paper |
Deletes paper files. (write support) |
ArxivJS: Delete Summary |
Deletes the summary document (.md) and highlights. (write support) |
ArxivJS: Generate Summary |
Creates a paper summary (.md) with Gemini, Claude, or Ollama. (write support) |
ArxivJS: Summarize All Papers Without Summaries |
Summarizes papers without summaries in a topic, one by one. (write support) |
ArxivJS: Set Gemini API Key |
Stores the Gemini API key in SecretStorage. |
ArxivJS: Delete Gemini API Key |
Deletes the stored Gemini API key. |
ArxivJS: Set Claude API Key |
Stores the Claude API key in SecretStorage. |
ArxivJS: Delete Claude API Key |
Deletes the stored Claude API key. |
ArxivJS: Open Summary Prompt (userprompt.txt) |
Opens userprompt.txt in the editor. Offers to create it with the default prompt if missing. (write support) |
Write-support commands appear only when arxivjs.enableWrite is on.
Data Folder Format
The data folder follows the format produced by the arxivjs app. With write support off, this extension only reads. The only exception is when you save yourself in an editor opened with Open Local Document. With write support on, the extension changes files following the writer rules of the arxivjs format specification.
<data folder>/
├── Few-Shot_Learning/ # topic folder
│ ├── a_closer_look_at_few_shot_classification.json # metadata
│ ├── a_closer_look_at_few_shot_classification.md # summary document
│ └── ...
└── ...
- Topic folder names may contain only English letters, digits, Hangul (Korean), spaces, underscores (
_), parentheses ((,)), and hyphens (-). For display,_is replaced with a space and consecutive spaces are collapsed into one (딥러닝_(Deep_Learning)→딥러닝 (Deep Learning)). Folders that do not follow this rule (e.g..git,a.b) are not listed. - Each paper consists of a pair of
.jsonand.mdfiles with the same name. - Other files such as
.txt,.hlt, and.bakare ignored.
Example .json metadata:
{
"title": "A Closer Look at Few-shot Classification",
"authors": "Wei-Yu Chen, Yen-Cheng Liu, Zsolt Kira, Yu-Chiang Frank Wang, Jia-Bin Huang",
"year": 2019,
"url": "http://arxiv.org/abs/1904.04232v2",
"abstract": "Few-shot classification aims to ...",
"citation": 2737,
"source": "arxiv"
}
| Field | Required | Description |
|---|---|---|
title |
✔ | Paper title |
authors |
✔ | Authors, as a comma-separated string |
year |
✔ | Publication year |
url |
✔ | Original URL |
abstract |
Abstract | |
citation |
Citation count. If missing, the paper goes last when sorting. | |
source |
Source: arxiv, pdf, manual |
Write Support and Data Protection
Write support (arxivjs.enableWrite) is off by default. Before turning it on, note the following.
- Files the extension changes: topic folders, papers'
.json,.md, and.txt, plus.hltand.bakwhen moving or deleting. It follows the writer rules of the arxivjs format specification. Files are written to a temporary file (.<name>.tmp) and then swapped in, so other apps never see a partially written file. - Concurrent editing: The data folder has no locking. If the arxivjs app or another VS Code window edits the same paper at the same time, the last write wins. Do not edit the same paper in two places at once.
- Irreversible operations: Deleting a paper, deleting a summary, and regenerating a summary keep no backup, so they go through a confirmation dialog. If you manage the data folder as a git repository,
.jsonand.mdcan be restored with git. Note that the default.gitignoredoes not track.txt,.hlt, or.bak. - AI summaries and privacy: Summarizing sends the full paper text and
userprompt.txtto the selected engine. With Gemini, they are sent to Google's servers; with Claude, to Anthropic's servers. Summarize documents that must not leave your machine with a local Ollama. The Gemini and Claude API keys are stored only in the OS credential store (SecretStorage) and never written to logs or settings files. - Differences from the arxivjs app
- No
.bakbackup is created when regenerating or deleting a summary. The arxivjs app moves.mdto.bakwhen deleting a summary. - Entries with only an
.mdand no.jsonare listed, but cannot be edited, moved, or deleted. - Editing highlights (
.hlt), looking up citation counts, chatting with papers, and uploading PDFs are still done in the arxivjs app.
- No
Troubleshooting
| Symptom | Solution |
|---|---|
| TOPICS is empty | Check that the arxivjs.dataFolder path is correct. Also check that topic folder names follow the naming rules. |
| Newly added papers do not appear | Press the Reload ⟳ button. This extension does not detect changes automatically. |
| A paper shows "No document" | That paper has no .md file yet. Only metadata and the abstract are shown. |
| Some math appears as raw source | The LaTeX syntax is not supported by KaTeX. Only that formula is shown as raw source. |
| Write menus and buttons do not appear | Turn on arxivjs.enableWrite. |
| Summarization fails with a "userprompt.txt" error | Click Open userprompt.txt in the error notification. Create the file if asked, and put {context} where the paper text should go. |
| Summarization fails with a PDF error | Check the paper's URL and source. Scanned image PDFs have no text and cannot be summarized. Manually added papers (manual) require a .txt file: click Open <paper>.txt in the error notification (an empty file is created if missing) and paste the full text. |
| Adding or searching papers fails with HTTP 429 or 503 | arXiv is limiting requests (429) or is temporarily unavailable (503). Wait as long as the notification says (a few minutes if it gives no time) and try once more. Retrying right away can extend the limit. |
| Ollama summaries cover only the beginning | Ollama's context length (num_ctx) is too short. Increase it in your Modelfile or Ollama settings. |
| Other errors | Check the logs in the ArxivJS output channel under View → Output. |
Developer Guide
Development Environment Setup
Required tools:
Clone the repository and install dependencies with the following commands.
git clone https://github.com/doosik71/arxivjs-extension.git
cd arxivjs-extension
npm install
Main npm scripts:
| Script | Description |
|---|---|
npm run build |
Bundles dist/extension.js and the PDF extraction worker dist/pdfWorker.js with esbuild. |
npm run watch |
Rebundles when sources change. |
npm run typecheck |
Runs TypeScript type checking only (no output files). |
npm run lint |
Runs ESLint, including the rules that forbid write APIs. |
npm test |
Runs unit tests (vitest). |
npm run check |
Runs typecheck → lint → test in order. |
npm run test:integration |
Runs VS Code integration tests with read-only verification. |
npm run bench |
Measures performance and checks the targets (DEV-PLAN §5.4). |
npm run icon |
Regenerates the Marketplace icon media/icon.png. |
npm run package |
Builds a .vsix file. |
Running and Debugging Locally
- Open the project folder in VS Code.
- Press
F5or chooseRun Extensionin Run and Debug. A new Extension Development Host window opens with the extension loaded. - In the new window, set a test data folder with
ArxivJS: Select Data Folder. The default istest/fixtures/sample-data. - After changing code, press
Ctrl+R(Developer: Reload Window) in the Extension Development Host window to apply the changes.
To debug webviews, run Developer: Open Webview Developer Tools in the Extension Development Host window.
Testing
npm run lint
npm test
npm run test:integration
Test data is in
test/fixtures/sample-data/. The edge cases it covers are listed intest/fixtures/README.md.The integration tests (
scripts/run-integration.mjs) verify that no file was changed in the following order.- Record the path, size, mtime, and SHA-256 of every fixture file.
- Make the fixtures read-only at the OS level. Writing to an existing file then fails with
EPERM. - Run the tests.
- Restore write permission.
- Compare against the record and fail if any file was created, removed, or changed.
Write-support tests copy the fixtures to an OS temporary folder and write to that copy.
test/unit/tempData.tsmakes the copy for unit tests, andtest/integration/tempData.tsfor integration tests. ESLint allows file writes in test code only in these two files.- The integration test
writeFlow.test.tsreplaces the input box, QuickPick, and confirmation dialog functions with functions that return predefined answers, replaces the globalfetchwith fake arXiv, PDF, and Ollama responses, and then runs the actual commands. No network is used.
Integration tests run on the latest stable VS Code by default. To check against the minimum supported version, run:
VSCODE_TEST_VERSION=1.90.0 npm run test:integration
Performance Benchmarks
npm run bench # fixtures
npm run bench -- <data folder> # real data (read-only)
The following targets are checked; if any is exceeded, the script exits with code 1.
| Item | Target |
|---|---|
| Topic list | ≤ 100 ms |
| First load of the largest topic | ≤ 500 ms |
| Rendering the largest md | ≤ 200 ms |
It also renders every md document once and reports the time distribution (p50, p95, max) and the number of rendering exceptions.
Packaging (Building a .vsix)
npm run package
# internally: vsce package --no-dependencies
--no-dependencies: The extension is bundled with esbuild, sonode_modulesis not included.- vsce rewrites relative links in the README to absolute links based on the
repository(GitHub) URL. Files not included in the package (such asDEV-PLAN.md) are mentioned by name only, without links.
This command creates arxivjs-viewer-<version>.vsix in the project root. Installing this file with Option 2 lets you distribute it within a team without the Marketplace.
Publishing-related fields in package.json:
| Field | Value | Notes |
|---|---|---|
name |
arxivjs-viewer |
Lowercase, no spaces |
displayName |
ArxivJS VSCode Extension |
Name shown in the Marketplace |
publisher |
doosik71 |
Publisher ID. The extension ID is doosik71.arxivjs-viewer |
version |
0.3.3 |
SemVer |
engines.vscode |
^1.90.0 |
|
icon |
media/icon.png |
128×128 PNG (npm run icon) |
repository |
https://github.com/doosik71/arxivjs-extension.git |
|
license |
MIT |
LICENSE file in the root |
Files that do not need to be in the distribution package (src/, test/, node_modules/, etc.) are listed in .vscodeignore.
Publishing to the Marketplace
This is the procedure for publishing to the Visual Studio Marketplace for the first time. Steps 1–3 are needed only once.
Step 1. Create an Azure DevOps Organization and a Personal Access Token (PAT)
- Sign in to https://dev.azure.com with a Microsoft account. Create an organization if you do not have one.
- Click User settings → Personal access tokens → New Token at the top right.
- Configure it as follows.
- Organization:
All accessible organizations - Scopes:
Custom defined→ Show all scopes → check Marketplace → Manage - Expiration: any period you like
- Organization:
- Copy the token somewhere safe. You cannot see it again after closing this window.
Step 2. Verify the Publisher
The publisher of this extension is doosik71. It already exists and is set in publisher in package.json.
To publish under a different publisher:
- Sign in to https://marketplace.visualstudio.com/manage with the same account.
- Click Create publisher and enter an ID and a name. The ID cannot be changed later.
- Put that ID in
publisherinpackage.json.
Step 3. Log In with vsce
npx @vscode/vsce login doosik71
# Paste the PAT from Step 1 at the prompt.
Step 4. Publish
npx @vscode/vsce publish
- If you already have a
.vsix, you can upload that file withnpx @vscode/vsce publish --packagePath arxivjs-viewer-0.3.3.vsix. - You can also upload on the web. At https://marketplace.visualstudio.com/manage, choose the publisher and upload the
.vsixvia New extension → Visual Studio Code. - After publishing, the extension goes through validation and appears in Marketplace search within a few minutes. The extension ID is
doosik71.arxivjs-viewer.
Azure DevOps PAT policies may change. If the method above is blocked, check the official documentation, Publishing Extensions. That document also describes
vsce publish --azure-credential, which uses Microsoft Entra ID authentication.
Updating the Version and Republishing
npx @vscode/vsce publish patch # 0.3.3 → 0.3.4
npx @vscode/vsce publish minor # 0.3.3 → 0.4.0
npx @vscode/vsce publish 1.0.0 # set the version explicitly
publish patch|minor|major bumps the version in package.json, creates a git tag, and then publishes. Update CHANGELOG.md before publishing.
To remove the extension from the Marketplace, run npx @vscode/vsce unpublish doosik71.arxivjs-viewer. This cannot be undone.
Publishing to Open VSX (Optional)
To distribute to users of VS Code–compatible editors such as VSCodium and Cursor, publish to Open VSX.
- Sign in to https://open-vsx.org with a GitHub account and accept the Eclipse Foundation Publisher Agreement.
- Create an Access Token in your user settings.
- Run the following commands.
npx ovsx create-namespace doosik71 -p <token> # first time only
npx ovsx publish arxivjs-viewer-0.3.3.vsix -p <token>
Development Notes
- Do not write to a real data folder.
- Point to your real data folder only for browsing. Do not turn on
arxivjs.enableWritein a window that uses that folder. - When checking write support by hand, use a copy of the fixtures or of real data.
- Tests, scripts, and auto-fix tools such as
markdownlint --fixmust never target that path. - Always test with the data under
test/fixtures/. Write tests copy it to an OS temporary folder first (test/unit/tempData.ts).
- Point to your real data folder only for browsing. Do not turn on
- Read the data folder only through
src/data/readonlyFs.ts, and write only throughsrc/data/dataWriter.ts. ESLint reports an error iffsis used elsewhere or a write API is called.dataWriter.tsre-checksarxivjs.enableWriteon every call and rejects paths outside the data folder. - Store caches and user state in
context.globalStateorcontext.globalStorageUri. Create nothing in the data folder other than the files defined in the format specification. - Follow
DEV-PLAN.mdin the repository for design details.