research-council
yongyong030/research-council
Multi-agent research deliberation for Claude Code — domain-neutral council engine + pluggable domain packs (reproducible runs, self-contained arXiv+RAG, cost-guarded)
Instalação
npx convez-ai yongyong030/research-council1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Research Council
A multi-agent research deliberation system for Claude Code. Point it at a paper, an idea, or a research question and a council of expert subagents reviews it, stress-tests it, grounds claims in real computation, judges novelty against your own accumulated literature, and ends with an honest proceed / revise / hold recommendation — with every run recorded for reproducibility.
It is built in two layers so it works for any field:
core/— the domain-neutral council engine: chair, skeptic, logic-auditor, external-reviewer, advisor, idea-generator, literature & document & numerical roles, plus the data plumbing (paper intake, RAG accumulation, provenance, vector-DB infra).domains/<field>/— a domain pack: the subject-matter experts and grounding tools for one field.domains/physics/is the reference implementation (condensed-matter / orbitronics). Write your own pack for chemistry, biology, ML, economics… (seedomains/_template/).
Why two layers: the hard, reusable engineering — reproducible runs, literature ingestion, novelty-vs-your-own-knowledge, multi-agent orchestration with cost guards — is field-independent. Only the experts and the "grounding" calculators change per field. Keep the engine; swap the pack.
What a run does
/council "<paper | arXiv id | research question | idea>"
intake → filter → selector (fixed 3 + 4 domain experts)
→ base council in parallel (independent opinions)
→ [grounding: domain tools turn claims into checked facts]
→ chair synthesis
→ [specialist call, only on a real gap]
→ external reviewer → advisor
→ human approval (never auto-promoted)
→ provenance: every run recorded under runs/<id>/
/research ["<topic>"] full autonomous cycle: discover → collect → accumulate(RAG) → council → report
/discover surface emerging topics, flagged by what's NEW to *you* (vs your indexed corpus)
Design choices that make it usable, not just a demo:
- Reproducible. Each run writes
runs/<id>/manifest.json(models, inputs, arXiv snapshot date, RAG state, agents, verdicts) + a papercatalog.jsonlinking papers↔runs. Re-runningfinddedups topics so an autonomous loop doesn't repeat itself. - Cost-guarded. Agents are model-tiered (opus for reasoning, sonnet/haiku for mechanical roles); each dispatched once; bounded tool use. A council fits one usage window.
- Honest by construction. Separate roles for novelty-checking and over-claim review; the system is built to say "this is already known / this premise is broken" rather than inflate.
- Grounded. Domain packs ship LLM-free tools (JSON stdout) so experts check facts instead of recollecting them — e.g. physics computes crystal-symmetry-allowed tensor components and fetches Materials Project structures.
Install
Requires Claude Code. From this repo:
# core only (domain-neutral)
./install.ps1 -Target "C:\path\to\my-research-project"
# core + physics reference pack
./install.ps1 -Target "C:\path\to\my-research-project" -Domains physics
This merges core/ + chosen packs into <target>/.claude/agents, .claude/commands, and scripts/. Then open Claude Code in the target project and run /council.
Setup (RAG + backends)
The literature/accumulation features are self-contained — core/scripts/backend/ bundles arXiv collection (arxiv.py) and the RAG store (rag_store.py). No external project needed. You provide a vector DB and config:
- Install deps:
pip install requests pyyaml sentence-transformers qdrant-client fastmcp defusedxml(+ physics pack:pymatgen mp-api spglib numpy scipy sympy). - Vector DB: run a Qdrant server (server mode — embedded single-locks under concurrent search+ingest). Start with
scripts/qdrant_serve.ps1. - Config: copy
rc_config.yaml.example→rc_config.yamlat your project root; setqdrant_url, embedding/reranker models, collection. - RAG MCP: register
scripts/rag_mcp_server.pyas theresearch_ragMCP server (search_papers / search_notes / search_all) so literature agents can query.
Optional env: RC_PAPERS_DIR (PDF download dir), RC_ARXIV_CATS (discovery categories), MP_API_KEY (physics pack, env only).
Pipeline: index_papers.py add <arxiv_id> → arxiv.to_markdown (.tex source) → rag_store.index_markdown (chunk+embed+Qdrant, incremental). intake.py / discover.py use the same backend.
📋 SETUP.md — a verified reference configuration (the author's actual setup) with the engineering lessons baked in: why server-mode Qdrant, model tiering and cost guards, orphaned-MCP cleanup, embedded→server migration. Point your Claude Code at it to reproduce a working environment.
Scope: arXiv-first. The bundled backend does NOT do non-arXiv PDF extraction, Zotero, or LLM equation cleanup (those were author-specific). arXiv coverage is high for physics/CS/math; add your own collector for other sources.
Writing a domain pack
Copy the shape of domains/physics/ and follow domains/_template/README.md:
- 3–6 expert subagents on distinct judgment axes (mechanism / method / feasibility / prior-art …), model-tiered.
- ≥1 grounding tool: LLM-free, JSON stdout, secrets from env.
- Install with
-Domains <yourpack>; combine packs with-Domains physics,<yourpack>.
Layout
core/
agents/ 15 domain-neutral council roles (council-*.md)
commands/ /council /research /discover
scripts/ provenance · intake · index_papers · discover · qdrant infra
domains/
physics/ reference pack: 5 experts + symmetry.py + mp_fetch.py
_template/ how to author a pack
install.ps1
Roadmap
- More domain packs (chemistry, ML, bio) as reference implementations.
- Robustness: network retry/backoff, graceful degradation for the autonomous loop.
- Claude Code plugin packaging.
- Additional collectors beyond arXiv (Semantic Scholar, DOI/PDF) as optional backends.
Notes
- Single LLM = Claude (agents use tiered
model:frontmatter). A provider-abstraction for local LLMs is future work. runs/,catalog.json, fetched data, and secrets are git-ignored — they're per-user, not part of the framework.
License
MIT (see LICENSE).