co-researcher
PhD-level co-researcher suite for systematic reviews, critical analysis, and academic writing.
Open source Open in the app JSON README (API)
About
PhD-level co-researcher suite for systematic reviews, critical analysis, and academic writing.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- poemswe
- Origin
- gemini
- Category
- ferramentas
- Version
- 2.6.1
- Stars
- 128
- Forks
- 13
- Open pull requests
- 4
- Last push
- 2026-09-08T15:14:22Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
poemswe/co-researcher
README
# 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
[](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.