{
  "markdown": "# Co-Researcher (v2.6.1)\n\nA 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**.\n\nSearches 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.\n\n## Installation\n\n### Claude Code\n\n**Option 1: Slash commands**\n```\n/plugin marketplace add poemswe/co-researcher\n/plugin install co-researcher\n```\n\n**Option 2: Claude CLI**\n```bash\nclaude plugin install poemswe/co-researcher\nclaude plugin install co-researcher\n```\n\n### Gemini CLI\n\n**Option 1: From GitHub**\n```bash\ngemini extension install https://github.com/poemswe/co-researcher\n```\n\n**Option 2: From Local Directory**\n```bash\ncd /path/to/co-researcher\ngemini extension link .\n```\n\n### Codex\n\n**Option 1: Ask Codex (Agentic)**\nTell Codex:\n```text\nFetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.codex/INSTALL.md\n```\n\n**Option 2: Manual Setup**\n```bash\n# 1. Clone this repo to ~/.codex/skills/co-researcher\n# 2. Add hook to ~/.codex/AGENTS.md\n# 3. Run:\n~/.codex/skills/co-researcher/.codex/co-researcher-codex bootstrap\n```\nSee [.codex/INSTALL.md](.codex/INSTALL.md) for details.\n\n### OpenCode\n\n**Option 1: Ask OpenCode (Agentic)**\nTell OpenCode:\n```text\nFetch and follow instructions from https://raw.githubusercontent.com/poemswe/co-researcher/main/.opencode/INSTALL.md\n```\n\n**Option 2: Manual Setup**\n```bash\n# 1. Clone this repo\n# 2. Run the installer:\n./.opencode/install.sh\n```\nSee [.opencode/INSTALL.md](.opencode/INSTALL.md) for details.\n\n## Native Platform Parity\n\nThe suite provides native research commands across all supported platforms:\n\n| Feature | Command (Claude) | Slash (Gemini) | Skill (Codex) |\n|---------|------------------|----------------|---------------|\n| **Research Project** | `/research` | `/research` | `$research` |\n| **Critical Analysis** | `/analyze` | `/analyze` | `$analyze` |\n| **Peer Review** | `/review` | `/review` | `$review` |\n\nEvery 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.\n\n## Research Orchestration Engine\n\nThe `/research` command features intelligent agent orchestration that automatically:\n- Analyzes your research question\n- Selects optimal agents for your specific needs\n- Creates an execution plan with clear phases\n- Coordinates multi-agent workflows\n\n### Usage Modes\n\n**Interactive Mode** (default - recommended):\n```bash\n/research \"impact of social media on teenage mental health\"\n```\nReview and approve the execution plan before agents run.\n\n**Auto Mode** (for trusted workflows):\n```bash\n/research \"climate change mitigation strategies\" --auto\n```\nExecutes the plan automatically without confirmation.\n\n**Plan-Only Mode** (for review):\n```bash\n/research \"AI ethics frameworks\" --plan-only\n```\nGenerates execution plan but doesn't run it.\n\n### Example Workflow\n\n```bash\n# 1. Start research with orchestration\n/research \"effectiveness of remote work on productivity\"\n\n# The engine will:\n# - literature-reviewer: Find recent studies on remote work outcomes\n# - critical-analyzer: Evaluate methodology and bias in key studies  \n# - quant-analyst: Interpret effect sizes and statistical significance\n# - hypothesis-explorer: Map variables (work location, productivity metrics, confounds)\n\n# 2. Review generated plan and approve execution\n# 3. Agents run in coordinated sequence\n# 4. Receive integrated findings\n```\n\n### Templates\n\nPre-configured agent combinations for common scenarios:\n```bash\n/research \"topic\" --template=quick        # Fast literature scan\n/research \"topic\" --template=rigorous     # Full systematic review\n/research \"topic\" --template=comprehensive # Deep multi-method analysis\n```\n\n## Specialized Skills\n\nThe suite includes PhD-level research skills, each governed by **Systemic Honesty** principles.\n\n- **critical-analysis**: Rigorous logic checking and fallacy detection\n- **ethics-review**: IRB compliance and privacy risk assessment\n- **grant-writing**: Funding strategy and proposal development\n- **hypothesis-testing**: Variable mapping and experimental design\n- **academic-writing**: Eliminating AI-isms from research prose\n- **literature-review**: Systematic search and citation analysis\n- **multi-source-investigation**: Cross-validation across diverse sources\n- **peer-review**: Manuscript critique and methodological review\n- **qualitative-research**: Thematic analysis and coding\n- **quantitative-analysis**: Statistical power and effect size interpretation\n- **research-manager**: Dynamic task scaffolding and polyglot session persistence\n- **research-methodology**: Design selection, validation, and creative reframing (cross-domain analogies, first-principles)\n- **research-synthesis**: Narrative synthesis with uncertainty quantification\n- **systematic-review**: PRISMA-standard systematic review guidance\n- **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.\n\n## Research Toolchain\n\nThe `literature-review` skill ships CLI backends (`skills/literature-review/scripts/`, run via `uv`) that the other evidence-handling skills share:\n\n| Script | What it does |\n|--------|--------------|\n| `openalex_cli.py` | Cross-disciplinary search over ~250M works (OpenAlex) |\n| `search_arxiv.py` | Preprint search (CS, physics, math, quant-bio) |\n| `europepmc_api.py` | Life-science full text + forward/backward citation chaining |\n| `read_paper.py` | Any DOI/arXiv ID/PMCID → markdown full text via legal open-access routes; warns on retracted papers |\n| `build_corpus.py` | Merges raw backend results into a deduplicated `corpus.json`; re-runs preserve screening decisions |\n| `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 |\n| `prisma_counts.py` | PRISMA 2020 flow counts computed from the review workspace's `corpus.json` |\n\nOne-time setup: `bash scripts/setup.sh` (installs `uv`, optionally stores an OpenAlex API key).\n\n## Evaluation Framework\n\nVerify agent performance with the v2.0 benchmark system:\n\n```bash\ncd evals\npython run_eval.py all -j 4 --model \"codex:gpt-5.2 high\"\n```\n\n### Features\n- **Parallel Runner**: Multi-threaded execution with `-j` (jobs) flag\n- **Dynamic Rubrics**: 6 specialized rubrics matched to agent skills\n- **Extended Targeting**: Support for specific versions and reasoning levels\n- **Persistent Indexing**: Rebuildable `latest/index.md` summary\n\n### Benchmark v2.0\nTwo-file architecture for scalability and transparency:\n\n**Dashboard Data** (`benchmark_overview.json` ~900B):\n- Lightweight run metadata and summary stats\n- Fast dashboard load times (10-50x improvement)\n\n**Test Details** (`test_results_detail/{run_id}.json` ~500KB):\n- Full agent outputs and judge evaluations\n- Rubric-by-rubric scoring breakdowns\n- Must-include analysis and justifications\n\n**Arena Dashboard**:\nView live interactive dashboard at **[coresearcher.poemswe.com](https://coresearcher.poemswe.com)**\n\nOr run locally:\n```bash\nopen evals/index.html\n```\n\nFeatures: Model leaderboards, capability matrices, score trends, and detailed test breakdowns with performance ratings (Excellent/Good/Fair/Poor).\n\n## Architecture\n\n- `skills/`: Specialized research skills (Markdown). Single source of truth for every platform.\n- `commands/`: Unified platform commands (.md for Claude, .toml for Gemini).\n- `.codex/`: Codex launcher (`co-researcher-codex`) and `bootstrap.md`; it reads `skills/` directly.\n- `evals/`: 22 test cases and Python runner.\n- manifests: `.claude-plugin/plugin.json`, `gemini-extension.json`, `GEMINI.md`.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=poemswe/co-researcher&type=Date)](https://star-history.com/#poemswe/co-researcher&Date)\n\n## License\nMIT\n\nThe 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.\n",
  "bytes": 8902,
  "sha": "d3fca18f12b39481bd3480bdcd8311119beb3b5a4708551e50d61b46fe234c40",
  "repo_slug": "poemswe/co-researcher",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_poemswe_co_researcher_02d279a4/readme"
}