---
**English | [็ฎไฝไธญๆ](./README.zh-CN.md)**
**EvoScientist aims to harness vibe research by enabling self-evolving AI scientists that autonomously explore, generate insights, and iteratively improve.
It is designed to be opinionated and ready to use out of the box, offering a living research system that grows alongside evolving agent skills, toolsets, and memory bases.
Moving beyond traditional human-in-the-loop systems, EvoScientist adopts a human-on-the-loop paradigm, where AI acts as a research buddy that co-evolves with human researchers and internalizes scholarly taste and scientific judgment.**
๐ Awards & Recognition
Best Paper & Appraisal Award
|
AI-Generated Best Paper
|
#1 on DeepResearch Bench II
|
โก Unified Control, Different Surfaces
## โจ Features
- **๐ค Multi-Agent Team** โ 6 sub-agents (plan, research, code, debug, analyze, write) working in concert.
- **๐ง Persistent Memory** โ Context, preferences, and findings survive across sessions.
- **๐ Multi-Provider** โ Anthropic, OpenAI, Google, MiniMax, NVIDIA โ one config to switch.
- **๐ฑ Multi-Channel** โ CLI as the hub; Telegram, Slack, Feishu, WeChat, and more โ one agent session.
- **๐ฌ Scientific Workflow** โ Intake โ plan โ execute โ evaluate โ write โ verify.
- **๐ MCP & Skills** โ Plug in MCP servers or install skills from GitHub on the fly.
> [!TIP]
> Looking for ready-to-use research skills? Check out [**EvoSkills**](https://github.com/EvoScientist/EvoSkills) โ powered by [**EvoScientist**](https://github.com/EvoScientist/EvoScientist)'s engine and installable skills, the entire end-to-end research lifecycle is covered out of the box. [**EvoSkills**](https://github.com/EvoScientist/EvoSkills) are also compatible with other AI coding agents like Claude Code, Cursor, and OpenClaw.
## ๐ฅ News
- **[13 Mar 2026]** ๐ [**EvoScientist**](https://github.com/EvoScientist/EvoScientist) officially debuts!
- **[11 Mar 2026]** โณ Technical Report is live! [**Check it out**](https://arxiv.org/abs/2603.08127) ๐
- **[06 Mar 2026]** ๐ฅ Ranked #1 on [DeepResearch Bench II](https://agentresearchlab.com/benchmarks/deepresearch-bench-ii/index.html#leaderboard) at submission time! [**Leaderboard**](https://agentresearchlab.com/benchmarks/deepresearch-bench-ii/index.html#leaderboard) ๐
- **[24 Nov 2025]** ๐ 6/6 accepted at [ICAIS 2025](https://icais.ai/) AI Scientist Track โ Best Paper & AI Reviewer's Appraisal Award! [**Details**](https://airaxiv.com/papers/?q=zacharyzhang2022%40gmail.com) ๐
## ๐ Table of Contents
- [๐ฆ Installation](#-installation)
- [๐ Configuration](#-configuration)
- [โก Quick Start](#-quick-start)
- [๐ช Examples & Recipes](#-examples--recipes)
- [๐ MCP Integration](#-mcp-integration)
- [๐ฑ Channels](#-channels)
- [๐ Acknowledgments](#-acknowledgments)
- [๐ฏ Roadmap](#-แฏ-roadmap)
- [๐ Project Roles](#-project-roles)
- [๐ค Contributing](#-contributing)
- [๐ Citation](#-citation)
## ๐ฆ Installation
> [!TIP]
> Requires **Python 3.11+** (**< 3.14**). We recommend [**uv**](https://docs.astral.sh/uv/) or **conda** for dependency management and virtual environments.
๐ช Install uv (if you don't have it)
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Quick Install
```bash
uv tool install EvoScientist
```
Or install into the current environment instead:
```bash
uv pip install EvoScientist
```
### Latest from GitHub
To get the latest patches before a [PyPI](https://pypi.org/project/EvoScientist/) release:
```bash
uv pip install git+https://github.com/EvoScientist/EvoScientist.git
```
### Development Install
```bash
git clone https://github.com/EvoScientist/EvoScientist.git
cd EvoScientist
uv sync --dev
```
enable pre-commit hooks:
```bash
uv run pre-commit install
```
Using conda
```bash
conda create -n EvoSci python=3.11 -y
conda activate EvoSci
pip install -e ".[dev]"
```
Using PyPi
```bash
pip install EvoScientist # quick install
pip install -e ".[dev]" # development install
```
Optional: Channel dependencies
Messaging channel integrations require extra dependencies. Install only what you need:
```bash
uv pip install "EvoScientist[telegram]" # Telegram
uv pip install "EvoScientist[discord]" # Discord
uv pip install "EvoScientist[slack]" # Slack
uv pip install "EvoScientist[wechat]" # WeChat
uv pip install "EvoScientist[qq]" # QQ
uv pip install "EvoScientist[feishu]" # Feishu
uv pip install "EvoScientist[all-channels]" # everything
```
Upgrade to the latest code base
```bash
git pull && uv sync --dev
```
๐Back to top
## ๐ Configuration
The easiest way to configure API keys is the interactive wizard:
```bash
EvoSci onboard
```
> [!TIP]
> It walks you through provider selection, key validation, model choice, and workspace mode.
> Supports OAuth sign-in for [Claude Code](https://claude.com/product/claude-code) and [Codex CLI](https://developers.openai.com/codex/cli/) users โ no API key needed.
๐ Manual configuration via environment variables
Set at least one LLM provider key and (optionally) a search key:
```bash
# Pick one LLM provider
export ANTHROPIC_API_KEY="sk-..." # Claude โ console.anthropic.com
export OPENAI_API_KEY="sk-..." # GPT โ platform.openai.com
export GOOGLE_API_KEY="AI..." # Gemini โ aistudio.google.com/api-keys
export MINIMAX_API_KEY="sk-..." # MiniMax โ platform.minimaxi.com (Anthropic-compatible)
export NVIDIA_API_KEY="nvapi-..." # NIM โ build.nvidia.com
# Web search (optional)
export TAVILY_API_KEY="tvly-..." # app.tavily.com
```
Or use `EvoSci config set` to persist keys in `~/.config/evoscientist/config.yaml`.
Alternatively, copy the example `.env` file for project-level configuration:
```bash
cp .env.example .env # then fill in your keys
```
> โ ๏ธ Never commit `.env` files with real keys. It is already in `.gitignore`.
๐Back to top
## โก Quick Start
```bash
EvoSci # or EvoScientist โ interactive mode (TUI by default)
```
> Run `EvoSci -h` for all CLI options.
> [!TIP]
> Need to copy long outputs? Use `--ui cli` for classic mode where native terminal copy works freely. On macOS, [iTerm2](https://iterm2.com/) users can also hold `โฅ Option` while dragging to select, then `โ+C`.
Common examples
```bash
EvoSci # interactive mode (TUI by default)
EvoSci -p "your question" # single-shot mode
EvoSci --workdir /path/to/project # open in a specific directory
EvoSci -m run # isolated per-session workspace
EvoSci --ui cli # classic CLI (lightweight)
EvoSci serve # headless mode โ channels only, no interactive prompt
```
Action Approval
By default, shell commands (`execute` tool) require human approval before running. To skip approval prompts:
```bash
# Per-session: auto-approve via CLI flag
EvoSci --auto-approve
EvoSci -p "query" --auto-approve
# Persistent: set in config (applies to all future sessions)
EvoSci config set auto_approve true
# Or allow only specific command prefixes
EvoSci config set shell_allow_list "python,pip,pytest,ruff,git"
```
During a session you can also reply **3** (Approve all) at any approval prompt to auto-approve for the rest of that session.
Agent Questions
The agent can proactively ask you questions when it needs clarification (e.g., dataset choice, experiment direction). This is enabled by default. To disable:
```bash
# Persistent: set in config
EvoSci config set enable_ask_user false
# Re-enable
EvoSci config set enable_ask_user true
```
In-session commands
| Command | Description |
| ------- | ----------- |
| `/current` | Show current session info |
| `/threads` | List recent sessions |
| `/resume` | Resume a previous session |
| `/delete` | Delete a saved session |
| `/new` | Start a new session |
| `/clear` | Clear chat history |
| `/skills` | List installed skills |
| `/install-skill ` | Add a skill from path or GitHub |
| `/uninstall-skill ` | Remove an installed skill |
| `/mcp` | Manage MCP servers |
| `/channel` | Configure messaging channels |
| `/help` | Show available commands |
| `/exit` | Quit |
Script Inference
```python
from EvoScientist import EvoScientist_agent
from langchain_core.messages import HumanMessage
from EvoScientist.utils import format_messages
thread = {"configurable": {"thread_id": "1"}}
last_len = 0
for state in EvoScientist_agent.stream(
{"messages": [HumanMessage(content="Hi?")]},
config=thread,
stream_mode="values",
):
msgs = state["messages"]
if len(msgs) > last_len:
format_messages(msgs[last_len:])
last_len = len(msgs)
```
๐Back to top
## ๐ช Examples & Recipes
A curated collection of official examples, advanced usage patterns, and community-contributed recipes to help you get the most out of EvoScientist.
๐ **[Browse all examples & recipes](docs/README.md)**
๐Back to top
## ๐ MCP Integration
Add external tools via [MCP](https://modelcontextprotocol.io/) servers with a single command:
```bash
# Usage
EvoSci mcp add [-- args...]
# Example
EvoSci mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking
```
> [!TIP]
> For command options, config fields, tool routing, wildcard filtering, and troubleshooting, see the **[MCP Integration Guide](https://github.com/EvoScientist/EvoScientist/tree/main/EvoScientist/mcp#model-context-protocol-integration)**.
๐Back to top
## ๐ฑ Channels
Connect messaging platforms so they share the same agent session as the CLI:
```bash
# Usage
EvoSci channel setup
# Example
EvoSci channel setup telegram
```
Multiple channels can run concurrently โ comma-separate names in the config:
```yaml
channel_enabled: "telegram,slack,feishu,qq"
```
The channel can also be started interactively with `/channel` in the CLI session.
> [!TIP]
> For per-channel setup guides, capability matrix, architecture details, and troubleshooting, see the **[Channel Integration Guide](https://github.com/EvoScientist/EvoScientist/tree/main/EvoScientist/channels#channels)**.
๐Back to top
## ๐ Acknowledgments
This project builds upon the following outstanding open-source works:
- [**LangChain**](https://github.com/langchain-ai/langchain) โ A framework for building agents and LLM-powered applications.
- [**DeepAgents**](https://github.com/langchain-ai/deepagents) โ The batteries-included agent harness.
We thank the authors for their valuable contributions to the open-source community.
๐Back to top
## ๐ฏ แฏโค Roadmap
Coming soon:
- [x] ๐ฅ๏ธ Full-screen TUI and classic CLI interfaces
- [x] ๐ป EvoMemory v1.0 shipped
- [x] โ๏ธ 200+ predefined skills built in
- [x] ๐งฉ Built-in research-lifecycle skills shipped
- [x] ๐ Human-in-the-loop action approval
- [x] ๐ฆพ Agent-initiated human clarification
- [x] ๐ Technical report on the way
- [x] ๐ OAuth sign-in (Anthropic, OpenAI, etc.)
- [ ] ๐บ Web app with workspace UI
- [ ] ๐น Demo and tutorial in the works
- [ ] ๐ Benchmark suite to be released
- [ ] โฐ Scheduled tasks for the core system planned
Stay tuned โ more features are on the way!
๐Back to top
## ๐ Project Roles
#### Core Contributors
#### Contributors
Jan Piotrowski, Wiktor Cupiaล, Jakub Kaliski, Jakub Filipiuk, Xinhao Yi, Shuyu Guo, Andreas Sauter, Wenxiang Hu, Jacopo Urbani, Zaiqiao Meng, Jun Luo, Lun Zhou
> 
[*Xiaoyi DeepResearch*](https://xiaoyi.huawei.com/chat/research) *Team* and the wider open-source community contribute to this project.
For any inquiries or collaboration opportunities, please contact: [**EvoScientist.ai@gmail.com**](mailto:evoscientist.ai@gmail.com)
๐Back to top
## ๐ค Contributing
We welcome contributions from developers, researchers, and AI coding agents at all levels. Our [Contributing Guidelines](./CONTRIBUTING.md) are designed for both humans and AI agents โ covering architecture, patterns, extension guides, and code standards to help you contribute safely and effectively.
### ๐ฅ Community Contributors
โ๏ธ Join the EvoScientist community to discuss AI-driven research, share experiment results, and help shape the future of automated scientific discovery.
- [Discord](https://discord.gg/AZ9ZMXkunY) โ Ask questions, share findings, and collaborate with researchers and developers in real-time.
- [WeChat](https://github.com/EvoScientist/EvoScientist/blob/main/.github/assets/cn_info.md) โ Connect with our Chinese-speaking research community.
Every contribution brings us one step closer to a future where AI accelerates scientific breakthroughs for all of humanity.
### ๐ Star History
[](https://www.star-history.com/?repos=EvoScientist%2FEvoScientist&type=date&legend=bottom-right)
๐Back to top
## ๐ Citation
If you find our paper and code useful in your research and applications, please cite using this BibTeX:
```bibtex
@article{evoscientist2026,
title={EvoScientist: Towards Multi-Agent Evolving AI Scientists for End-to-End Scientific Discovery},
author={Yougang Lyu and Xi Zhang and Xinhao Yi and Yuyue Zhao and Shuyu Guo and Wenxiang Hu and Jan Piotrowski and Jakub Kaliski and Jacopo Urbani and Zaiqiao Meng and Lun Zhou and Xiaohui Yan},
journal={arXiv preprint arXiv:2603.08127},
year={2026}
}
```
๐Back to top
## ๐ License
This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
๐Back to top
