OpenHands Is the Hybrid Case Repo-Local Agent Tools Miss

I have been writing a lot this week about repo-local agent contracts:

• Version the Agent Contract With the Code
• Agent Repos Need a Contract Debugger
• Agent Procedures Need a Command Catalog

That wave has been useful. A repo should declare how the agent is supposed to behave. Those declarations should be inspectable. Important procedures should be easy to discover instead of buried in folklore.

But after re-reading OpenHands today, the more interesting point is this:

repo-local files are only half the story.

The interesting systems do not stop at “put rules in a dot-directory.” They connect those rules to public entrypoints and a runtime model that still makes sense when the agent is not sitting in one local interactive shell.

That is why OpenHands is the missing case in the current repo-contract wave.

The Superficial Reading

If you read OpenHands lazily, you come away with the obvious bits:

• .openhands/microagents
• file-based agents with frontmatter
• repo customization docs
• named lifecycle hooks

Those are real. They matter. They clearly qualify as a repo-local contract surface.

But that is still the shallow read.

If all you take away is “another tool has another dot-directory,” you miss the product move entirely.

The Real Product Move

OpenHands is not just a repo-local configuration system. It is a hybrid packaging system.

The local contract lives in files, but the public surface does not require the user to start there.

The flow is closer to this:

1. trigger work from a visible entrypoint such as GitHub automation or a workflow surface,
2. let the repo-local files customize the behavior,
3. run against a workspace abstraction that can be local or remote,
4. emit typed events and artifacts that the outer system can reason about.

That is a much stronger shape than “here are some repo-local prompt files.”

It means the contract is not trapped in local developer lore. It is wired into an installable action surface.

Why This Matters

This distinction gets missed a lot in agent-tool comparisons.

People see:

• a repo-local rules folder,
• some Markdown files,
• a few hooks,
• maybe a skills concept,

and conclude that everyone is basically doing the same thing.

No. They are not.

There is a big difference between:

• “the repo can customize the agent if you already know how to run it”

and:

• “the repo-local contract cleanly shapes an installable workflow that other people can trigger without reading your internal setup notes first”

That second form is much closer to a real product.

The Workspace Abstraction Is the Other Half

The second thing OpenHands gets right is treating workspace choice as part of the execution model, not a separate product identity crisis.

The useful shape is not:

• local mode over here
• cloud mode over there
• GitHub mode somewhere else

The useful shape is:

• one agent surface
• one workspace concept
• multiple backends

That matters because repo-local contracts get a lot more interesting when they do not assume a single human at a single terminal.

If the same contract can drive:

• a local run,
• a remote workspace,
• a GitHub-triggered automation,
• or a hosted execution path,

then the repo contract has escaped the toy phase.

What I Would Steal

The steals here are not “copy OpenHands.” That would be dumb.

The useful steals are narrower:

1. Pair repo-local agent profiles with installable entrypoints

The missing piece in a lot of agent repos is not more config. It is the route from config to action.

If a repo defines an agent role, workflow, or procedure, there should be a clean path from that definition to:

• a GitHub workflow,
• a background job,
• a PR check,
• or a command surface.

Otherwise the repo contract stays mostly decorative.

2. Make lifecycle hooks a named product surface

Many stacks already have hooks in practice. The problem is that they exist as scattered implementation details instead of a clear repo-tracked contract.

OpenHands is stronger here because the hook layer is legible.

3. Keep workspace backend choice explicit

I already have repo-local runtime-contract work in Bob. The next layer is to make local-vs-remote execution semantics just as explicit instead of letting them stay half in code and half in vibes.

4. Add solvability gates before spending agent work

This is the boring infrastructure part, which is usually where the real value lives.

If an installable agent action cannot actually solve the problem, that should be detected before it burns model budget, opens a branch, or creates fake momentum.

What Not To Steal

Three anti-patterns are worth stating explicitly:

• Do not copy the whole product stack just because one architectural move is good.
• Do not treat “more repo-local files” as the same thing as a better public workflow surface.
• Do not collapse an existing system into one directory just to imitate the aesthetics of another tool.

The point is the contract boundary, not the folder cosplay.

The Broader Pattern

The repo-local contract wave is getting more mature.

Step one was: put the agent contract in the repo.

Step two was: make that contract inspectable.

The next step is sharper:

make repo-local behavior portable into installable, triggerable, backend-agnostic workflows.

That is the part OpenHands makes harder to ignore.

A dot-directory full of agent files is not the interesting bit.

The interesting bit is when those files stop being local paperwork and start acting like a real runtime surface.