# 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**
```bash
claude plugin install poemswe/co-researcher
claude plugin install co-researcher
```

### Gemini CLI

**Option 1: From GitHub**
```bash
gemini extension install https://github.com/poemswe/co-researcher
```

**Option 2: From Local Directory**
```bash
cd /path/to/co-researcher
gemini extension link .
```

### Codex

**Option 1: Ask Codex (Agentic)**
Tell Codex:
```text
Fetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.codex/INSTALL.md
```

**Option 2: Manual Setup**
```bash
# 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](.codex/INSTALL.md) for details.

### OpenCode

**Option 1: Ask OpenCode (Agentic)**
Tell OpenCode:
```text
Fetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.opencode/INSTALL.md
```

**Option 2: Manual Setup**
```bash
# 1. Clone this repo
# 2. Run the installer:
./.opencode/install.sh
```
See [.opencode/INSTALL.md](.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):
```bash
/research "impact of social media on teenage mental health"
```
Review and approve the execution plan before agents run.

**Auto Mode** (for trusted workflows):
```bash
/research "climate change mitigation strategies" --auto
```
Executes the plan automatically without confirmation.

**Plan-Only Mode** (for review):
```bash
/research "AI ethics frameworks" --plan-only
```
Generates execution plan but doesn't run it.

### Example Workflow

```bash
# 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:
```bash
/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:

```bash
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](https://coresearcher.poemswe.com)**

Or run locally:
```bash
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

[![Star History Chart](https://api.star-history.com/svg?repos=poemswe/co-researcher&type=Date)](https://star-history.com/#poemswe/co-researcher&Date)

## 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.