Co-Researcher (v2.6.1)

A professional research suite for conducting rigorous academic research using specialized agents and multi-platform CLI commands. Compatible with Claude Code, Gemini CLI, OpenAI Codex, and OpenCode.

Searches run against real scholarly databases (OpenAlex, arXiv, Europe PMC), and every bibliography passes a verification gate that catches fabricated, mismatched, and retracted citations before output.

Installation

Claude Code

Option 1: Slash commands

/plugin marketplace add poemswe/co-researcher
/plugin install co-researcher

Option 2: Claude CLI

claude plugin install poemswe/co-researcher
claude plugin install co-researcher

Gemini CLI

Option 1: From GitHub

gemini extension install https://github.com/poemswe/co-researcher

Option 2: From Local Directory

cd /path/to/co-researcher
gemini extension link .

Codex

Option 1: Ask Codex (Agentic) Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.codex/INSTALL.md

Option 2: Manual Setup

# 1. Clone this repo to ~/.codex/skills/co-researcher
# 2. Add hook to ~/.codex/AGENTS.md
# 3. Run:
~/.codex/skills/co-researcher/.codex/co-researcher-codex bootstrap

See .codex/INSTALL.md for details.

OpenCode

Option 1: Ask OpenCode (Agentic) Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.opencode/INSTALL.md

Option 2: Manual Setup

# 1. Clone this repo
# 2. Run the installer:
./.opencode/install.sh

See .opencode/INSTALL.md for details.

Native Platform Parity

The suite provides native research commands across all supported platforms:

Feature	Command (Claude)	Slash (Gemini)	Skill (Codex)
Research Project	/research	/research	$research
Critical Analysis	/analyze	/analyze	$analyze
Peer Review	/review	/review	$review

Every other capability (methodology, synthesis, ethics review, grant writing, bibliography) is invoked by describing the task in natural language — the matching skill self-triggers via its description. Commands exist only for the three entry points people type habitually.

Research Orchestration Engine

The /research command features intelligent agent orchestration that automatically:

• Analyzes your research question
• Selects optimal agents for your specific needs
• Creates an execution plan with clear phases
• Coordinates multi-agent workflows

Usage Modes

Interactive Mode (default - recommended):

/research "impact of social media on teenage mental health"

Review and approve the execution plan before agents run.

Auto Mode (for trusted workflows):

/research "climate change mitigation strategies" --auto

Executes the plan automatically without confirmation.

Plan-Only Mode (for review):

/research "AI ethics frameworks" --plan-only

Generates execution plan but doesn't run it.

Example Workflow

# 1. Start research with orchestration
/research "effectiveness of remote work on productivity"

# The engine will:
# - literature-reviewer: Find recent studies on remote work outcomes
# - critical-analyzer: Evaluate methodology and bias in key studies  
# - quant-analyst: Interpret effect sizes and statistical significance
# - hypothesis-explorer: Map variables (work location, productivity metrics, confounds)

# 2. Review generated plan and approve execution
# 3. Agents run in coordinated sequence
# 4. Receive integrated findings

Templates

Pre-configured agent combinations for common scenarios:

/research "topic" --template=quick        # Fast literature scan
/research "topic" --template=rigorous     # Full systematic review
/research "topic" --template=comprehensive # Deep multi-method analysis

Specialized Skills

The suite includes PhD-level research skills, each governed by Systemic Honesty principles.

• critical-analysis: Rigorous logic checking and fallacy detection
• ethics-review: IRB compliance and privacy risk assessment
• grant-writing: Funding strategy and proposal development
• hypothesis-testing: Variable mapping and experimental design
• academic-writing: Eliminating AI-isms from research prose
• literature-review: Systematic search and citation analysis
• multi-source-investigation: Cross-validation across diverse sources
• peer-review: Manuscript critique and methodological review
• qualitative-research: Thematic analysis and coding
• quantitative-analysis: Statistical power and effect size interpretation
• research-manager: Dynamic task scaffolding and polyglot session persistence
• research-methodology: Design selection, validation, and creative reframing (cross-domain analogies, first-principles)
• research-synthesis: Narrative synthesis with uncertainty quantification
• systematic-review: PRISMA-standard systematic review guidance
• using-co-researcher: Orientation to the suite — how skills are invoked and the rules that govern them. Activation is automatic: a session-start hook injects the Systemic Honesty principles, and each skill self-triggers from its description.

Research Toolchain

The literature-review skill ships CLI backends (skills/literature-review/scripts/, run via uv) that the other evidence-handling skills share:

Script	What it does
openalex_cli.py	Cross-disciplinary search over ~250M works (OpenAlex)
search_arxiv.py	Preprint search (CS, physics, math, quant-bio)
europepmc_api.py	Life-science full text + forward/backward citation chaining
read_paper.py	Any DOI/arXiv ID/PMCID → markdown full text via legal open-access routes; warns on retracted papers
build_corpus.py	Merges raw backend results into a deduplicated corpus.json; re-runs preserve screening decisions
verify_citations.py	Bibliography gate — resolves every citation (JSON, BibTeX, or plain text) against OpenAlex, Europe PMC, and Crossref/Retraction Watch; reports verified / mismatched / not_found / retracted with a nonzero exit on any failure
prisma_counts.py	PRISMA 2020 flow counts computed from the review workspace's corpus.json

One-time setup: bash scripts/setup.sh (installs uv, optionally stores an OpenAlex API key).

Evaluation Framework

Verify agent performance with the v2.0 benchmark system:

cd evals
python run_eval.py all -j 4 --model "codex:gpt-5.2 high"

Features

• Parallel Runner: Multi-threaded execution with -j (jobs) flag
• Dynamic Rubrics: 6 specialized rubrics matched to agent skills
• Extended Targeting: Support for specific versions and reasoning levels
• Persistent Indexing: Rebuildable latest/index.md summary

Benchmark v2.0

Two-file architecture for scalability and transparency:

Dashboard Data (benchmark_overview.json ~900B):

• Lightweight run metadata and summary stats
• Fast dashboard load times (10-50x improvement)

Test Details (test_results_detail/{run_id}.json ~500KB):

• Full agent outputs and judge evaluations
• Rubric-by-rubric scoring breakdowns
• Must-include analysis and justifications

Arena Dashboard: View live interactive dashboard at coresearcher.poemswe.com

Or run locally:

open evals/index.html

Features: Model leaderboards, capability matrices, score trends, and detailed test breakdowns with performance ratings (Excellent/Good/Fair/Poor).

Architecture

• skills/: Specialized research skills (Markdown). Single source of truth for every platform.
• commands/: Unified platform commands (.md for Claude, .toml for Gemini).
• .codex/: Codex launcher (co-researcher-codex) and bootstrap.md; it reads skills/ directly.
• evals/: 22 test cases and Python runner.
• manifests: .claude-plugin/plugin.json, gemini-extension.json, GEMINI.md.

Star History

License

MIT

The project itself is MIT-licensed. One optional runtime dependency carries a stronger license: pymupdf4llm (and its PyMuPDF backend), used by skills/literature-review/scripts/read_paper.py for PDF text extraction, is AGPL-3.0. It is pulled in only when that script runs via uv, not bundled with the skills. If you redistribute a service built on read_paper.py, the AGPL terms apply to that dependency. The Europe PMC JATS and OpenAlex abstract routes do not require it.