# OpenCollab (RISE-X-Lab/OpenCollab)
> OpenCollab is a multi-agent coding framework where several AI agents collaborate on coding tasks, with programmable roles and a controllable runtime. It is aimed at research, with built-in statistics and experiment instrumentation.
- GitHub: https://github.com/RISE-X-Lab/OpenCollab
- GitHub.Locker page: https://github.locker/RISE-X-Lab/OpenCollab
- Stars: 1.1K
- Language: Python
- License: MulanPSL-2.0
- Last push: 2026-11-07
## Questions and answers
Written by GitHub.Locker from the README and the repository; check the README below for details.
**Is it a framework, a library, or an app?**
It is a framework: you describe agent teams in YAML files and handoff logic in Python workflow modules, then run them from the terminal or the Python API.
**How do I get it running?**
Create configs/.env with an OpenAI-compatible or Anthropic endpoint and key, then run the opencollab command. It starts the built-in Self-Collaboration team, where an Analyst delegates work to independent Coder and Tester workspaces.
**Which model provider and keys do I need?**
You need an API key for any OpenAI-compatible or Anthropic endpoint. The key goes in configs/.env and must never be committed to git.
**Is it ready for production use?**
Not yet: version 0.9.3 is labeled a v1.0.0 PreRelease. The authors plan to release 1.0.0 only after their paper is accepted, so treat it as a pre-release.
**Does it actually enforce the team layout I declare?**
Yes. A message along an undeclared edge is refused and logged, each agent's token budget is checked before every model call, and --trace writes one JSONL record per step.
**How does it compare to Claude Code or Codex CLI?**
The authors report that their harness core, under 50,000 lines, outperforms Claude Code, Codex CLI and OpenHands on several coding benchmarks, while those projects' cores span over 100,000 lines. These are the authors' own claims.
**Has it been validated outside the lab?**
It won first place at the OAIC Agentic Software Factory Hackathon, which had a $24,000 prize pool. An example built on it reports a 98.3% resolve rate (113/115) on IO2CodeBench.
**Can I define my own agent roles?**
Yes. Write a team YAML file declaring each role's prompt, model, tools and token allowance, or write a Python workflow module that issues the handoffs yourself.
---
## README (checked against GitHub 2026-11-08)
Source: https://github.com/RISE-X-Lab/OpenCollab/blob/main/README.md
A multi-agent coding framework with programmable collaboration and a controllable runtime.
English ยท Chinese
OpenCollab follows a **rigorous and restrained software engineering philosophy**. In [version 0.9.3](https://github.com/RISE-X-Lab/OpenCollab/releases/tag/v0.9.3), its harness core in the [OpenCollab/opencollab directory](https://github.com/RISE-X-Lab/OpenCollab/tree/v0.9.3/opencollab), written in **under 50,000 lines**, provides comprehensive research instrumentation and statistics while **outperforming Claude Code, Codex CLI and OpenHands** across several [coding benchmarks](https://github.com/RISE-X-Lab/OpenCollab/blob/main/docs/results.md). The core implementations of these mature competitors have codebases spanning **well over 100,000 lines**. OpenCollab also **won first place** at the [OAIC Agentic Software Factory Hackathon](https://create.gosim.org/factory26/), which featured a **$24,000 prize pool**.
Full results
## News
- โญ **2026-11-07** โ OpenCollab reached **1,000 stars on GitHub**.
- ๐ **2026-10-11** โ **[Won first place](https://create.gosim.org/factory26/)** at the OAIC Agentic Software Factory Hackathon using OpenCollab! ๐
- ๐ **2026-10-08** โ [OpenCollab 0.9.3 (v1.0.0 PreRelease)](https://github.com/RISE-X-Lab/OpenCollab/releases/tag/v0.9.3)
includes the latest Duo V8 workflow and all the statistical features described
in our paper to support research experiments. Following extensive testing and
bug fixes, the framework now offers the complete feature set planned for 1.0.0.
We will release version 1.0.0 once our paper is accepted. See the
[changelog](CHANGELOG.md#093---2026-10-08).
- **2026-09-29** โ Our paper is on arXiv: [*OpenCollab: A Multi-Agent Coding Framework with
Programmable Collaboration and Controllable Runtime*](https://arxiv.org/abs/2609.38345).
- **2026-09-27** โ [OpenCollab 0.8](https://github.com/RISE-X-Lab/OpenCollab/releases/tag/v0.8.0)
ships [Duo](docs/duo.md) built in and makes [Single2](docs/single2.md) the
default Base agent.
- ๐ OpenCollab has been selected for support by the **Seed Program of the
Youth Open Source Special Fund**.
## Quick start
```bash
uv sync --locked
cp configs/.env.example configs/.env # then set OPENCOLLAB_API_KEY
uv run opencollab --workspace .
```
`configs/.env` accepts any OpenAI-compatible or Anthropic endpoint. Never commit
real API keys. The command starts the built-in Self-Collaboration team: the
Analyst delegates to independent Coder and Tester workspaces and adopts the
Coder's changes before testing. See [cooperative teams](opencollab/README.md#cooperative-teams)
for adoption, conflicts, and recovery. Custom teams choose their own tools.
Type `/help` in the terminal for navigation, saving and exit controls.
To define additional roles, create and select an explicit team file as shown below.
To run Duo on a Git repository, use this command.
```bash
uv run opencollab workflow run duo --workspace /path/to/repository \
--task 'Fix the public issue described here.' \
--args '{"allow_unisolated_shell":true}'
```
Place run options such as `--workspace`, `--model` and `--budget` after
`workflow run NAME`. To list workflows in another workspace, use
`workflow list --workspace PATH`. Options placed before the `workflow`
subcommand are interpreted as belonging to the root interactive mode and
will produce a usage error.
## Program the collaboration
- **Team.** A YAML file declares each role's prompt, model, tools, and token
allowance, the context policy, and who may message whom. Start from the
built-in team and edit it:
```bash
uv run opencollab team init team.yaml # edit roles, prompts, tools, and topology
uv run opencollab team show --team-config team.yaml
uv run opencollab --team-config team.yaml --workspace .
```
- **Workflow.** A Python module issues every handoff. Duo is one;
[write your own](opencollab/README.md#workflow-authoring) and run it with
`opencollab workflow run NAME`.
## Examples
**[First place at the OAIC Hackathon](examples/arcbench-evolution-r6/).**
OpenCollab powered the **first-place solution** at the
[OAIC Agentic Software Factory Hackathon](https://create.gosim.org/factory26/),
which offered a **$24,000 prize pool**. Explore the winning approach in the
ARC-Bench r6 example and build on it for your own applications.
**[From 24,000 lines to a 239-line example](examples/mini-edict/).**
[Edict](https://github.com/cft0808/edict) is a multi-agent project of roughly
**24,000 lines**. Mini Edict's original implementation recreates its core
collaboration protocol in **239 lines** of team and workflow code, showing how
OpenCollab makes sophisticated multi-agent designs compact and easy to extend.
**[98.3% on a NeurIPS 2026 benchmark](examples/io2code_oc/).** IO2CodeBench was
introduced in [FromIO](https://arxiv.org/abs/2605.15334), accepted at NeurIPS 2026.
Built on OpenCollab, this example reports a resolve rate of **98.3% (113/115)**,
up from its **78.3% (90/115)** fixed-example baseline with the same `gpt-6-luna`
model, a **20-percentage-point gain** across the benchmark's 115 non-multimodal
tasks.
[See the results](examples/io2code_oc/#results).
## Verify it happened
In a Team, the agents decide the handoffs, and a declared team does not
guarantee that they happen. In our runs, the lead agent often briefed its
teammates and then did the work itself. OpenCollab enforces the declaration and
records what each agent did:
- a message along an undeclared edge is refused, and the refusal is recorded;
- each agent's token budget is checked before every model call;
- `--trace` writes one JSONL record per step, stamped with the run, agent, role,
event type, and token usage.
From these records we measure **Adherence**, the share of runs in which the
declared organization actually happened. Changing one setting of the same team
raised it from 47.2% to as much as 97.2%.
See [how Adherence is measured](docs/adherence.md).
## Learn more
| Guide | What it covers |
| --- | --- |
| [Package guide](opencollab/README.md) | CLI, Python API, architecture, and runtime behavior |
| [Configuration guide](configs/README.md) | Providers, models, and team files |
| [Duo guide](docs/duo.md) | Running the dual-coder workflow from the CLI and SDK |
| [Weave guide](docs/weave.md) | Ordered sessions, executable checks, bounded repair and continuation |
| [Benchmark results](docs/results.md) | Tokens, cost, the paired DuoโBase test, and how to run an evaluation |
| [Adherence](docs/adherence.md) | What the runtime records, and how we measure Adherence |
| [OpenCollab-Eval README](https://github.com/RISE-X-Lab/OpenCollab-Eval#readme) | Running agents on software-engineering benchmarks |
| [Documentation index](docs/README.md) | Skills, migration guides, and design records |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development checks, [testing](CONTRIBUTING.md#checks-must-pass-before-a-pr), and [releases](RELEASING.md) |
## Citation
If you find OpenCollab useful, please give it a โญ and cite our work. Our paper is
[*OpenCollab: A Multi-Agent Coding Framework with Programmable Collaboration and
Controllable Runtime*](https://arxiv.org/abs/2609.38345). OpenCollab builds on
[Self-Collaboration](https://arxiv.org/abs/2304.07590):
```bibtex
@misc{hsu2026opencollab,
author = {Hsu, Chun-Wah and Gong, Kai and Wu, Yu and Chen, Xianhe and
Liu, Mengyang and Li, Jie and Li, Hanyu and Liu, Zhixuan and
Tang, Naisheng and Chi, Jiaying and Fan, Ziheng and He, Xuning and
Yang, Xiaokang and Jiang, Xue and Dong, Yihong},
title = {OpenCollab: A Multi-Agent Coding Framework with Programmable Collaboration and Controllable Runtime},
year = {2026},
eprint = {2609.38345},
archivePrefix = {arXiv},
url = {https://arxiv.org/abs/2609.38345}
}
@article{dong2023self,
author = {Dong, Yihong and Jiang, Xue and Jin, Zhi and Li, Ge},
title = {Self-Collaboration Code Generation via ChatGPT},
journal = {ACM Transactions on Software Engineering and Methodology},
volume = {33},
number = {7},
pages = {189:1--189:38},
year = {2024}
}
```
## License
OpenCollab is licensed under the [Mulan Permissive Software License v2](https://github.com/RISE-X-Lab/OpenCollab/blob/main/LICENSE)
(`MulanPSL-2.0`).
## Star History
