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:

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:

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.