One common failure mode I have seen recently is that the agent will implement something in the wrong repository. For instance we keep getting new implementations of API access to endpoints in the OpenHands repo despite the fact that this should be in typescript client. We could consider restructuring repos but as a first step maybe we can improve our agents.md and review guidelines about things that should not be implemented in particular repose but a different repo

one option would be to put comments in the code that tell agents "this is not where to add an endpoint; if that, then go there ->" i used this strategy a lot more early on in AI dev when an agents would constantly look for arbitrary resources. the system uses nginx+caddy but agents keep looking for apache httpd configs? i would leave a fake apache config that said "GO AWAY! U NOT WELCOME! WE USE NGINX"

@bland-bear-604 add to AGENTS.md in openhands repo (odie) clear relationships between repos and responsibilities of its repo. KISS. Look at them to know to summarize pointer.

🐾 Drafted it. Added a Repository Map near the top of

OpenHands/OpenHands

AGENTS.md — a small table of what each repo owns (frontend / software-agent-sdk / typescript-client / extensions) and when a change belongs here vs a sibling, plus the common mis-placements (API-endpoint access → typescript-client, new endpoints/agent-tool logic → software-agent-sdk, skills/automations → extensions). KISS, pointer-not-duplicate. It also ties into the existing “API Access Rules” CI guard so “endpoint code in the frontend” gets caught. Committed on

docs/agents-repo-map

— want me to open the PR?

yep

🐾 PR up (draft): https://github.com/OpenHands/OpenHands/pull/16612 — the AGENTS.md Repository Map.

Okies, can you please check the edit I made to the previous section, and since we are at it, verify the previous section for correctness (some may be outdated… or not)

🐾 Checked your edit + verified the whole General section against the code. Your edit: all good. “This repository is the OpenHands frontend” + dropping “OSS” from option-service are both accurate, and trimming my “pointer-not-duplicate” line is fine. General section — verified accurate: the

src/api/*

service names (incl.

agent-server-conversation-service

/

agent-server-git-service

), all five

VITE_*

env vars,

DEFAULT_WORKING_DIR = "workspace/project"

,

SKILLS_CATALOG

+

load_public:false

(in skills-service), the device-authorization flow (

use-device-flow.ts

), and the build/verify commands all still match the code. ✅ One stale bit: the browser-tools bullet says

VITE_ENABLE_BROWSER_TOOLS=false

omits

BrowserToolSet

. The env var is still wired (

agent-server-adapter.ts

), but the thing it toggles is now the tool named

browser_tool_set

— there’s no

BrowserToolSet

symbol anymore. Want me to reword it to

browser_tool_set

?

yes sure

🐾 Done — reworded to

browser_tool_set

, pushed to the PR (

fba2ccd8e

). #16612 now covers the repo map + the one stale-wording fix.