Researcherz — AI Research Workspace

An all-in-one AI research workspace for VS Code, VSCodium, Cursor, Windsurf, and any VS Code-compatible desktop editor. Search 12+ scholarly databases, organize and evaluate evidence, run 25+ AI-assisted analyses, and produce citation-grounded academic drafts with local Ollama or your preferred cloud model — without leaving your editor.

Researcherz is free and MIT-licensed. If it saves you time, you can buy us a coffee.

Install

Option A — Install from VSIX (all editors)

1. Download researcherz-1.0.3.vsix from the repository root (or the releases page once a release is published)
2. Install it from your editor:
   • VS Code / VSCodium: Command Palette → Extensions: Install from VSIX... → select the .vsix
   • Cursor: Command Palette → Extensions: Install from VSIX... → select the .vsix
   • Windsurf: Command Palette → Extensions: Install from VSIX... → select the .vsix
   • CLI (any editor): code --install-extension researcherz-1.0.3.vsix (or codium / cursor / windsurf in place of code)
3. Run Researcherz: Open Workspace from the Command Palette

Option B — Build from source

git clone https://github.com/DataConceptz/Researcherz.git
cd Researcherz
npm install
npm run package   # produces researcherz-1.0.3.vsix

Features

• Multi-source Literature Search — Query 12+ academic databases simultaneously (OpenAlex, Semantic Scholar, Crossref, PubMed, Europe PMC, arXiv, DOAJ, DBLP, CORE, ERIC, SSRN, BASE)
• AI Studio — 25+ AI tools for paper analysis: summarize, critique, compare, lit review, evidence assessment, TL;DR, questions, hypotheses, and more
• Automate Manuscript Drafting — Generate complete, publication-grade manuscripts with rigorous thematic synthesis, explicit research-gap identification, per-section word budgets, and citations in 8 styles (APA, MLA, Chicago, Harvard, IEEE, Vancouver, Nature, ACS)
• Humanize Text — State-of-the-art 6-stage adversarial pipeline that removes AI writing patterns and matches your voice
• AI Detection Scoring — Burstiness analysis, pattern detection, composite risk score (GPTZero/Originality.ai calibrated)
• Citation Management — Insert citations in APA, BibTeX, RIS formats; export library or a selection to LaTeX, BibTeX, RIS, CSL-JSON, Markdown, CSV, JSON
• Zotero Integration — Export papers to Zotero, import from Zotero collections
• Multi-Provider LLM Support — Ollama (local), OpenAI, Anthropic Claude, Google Gemini, Azure OpenAI, Groq, Nvidia NIM, or any OpenAI-compatible API, with a per-provider connection health dashboard and live sidebar status indicator
• Real DOCX & PDF Export — Native Office Open XML (.docx) and binary PDF generation via docx and pdf-lib — real headings, tables, lists, and page-numbered footers, not HTML-saved-as-.doc
• Retraction Checking — Automatic integrity flagging via Crossref retraction metadata, surfaced as a warning badge on affected results
• Automate Presets — Save and reload named Automate configurations (doc type, tone, citation style, word count, sources)
• Document Feedback — A pinned panel beside the Automate draft flags missing citations, orphan claims, and low burstiness per line; clicking an item highlights the passage it refers to
• Resilient Search — Every database call runs under a request timeout with automatic retries on rate-limit and gateway errors, and a per-source deadline, so one slow or throttled service degrades to a single failed source instead of hanging the whole search
• Privacy-First — No telemetry, no data collection. API keys stored in your editor's encrypted SecretStorage. Local Ollama mode never sends a byte off your machine.

Cross-Editor Compatibility

Researcherz targets the stable VS Code extension API (engines.vscode: ^1.85.0) and runs in every desktop editor built on that API:

The extension declares untrustedWorkspaces.supported: true and virtualWorkspaces.supported: true, so it loads in restricted and remote contexts without prompting.

Requirements

