# OpenCollab: a multi-agent coding framework you program instead of prompt > OpenCollab is a research-oriented framework for running several coding agents together. Team topology is declared in YAML, handoffs are issued from Python, and the harness core carries heavy instrumentation while staying under 50,000 lines. It is an alpha release that will not become 1.0.0 until its paper is accepted. **RISE-X-Lab/OpenCollab** — A research-friendly, high-performance multi-agent collaboration coding framework. - Repository: https://github.com/RISE-X-Lab/OpenCollab - Stars: 685 · Forks: 104 - Language: Python - License: MulanPSL-2.0 - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/rise-x-lab-opencollab ## Collaboration as a program rather than a prompt The project description is short: a research-friendly, high-performance multi-agent collaboration coding framework. The hero image carries the sharper formulation, that you program how coding agents collaborate and then verify that they did. That second half is the differentiator. Most multi-agent tooling leaves the coordination implicit: one agent is told to hand off to another, and the transcript is the only record of what happened. OpenCollab treats the collaboration structure as an artifact you author, which means the same run can be inspected, replayed and compared across experiments. The paper, OpenCollab: A Multi-Agent Coding Framework with Programmable Collaboration and Controllable Runtime, is on arXiv as 2609.38345, and the project has its own page hosted under the RISE-X-Lab organisation. The scope is deliberately narrow. The package description in pyproject.toml calls it a minimal multi-agent software development framework for explicit team and workflow orchestration, and the classifiers mark it as Development Status :: 3 - Alpha. The keyword list is llm, agent, multi-agent, coding-agent and software-engineering. There is no pretence here of being a general agent platform. The audience follows from that: researchers running experiments on agent collaboration, and engineers who need the interaction between agents to be defined and inspected rather than improvised. A team that simply wants one agent to write code has no use for any of this. ## Two ways to describe a collaboration, and how they differ OpenCollab exposes the collaboration in two modes, and the difference between them is the main design decision in the project. Team mode is declarative. A YAML file declares each role's prompt, model, tools and token allowance, the context policy, and who may message whom. The topology is data: you can see the whole communication graph in one file, and the framework enforces the allowances you wrote down. Workflow mode is imperative. A Python module issues every handoff. Duo is one such workflow and ships built in, and the README points at writing your own and running it with opencollab workflow run NAME. In workflow mode the sequence of delegation is code, so the order of operations, the branching and the retries are all ordinary programming constructs rather than YAML structure. The README also shows the built-in Self-Collaboration team in action: the Analyst delegates to independent Coder and Tester workspaces and adopts the Coder's changes before testing. That detail, the adoption step, is where the interesting engineering sits, because a multi-agent system that produces two divergent edits needs a defined policy for which one survives. The documentation on cooperative teams covers adoption, conflicts and recovery. The examples directory shows how small these programs can be. The Mini Edict example reimplements the core protocol of Edict, a multi-agent system of roughly 24,000 lines, in 239 lines of team and workflow code. That is the clearest statement of the framework's thesis: the protocol is the valuable part, and it should not cost you tens of thousands of lines to express. ## Quick start with uv and any compatible endpoint The installation path assumes uv and a locked dependency set, and the three commands are short. ```bash uv sync --locked cp configs/.env.example configs/.env # then set OPENCOLLAB_API_KEY uv run opencollab --workspace . ``` The copy of the example environment file is where the credentials go, and the README states two rules plainly. configs/.env accepts any OpenAI-compatible or Anthropic endpoint, and you should never commit real API keys. That first point is worth pausing on. The framework is not tied to one model vendor, because the provider SDKs are the openai and anthropic packages and the endpoint is a URL in an environment file. A research group comparing models can point the same topology at different backends without touching the team file. The third command starts the interactive mode on the current workspace, and it starts the built-in Self-Collaboration team rather than nothing. The README notes that you can type /help in the terminal for navigation, saving and exit controls, so the interactive session has the usual affordances rather than being a bare prompt loop. One detail worth internalising: the command is run through uv, so the environment is exactly the one in uv.lock. For an experimental framework that is the right default, since a drifted dependency set would silently change the results of a run. ## Running Duo on a repository, and the option ordering rule Running a named workflow on a Git repository is a single command with a task and an argument payload. ```bash uv run opencollab workflow run duo --workspace /path/to/repository \ --task 'Fix the public issue described here.' \ --args '{"allow_unisolated_shell":true}' ``` The workflow subcommand takes options such as --workspace, --model and --budget, and they must come after the workflow name. The README is explicit about the failure mode: options placed before the workflow subcommand are interpreted as belonging to the root interactive mode and produce a usage error. That is a sharp edge for anyone used to flags-before-subcommand conventions, and the README calls it out because it bites. The --args payload is a JSON object, and the example key allow_unisolated_shell is worth noting. It implies that shell execution is isolated by default and that turning that off is an explicit, visible decision in the command line, which is a better design than a flag buried in a configuration file. To see what is available in another workspace, the command is workflow list --workspace PATH. So the discovery path is: list the workflows in a workspace, then run one of them against it. ## A small core with a large instrumentation surface The size claim in the README is specific and worth repeating carefully. In version 0.9.3 the harness core in the opencollab directory is written in under 50,000 lines, and it provides comprehensive research instrumentation and statistics. The README compares this against Claude Code, Codex CLI and OpenHands, whose core implementations span well over 100,000 lines, and states that OpenCollab outperforms them across several coding benchmarks, with the full results in docs/results.md. Those are the project's own claims, and the benchmark graphic in the README presents pass@1 numbers for six harnesses running the same model at max reasoning effort. What is verifiable from the repository is the code size, the existence of the results document and the presence of the statistics features described in the paper. The repository layout supports the research framing. Alongside the opencollab/ package are docs/, examples/, configs/, skills/, scripts/ and tests/. The tooling is disciplined for a project at this stage: a .pre-commit-config.yaml, ruff.toml, pyrightconfig.json, an .importlinter file that enforces the package boundaries, and a .secrets.baseline from a secret scanner. The dev dependencies read pytest, pytest-asyncio, ruff, import-linter and deptry, so dependency hygiene is checked rather than assumed. The runtime dependencies are modest and mostly infrastructure rather than model machinery: openai and anthropic for the two provider SDKs, typer for the command line, rich for terminal output, prompt-toolkit for the interactive prompt, filelock for coordinating concurrent access, pydantic for the configuration schema and pyyaml for the team files. Python 3.10 through 3.14 are supported, and the console entry point is opencollab.adapters.cli.main:app. The licence is MulanPSL-2.0, with LICENSE, NOTICE and THIRD_PARTY_NOTICES.md all listed as licence files, which is the pattern for a project that bundles or adapts third-party code. ## What the framework does not settle for you Several things are genuinely unresolved, and the release record is honest about them. Version 1.0.0 does not exist yet, and the README explains why: it will be released once the paper is accepted. The current tags make the staging visible, with v0.9.3 described as the v1.0.0 PreRelease, v0.9.4 as the PreRelease beta and v0.9.5 as the gamma pre-release. So the API you use today is explicitly a pre-1.0 API, and the classifier still says alpha. The option ordering rule is a second sharp edge, and it is a design choice rather than an oversight: the root interactive mode and the workflow subcommand share a command line, so arguments are disambiguated by position. That is a small thing to hit once and an annoyance to explain in a wiki page. Research instrumentation is a third. A harness built to produce statistics about agent behaviour does work that a production harness would not: event capture, per-role accounting, token allowance tracking. The framework has to keep all of that while still being described as minimal, and the tension between those two goals is visible in the fact that the code size comparison in the README is part of the pitch. The alternative is the one the README itself names. If you need one agent doing one task well, running Claude Code or Codex CLI directly gives you a mature harness with no YAML, no topology and no workflow layer. OpenCollab earns its complexity only when the collaboration itself is the object of study or the thing you need to control: the adoption policy between two divergent agents, the context policy, the token allowance per role, and the record of who messaged whom. If none of those matter to you, a single-agent CLI is the better tool, and the README's own Mini Edict example is the proof that OpenCollab's value is compressible into a few hundred lines when you know exactly what the protocol should be. ## Conclusion OpenCollab fits a research group that needs to control and measure how multiple coding agents collaborate, and that can live with an alpha API and a team file as the unit of configuration. It is the wrong choice for a team that wants a single agent with a good prompt, because the framework's value appears only when you have a topology to express, and it is the wrong choice for a project that needs a stable public contract, since version 1.0.0 is gated on paper acceptance and the package is classified as alpha. Before adopting, read docs/duo.md and opencollab/README.md for the team and workflow formats, run uv sync --locked so the locked dependency set is what you test, and check that your model endpoint is reachable through configs/.env before wiring anything into CI. ## FAQ ### How do I install and start OpenCollab? Run uv sync --locked, copy configs/.env.example to configs/.env and set OPENCOLLAB_API_KEY, then start it with uv run opencollab --workspace .. The environment file accepts any OpenAI-compatible or Anthropic endpoint, and the README says never to commit real API keys. ### What is the difference between Team mode and Workflow mode in OpenCollab? A team is a YAML file declaring each role's prompt, model, tools and token allowance, the context policy and who may message whom. A workflow is a Python module that issues every handoff, such as the built-in Duo workflow, and is run with opencollab workflow run NAME. ### When will OpenCollab reach 1.0.0? The README states that version 1.0.0 will be released once the paper is accepted. Recent tags are pre-release stages, v0.9.3 as the v1.0.0 PreRelease, v0.9.4 as beta and v0.9.5 as gamma, and the package is classified as Development Status :: 3 - Alpha. ### What licence is OpenCollab released under? MulanPSL-2.0, with LICENSE, NOTICE and THIRD_PARTY_NOTICES.md listed as licence files in pyproject.toml. The project is maintained by RISE-X-Lab and the console entry point is opencollab.adapters.cli.main:app. ## Sources - [Issues](https://github.com/RISE-X-Lab/OpenCollab/issues) - [License: MulanPSL-2.0](https://github.com/RISE-X-Lab/OpenCollab/blob/main/LICENSE) - [README](https://github.com/RISE-X-Lab/OpenCollab/blob/main/README.md) - [Releases](https://github.com/RISE-X-Lab/OpenCollab/releases) - [RISE-X-Lab/OpenCollab on GitHub](https://github.com/RISE-X-Lab/OpenCollab) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rise-x-lab-opencollab