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.

Install

Option A — Install from VSIX (all editors)

1. Download the latest researcherz-1.0.2.vsix from the releases page
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.2.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/r-researcher.git
cd r-researcher
npm install
npm run package   # produces researcherz-1.0.2.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 LLM inference, or API keys for cloud providers

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

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, but they can be retired upstream or require a linked account. 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)

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/r-researcher.git
cd r-researcher
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..."

License

MIT — see LICENSE

Contributing

See CONTRIBUTING.md

Authors

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