<div align="center">

# co-scientist plugin

**Run a multi-agent scientific research engine from inside your coding agent.**

An [Agent Plugins 1.0](https://agent-plugins.org/specification) package that lets
Claude Code, Codex CLI, Cursor, VS Code, Copilot and Kiro drive the
[AI co-scientist](https://github.com/Kaimen-Inc/Co-Scientist) engine: generate
hypotheses, review them, settle them in an Elo tournament, evolve the winners,
and read the synthesis back.

[![tests](https://github.com/Ahmad-Jaradat-Space/co-scientist-plugin/actions/workflows/test.yml/badge.svg)](https://github.com/Ahmad-Jaradat-Space/co-scientist-plugin/actions/workflows/test.yml)
[![Python 3.11 to 3.13](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![Agent Plugins 1.0](https://img.shields.io/badge/Agent%20Plugins-1.0-8A2BE2)](https://agent-plugins.org/specification)

[Install](#install) ·
[What the agent gets](#what-the-agent-gets) ·
[The design rule](#the-design-rule) ·
[Works with ScientistOS](#works-with-scientistos) ·
[Contributing](CONTRIBUTING.md)

</div>

---

## The idea

The [AI co-scientist](https://github.com/Kaimen-Inc/Co-Scientist) engine is an
open re-implementation of [Gottweis et al., *Nature*, 2026](https://www.nature.com/articles/s41586-026-10644-y).
It takes a research goal and runs six specialist agents over it: Generation,
Reflection, Ranking, Evolution, Proximity and Meta-review, scheduled by a
Supervisor over a durable SQLite task queue.

That engine has a CLI. This package gives it an **agent-facing** surface, so
the thing driving it can be Claude Code or Codex rather than you typing
commands:

```
you    → "review hypothesis 3 in that Crohn's session and tell me what breaks"
agent  → reads the hypothesis, searches the literature, applies the rubric,
         records the review into the engine's database, reports the verdict
```

The review it wrote is now a row in the same table the engine's own Reflection
agent writes to. It counts toward the tournament. The meta-review will see it.

## What the agent gets

**One MCP server** with fifteen tools:

| Group | Tools |
| --- | --- |
| Lifecycle | `session_start` · `session_resume` · `session_pause` · `session_abort` · `session_list` · `session_status` |
| Reading | `hypotheses_list` · `hypothesis_get` · `overview_get` |
| Writing | `hypothesis_record` · `review_record` · `match_record` · `feedback_add` |
| Diagnostics | `estimate_cost` · `doctor` |

**Seven skills** carrying the judgement the tools cannot:

| Skill | What it does |
| --- | --- |
| `running-research-sessions` | Sharpens a vague goal into a real one, gates on the size of the run, starts and monitors it |
| `reading-research-overviews` | Reads the ranked output honestly, with five known failure modes checked |
| `reviewing-hypotheses` | Reviews against a rubric with score anchors and a verdict decision rule, then records it |
| `ranking-hypotheses` | Runs a three to five turn debate, decides on ordered criteria, records the Elo match |
| `evolving-hypotheses` | Combine, simplify, feasibility, out-of-box, each with its own reference file and failure mode |
| `benchmarking-models` | Cross-model Elo bench, and how to read a result without overclaiming |
| `grounding-claims` | Checks that citations say what they are claimed to say, per claim, with verdicts |

## The design rule

The engine keeps **all** state: Elo, the task queue, dedup, embeddings, the
token budget, termination. This package reimplements none of it.

Everything an agent produces goes back in through the same repositories the
engine's own agents write to. `match_record` reuses the engine's Elo module and
its `elo_journal` idempotency. `review_record` writes the same `Review` model
and promotes `draft` to `reviewed` exactly as Reflection does.
`hypothesis_record` derives `created_by` from whether parents were given.

The skills state the consequence in plain words: **output that is not recorded
does not exist.** An agent that describes a review in chat without calling
`review_record` has produced nothing the system can use.

This is what stops the common failure of "port the prompts to skills and call
it done". The prompts are not where the quality comes from. The tournament is,
and a tournament needs somewhere to keep score.

## Works with ScientistOS

This plugin generates and ranks candidate hypotheses. It does not decide what
you are allowed to claim from them, and the difference matters: a hypothesis
can top the tournament and still rest on a mechanism the literature
contradicts. The `reading-research-overviews` skill lists that failure mode and
several others to check by hand.

[ScientistOS](https://github.com/Ahmad-Jaradat-Space/scientistos) makes that
check structural instead of advisory. It keeps a typed evidence graph and
refuses to record a claim at a strength its lineage does not support.

```
this plugin   →  ranked hypotheses, reviews with claim / url / excerpt per source
                              ↓
ScientistOS   →  hypothesis and source nodes, evidence at its honest level,
                 an integrity gate before anything gets written up
```

The two install side by side, since both are skill and MCP packages, and an
agent with both loaded gets the whole path. Nothing here requires ScientistOS,
and ScientistOS does not depend on this.

## Install

**No API key, and nothing to decide about billing.** If you are reading this
you already have the Claude Code or Codex CLI signed in, and that is the whole
requirement: the research engine runs its agents through the same subscription
your coding agent uses.

```bash
python3.12 -m venv .venv
source .venv/bin/activate

pip install "co-scientist @ git+https://github.com/Kaimen-Inc/Co-Scientist.git"
pip install "co-scientist-plugin @ git+https://github.com/Ahmad-Jaradat-Space/co-scientist-plugin.git"

co-scientist init
```

On first connection the server looks for a working backend. Finding none, it
adopts whichever agent CLI is installed and signed in, writes that choice to
`~/.co-scientist/config.toml`, and gets on with it. An existing `provider =`
line is never touched, so a setup you configured yourself is left alone. Set
`COSCI_AUTO_BACKEND=0` to turn the whole thing off.

If `doctor` still reports no backend, sign the CLI in (`claude`, or
`codex login`) rather than reaching for a key. It will also report a local hash
embedder, which is the expected keyless state: dedup catches repeated wording
but not two hypotheses that say the same thing differently.

Everything stays on your machine: SQLite under `./data`, no account, no service
to sign up for, and no traffic beyond the model calls your CLI was already
making.

<details>
<summary>Pinning the models, or paying for an API instead</summary>

[`config/subscription.toml`](config/subscription.toml) is the same choice
written out by hand, with the model ids pinned rather than left to the alias
your CLI resolves. Point the engine at it with
`export COSCI_CONFIG=/path/to/config/subscription.toml`.

A metered API works too: set a provider and key in
`~/.co-scientist/config.toml` before first run and auto-selection stays out of
the way. `estimate_cost` then prices the run against a budget, and the skills
ask for a go-ahead on spend rather than on time. See the
[engine's backend guide](https://github.com/Kaimen-Inc/Co-Scientist#llm-backend).

</details>

### Codex CLI

```bash
codex plugins install ./co-scientist-plugin
```

### Claude Code

```bash
ln -s "$PWD/skills/"* ~/.claude/skills/
claude mcp add co-scientist -- co-scientist-mcp
```

### Anything else

Any client that reads Agent Plugins 1.0 loads the directory as it is. Any client
that reads SKILL.md and MCP config separately can take `skills/` and `mcp.json`
on their own.

## Configuration

The server reads the engine's config. Set these in the `env` block of your
`mcp.json` if you need them:

| Variable | Effect |
| --- | --- |
| `COSCI_CONFIG` | Path to an extra TOML config to overlay |
| `COSCI_ALLOW_START` | `0` refuses `session_start` and `session_resume` |
| `COSCI_START_TIMEOUT` | Seconds to wait for a spawned run to register, default 120 |
| `COSCI_AUTO_BACKEND` | `0` turns off picking a signed-in CLI when nothing is configured |

### Read-only installs

A session makes hundreds of model calls and keeps running after the
conversation ends. On a shared machine, or anywhere an agent should not be
able to start one on its own:

```bash
co-scientist-mcp --read-only
```

Reads keep working; `session_start` and `session_resume` refuse with an
explanation.

### Virtualenv paths

`mcp.json` calls `co-scientist-mcp`, which assumes the console script is on
`PATH`. If your agent does not activate the virtualenv, use an absolute path:

```json
{
  "command": "/path/to/.venv/bin/co-scientist-mcp",
  "args": []
}
```

## Development

```bash
pip install -e ".[dev]"
ruff check coscientist_plugin tests
pytest -q
co-scientist-plugin-validate
```

Every test runs offline against a throwaway database. No key, no network, no
model calls.

Three checks guard this package:

- **`co-scientist-plugin-validate`** checks spec conformance: the ten permitted
  manifest fields, transport types, skill frontmatter, name and directory
  agreement, body length, and that every relative link resolves and stays one
  level deep.
- **`tests/test_plugin.py`** checks what a validator cannot: that no skill tells
  an agent to call an MCP tool or an engine command that does not exist, and
  that the recording discipline is actually stated in the skills that write.
- **`tests/test_server.py`** covers the invariants the design rests on: zero-sum
  Elo, idempotency per round, cross-session refusal, evidence without an
  excerpt refused, and state transitions that never drag a ranked hypothesis
  backwards.

## Relationship to the engine

This repository is the plugin layer only. The engine it drives lives at
[Kaimen-Inc/Co-Scientist](https://github.com/Kaimen-Inc/Co-Scientist) and is a
separate project under the same licence. See [`NOTICE`](NOTICE).

Neither project is affiliated with Google or with the paper's authors.
Hypotheses either one produces are a starting point for a scientist, not a
finding.

## Licence

Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).