Proposal: Separate Repositories

[rbren]

The Problem

This repository has grown like a weed. We have many different things mingled in here:

• Prompts and microagents
• Logic for running agents
• A web server
• A frontend
• Logic for bash runtime environments
• A CLI package
• Evaluation logic

This creates all sorts of headaches:

• It makes the repo very unapproachable for new users
• CI/CD takes forEVER (and is often flaky w/ runtime and frontend tests)
• We have weird interdependencies that shouldn't exist
• Package/image sizes are massive.

The Solution

I'd like to propose that we break things up into the following repositories:

• OpenHands/Agent-SDK
  • contains LLM, Agent, AgentController
  • contains security analyzer, condenser, planner, and other agent behaviors
  • contains base classes for Tools, Actions, Observations
  • contains support for loading in MCP servers as tools (i.e., MCP clients)
  • contains tools as a separate python package
    • contains all the tools (and corresponding Actions and Observations) we use everywhere
      • e.g. execute_bash, read_file, write_file, etc
    • contains current ACI
    • contains python classes for Actions and Observations we use
    • run locally only
• OpenHands/Benchmarks
  • contains scripts etc for running evals
• OpenHands/OpenHands
  • CLI package
    • contains CLI code
    • also headless
  • Server package
    • contains backend for the GUI
    • contains GitHub/GitLab/Bitbucket
    • contains Jira/Linear
    • runs LocalRuntime by default
    • uses OpenHands/Runtimes library to optionally manage other runtimes
    • contains a Dockerfile that contains:
      • OpenHands Server
      • extra runtime dependencies (replaces our current runtime-nikolaik)
    • contains a Helm Chart
  • Frontend package
    • contains React application
    • contains UI library

Future State

These are stretch goals.

• OpenHands/Runtimes
  • Replaces current runtime-api—no more microservice
  • Python library for managing runtimes
  • Implementations for:
    • Docker container mgmt
    • K8s container mgmt
    • Modal/Runloop/etc
• OpenHands/Microagents
  • directory of microagent markdown files

Additional context

If you find this feature request or enhancement useful, make sure to add a 👍 to the issue

[pcuci]

Uh oh, this will be painful... good luck!

I would suggest narrowing down on a multi polyglot repos workflow first so OpenHands can still gather all the context it needs for cross-repos feature development

ref: https://openhands-ai.slack.com/archives/C06QT0AGY4W/p1755618202866349?thread_ts=1755542580.404049&cid=C06QT0AGY4W

[enyst]

Yes! I wanted to make things more modular since forever. We didn’t succeed splitting only one thing in the past, but that’s also why it’s totally worth rethinking it from basics and splitting all/most of it.

Hey, OH repo had ~5 million tokens last I checked. 😅

I’ll follow up on the details.

[enyst]

Multiple repos used to require careful prompting, and some trial-and-error; but idk if it is a pain anymore: with OpenHands-GPT-5, I’m slowly getting used to not worrying about it, because it can do it! Had twice now, a complex feature to explore, follow, investigate in a repo, then implement it in 2 others, in a way that makes sense: the agent didn’t stumble. So far, anyway.

Are there simpler things to fix in one repo, but I told the agent to pick up another repo, make a PR there, then come back? I didn’t prompt much more than this, and it did.

Nevertheless, we may want to think about this and find some way to insert some info about multiple repos in agent’s permanent history (so in the initial ‘workspace context’):

• https://github.com/All-Hands-AI/OpenHands/issues/7752

[pcuci]

Another thing I tried was mounting the parent directory of 5 repos into OpenHands; it worked, but polluted the root with .vscode files...

It did need extra guidance to understand it's tackling multiple repos, however.

[enyst]

Some notes and/or questions

1. I added OpenHands/VSCode, the extension

Currently it’s like an auxiliary of the CLI, so it could be there too; on the other hand, I still think we could go the other way around and make it a “full” integration; and even ignoring that, people have looked for the code outside OH repo, that is, expecting it to be outside, like the Chrome extension. 🤔

2. OpenHands/Server

backend for the GUI

What does the backend include here, I expect it should/would be based on the SDK, in other words, have a dependency to the SDK?

3. OpenHands/Agent-SDK

contains tools as a separate python package run locally only

Does that mean they don’t run on a Runtime? Current status is they are defined on Runtime base class, and the SDK initializes a Runtime; so while we could make CLIRuntime the default, they’d be compatible with any Runtime. 🤔 What is the relevance of Tools being a separate python package, why separate?

4. OpenHands/CLI I kind of like the CLI/headless being separate from Agent-SDK. I’ve been thinking about this at some point… But it’s a bit unusual, isn’t it? In the python world, dropping to a CLI from/for a package feels pretty normal. I wonder if it’s useful when developing/working with the Agent-SDK so it’s expected. Though I guess we could make up a combined package here.

5. OpenHands/Server (this repository)

• backend for the GUI
• runs LocalRuntime by default
• a Dockerfile that contains:
  • OpenHands Server
  • extra runtime dependencies (replaces our current runtime-nikolaik)
• contains a Helm Chart

🤔

How about, move stuff to the OpenHands/Cloud repo, and keep this repo (probably can’t Agent-SDK), then CLI or FE?

Or Runtimes.

Or Evaluation! 😅

[rbren]

OK new proposal is up! Thanks for the feedback all

Major change is that we're hoping to put all the end-user-facing stuff (namely CLI, Server, and Frontend) into a single repo. I don't love this from a development perspective, but it will help us keep momentum (stars, contributors, discussion, etc) around this repository.

[mamoodi]

I think we still need to move the benchmarks one

[enyst]

I think we still need to move the benchmarks one

I think we have a benchmarks repo?

[mamoodi]

I think we still need to move the benchmarks one

I think we have a benchmarks repo?

true. But things aren't moved over yet. I guess we can close this after V1 is released.