• VS Code 1.85+ or a compatible desktop editor (VSCodium, Cursor, Windsurf, Theia)
• Node.js 18.x, 20.x, or 22.x (for development only — not required to install the VSIX)
• Optional: Ollama for local or Ollama-hosted cloud inference, or an API key for any supported cloud provider. A cloud model is the faster starting point — see Which model should I use?

Quick Start

1. Install the extension (see Install above)
2. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and run Researcherz: Open Workspace
3. Search for literature using the built-in webview panel
4. (Optional) Configure an LLM provider in Settings → Extensions → Researcherz

Which model should I use? Start in the cloud

Researcherz runs happily against a model on your own machine, and it always will — that path is private, free, and works on a plane. But be clear about the trade: a local model is limited by the hardware under your desk. A laptop without a discrete GPU realistically runs a 7–8B model, and it will produce a few tokens a second. The manuscript drafting, thematic synthesis and multi-paper comparison tools are long-generation jobs, so on that hardware a full draft is a coffee break, not a keystroke.

A cloud-hosted model is dramatically faster and noticeably better at this work, because it runs on datacentre GPUs and is far larger than anything a laptop can hold. If you are trying Researcherz for the first time, start there — you can always move to a local model once you know what the tools do.

The easiest starting point is gpt-oss:120b-cloud — OpenAI's open-weight 120B reasoning model, Apache 2.0 licensed, with a 128K context window, hosted by Ollama and run through the same local Ollama command you would use for any other model. There is nothing new to configure in Researcherz: it is an Ollama model like any other, so the provider stays Ollama and the base URL stays http://localhost:11434.

ollama signin                    # free ollama.com account; opens your browser
ollama pull gpt-oss:120b-cloud   # registers the model — nothing large is downloaded

Your local Ollama then transparently forwards requests for that model to Ollama's servers. In Researcherz, open Settings → Ollama, refresh the model list, and pick gpt-oss:120b-cloud.

Two things to know: cloud models need you to stay signed in and online, and Ollama's free tier has usage limits (see Ollama's cloud docs for current terms). Cloud tags are also retired upstream as newer open models land — if the health indicator reports the model unavailable while your server is running, check the current cloud model list or fall back to a local model.

If you would rather not use Ollama's hosting at all, every other cloud provider below works the same way, and Nvidia NIM has a free credit allowance worth knowing about.

Using with Ollama (Local)

1. Install Ollama and pull a model:

   ollama pull llama3.2
   

2. Start the Ollama server. Confirm it is actually serving — the tray app running is not the same thing:

   curl http://127.0.0.1:11434/api/tags
   

3. Open Researcherz — it auto-detects Ollama at http://localhost:11434
4. Settings → Ollama lists every installed model, and can pull a new one for you without leaving the editor

Base URL: enter the server root (http://localhost:11434), not the API path. A trailing /api or /v1 is stripped automatically, since the extension appends its own.

Cloud-hosted Ollama models (tags ending in -cloud) are listed alongside local ones and are the faster option — see Which model should I use? above. They require a signed-in ollama.com account and can be retired upstream. If the health indicator reports a model as unavailable while the server is running, pick a locally downloaded model.

Using with Cloud Providers

1. Open VS Code Settings > Extensions > Researcherz
2. Set Active Provider to your chosen provider (OpenAI, Anthropic, etc.)
3. Configure your API key when prompted (stored securely in VS Code Secret Storage)

Every cloud provider ships with a working default base URL, so in most cases the key is the only thing you supply. Use the per-provider Test button in Settings to confirm the key and model before running a long job.

Nvidia NIM

NVIDIA hosts a catalogue of open models (Llama, Mistral, DeepSeek, Nemotron and others) behind an OpenAI-compatible API, and new accounts get a free credit allowance — which makes it a good way to try a large model without a subscription.

Getting the API key:

1. Go to build.nvidia.com and sign in with an NVIDIA account (free to create)
2. Open the profile menu → Settings → API Keys, or go straight to build.nvidia.com/settings/api-keys
3. Click Generate API Key. The key begins with nvapi-
4. Copy it immediately — NVIDIA shows the full key once and cannot display it again

Base URL: https://integrate.api.nvidia.com/v1

That is already the default in Researcherz, so you should not need to change it. It is the hosted endpoint shared by every model in the NVIDIA catalogue — you select which model you get through the model name, not the URL. Enter the server root exactly as above, including /v1.

If you are running NIM as a self-hosted container rather than using NVIDIA's hosted API, point the base URL at your own container instead (typically http://localhost:8000/v1) and leave the key blank if the container is unauthenticated.

Choosing a model: browse build.nvidia.com/models and use the model's exact catalogue identifier, including the publisher prefix — the names are namespaced, e.g. meta/llama3-70b-instruct. The card for each model shows the identifier in its sample code.

If you get a 403 "Authorization failed" on a key that looks correct, the account's organisation may not have public API endpoints enabled — this is an NVIDIA account permission, not a Researcherz setting, and is resolved in your NVIDIA org settings.

Commands

Keybindings

All five are scoped to an active text editor (Humanize additionally requires a selection), so they do not fire while the Researcherz webview itself has focus — use the Command Palette there. Rebind any of them via Preferences: Open Keyboard Shortcuts if they collide with your setup.

Supported LLM Providers

Token streaming is enabled for every provider, local and cloud.

All providers expose a live connection-health indicator in the sidebar and a per-provider "Test" button in Settings. The indicator refreshes immediately when you switch providers or update an API key — no restart required, and it distinguishes an unreachable server from a reachable one whose selected model is unavailable.

Architecture

src/
├── extension.ts              # Entry point: activation, commands, lifecycle
├── panels/
│   ├── researchWorkspacePanel.ts  # Webview panel (search, library, AI, automate)
│   ├── panelHelpers.ts            # Automate helpers, prompt builders
│   └── citationSanitizer.ts       # Citation validation & sanitization
├── services/
│   ├── ollama.ts              # Unified LLM query (all providers)
│   ├── providers.ts           # Provider metadata, auth, request building
│   ├── connectionManager.ts   # Real-time provider health monitoring
│   ├── streaming.ts           # SSE streaming for LLM responses
│   ├── humanizer.ts           # AI pattern detection & deterministic cleanup
│   ├── sotaHumanizer.ts       # 6-stage adversarial humanization pipeline
│   ├── storage.ts             # Persistent state (collections, papers, settings)
│   ├── search/                # Multi-source search providers (openalex, crossref, arxiv, etc.)
│   ├── exportService.ts       # Export to LaTeX, BibTeX, RIS, CSL-JSON, Markdown, CSV, JSON
│   ├── zotero.ts              # Zotero API integration
│   ├── pdfExtract.ts          # Zero-dependency PDF text extraction
│   ├── statusBar.ts           # VS Code status bar items
│   └── citation.ts            # Citation format helpers (APA, BibTeX, RIS)
├── shared/
│   ├── contracts.ts           # TypeScript interfaces & types
│   └── constants.ts           # Default values & constants
├── utils/
│   └── citation.ts            # Citation formatting utilities
├── views/
│   └── sidebarProviders.ts    # Tree view providers for sidebar
├── i18n/
│   ├── index.ts               # Internationalization
│   └── en.json                # English locale
├── data/
│   └── humanizerPatterns.json # 30 AI pattern categories
└── prompts/
    ├── index.ts               # Prompt builders
    ├── automate.json          # Automate drafting prompts
    └── ollama.json            # Ollama-specific prompts

media/
├── index.html                 # Webview HTML template (with CSP)
├── main.js                    # Webview client-side logic
├── main.css                   # Base webview styles
├── modern-ui.css              # Theme layer loaded over main.css
└── scholar.js                 # Scholar search UI

Security

• API keys: Stored in VS Code's SecretStorage, never in plain-text config files
• CSP: Content Security Policy enforced on the webview panel (default-src 'none')
• SSRF protection: PDF URL validation blocks private/internal IP ranges
• No hardcoded secrets: All credentials are user-supplied and stored securely
• Input validation: Provider configuration is validated before use

Development

Prerequisites

node --version  # 18.x, 20.x, or 22.x
npm --version

Setup

git clone https://github.com/DataConceptz/Researcherz.git
cd Researcherz
npm install

Scripts

Testing

npm run test                    # Everything: vitest + the webview suites
npm run test:webview            # Webview suites only (no vitest, no network)
npx vitest run test/providers.test.ts  # A single file
npx vitest run --coverage       # With coverage report

Live tests

test/ollamaLive.test.ts and test/searchLive.test.ts drive the real shipped modules against a real Ollama server and the real academic APIs — real generation, real token streaming, real search results. They exist because the rest of the suite tests pure functions and local re-implementations of parsers, which can agree with each other while both disagree with the code that ships.

Both skip themselves with a warning when the dependency is unreachable, so npm test stays green offline and in CI. To exercise them, start Ollama (with tinyllama:1.1b pulled) and run the suite on a networked machine.

Webview suites

media/*.js is not bundled, not typechecked, and not imported by any vitest file, so nothing else in the pipeline reads it. Two node suites cover that gap:

• webviewSyntax.node.test.mjs — compiles every webview script. A plain syntax error there is not a localized failure: the script never evaluates, so no listener attaches and the entire UI goes dead while still rendering perfectly.
• messageContract.node.test.mjs — asserts every message declared in shared/contracts.ts has a handler on both sides of the webview boundary. TypeScript cannot check across that boundary, so a message with no handler compiles, lints, and ships as a button that does nothing.

The test suite covers:

• All provider metadata, configuration, and API formatting
• Citation formatting (APA, BibTeX, RIS)
• Humanizer patterns, burstiness analysis, deterministic cleanup
• SOTA humanizer stylometric fingerprinting & composite risk scoring
• Edge cases: empty text, very short text, special characters, unicode, markdown
• Search shared utilities (dedup, sort, filter, DOI normalization)
• Export service (LaTeX, BibTeX, RIS, CSL-JSON, Markdown, CSV, JSON)
• Citation sanitization
• Streaming response parsing (all providers)
• Retraction check enrichment
• Integration tests for search pipeline
• Security validation (API key handling, input validation)
• Ollama base-URL normalization, including the /api and /v1 suffixes users paste
• Live provider and live search end-to-end paths (see above)
• Webview↔host message contract and webview script integrity

Release Process

1. Update version in package.json
2. Update CHANGELOG.md
3. Update README.md if needed
4. Run full quality pipeline:

   npm run lint:all
   npm run test
   npm run production
   

   Run this on a machine with a network connection and Ollama running, so the live suites actually execute rather than skipping.
5. Package the extension:

   npm run package
   

6. The output .vsix file can be installed via VS Code's "Extensions: Install from VSIX..."

Support This Project

Researcherz is built and maintained in our own time, and it is free and open source under the MIT licence — no paywalled features, no telemetry, no account required. Every scholarly database it queries is a public API, and every model provider it talks to is one you bring yourself.

If Researcherz saves you an afternoon of literature triage, or gets a manuscript draft over the line, the best way to say thanks is a coffee:

buymeacoffee.com/Gidlake

Support goes straight back into the work — testing against more databases, keeping provider integrations current as APIs shift, and building the features people ask for in issues.

Not in a position to give? Starring the repository, leaving a marketplace review, or filing a good bug report helps just as much.

License

MIT — see LICENSE

Contributing

See CONTRIBUTING.md

Authors

• Gideon Alake — @DataConceptz
• Oluwaseun Ola — @Olaot18
• Folahanmi Adeyemi — @Folapipi