What agents should know before contributing
All-Hands-AI/OpenHands
🙌 OpenHands: AI-Driven Development
Read by Bluet from 7 files written for agents and 300 merged pull requests on 2026-09-25. Not reviewed by the maintainers.
Rules its files tell agents (7)
- docs/ACP_AGENTS.md
mustCanvas never derives a base-URL secret from your LLM settings — but a base URL you save yourself rides along…
[!IMPORTANT] Do not set ANTHROPIC_BASE_URL alongside the Claude OAuth token. An inherited LiteLLM base URL silently breaks the token's bearer auth (it routes the request away from Anthropic). Canvas never derives a base-URL secret from your LLM settings — but a base URL you save yourself rides along on every start request like any other saved secret, which is why the credential forms warn when both are set. Only set it deliberately, and not with the OAuth path.
- AGENTS.md
mustNever hand-edit a release-please branch.
Follow .agents/skills/release.md for release automation. Never hand-edit a release-please branch.
- docs/CANVAS_EXTENSIONS_TESTING.md
shouldDo not use the normal ingress URL at http://localhost:8000 for this test because its /api traffic goes directl…
Open <http://localhost:3102/extensions>. Do not use the normal ingress URL at http://localhost:8000 for this test because its /api traffic goes directly to the unmodified Agent Server rather than through the mock browser session.
- docs/ACP_AGENTS.md
shouldgemini-cli 0.45.x re-resolves any *-flash model id at generation time to its current default flash (e.g. gemin…
[!NOTE] Pick a non-flash Gemini model. gemini-cli 0.45.x re-resolves any *-flash model id at generation time to its current default flash (e.g. gemini-2.5-flash silently ran gemini-3-flash, which 404s on projects that don't serve it — software-agent-sdk#3532). Only a non-flash id sticks, so Canvas preselects gemini-2.5-pro. If a Gemini turn fails with Publisher Model … was not found, check the selected model isn't a flash id.
- docs/ACP_AGENTS.md
shouldIf you're already signed in to the provider's CLI on the machine the agent runs on, it reuses that login a…
[!IMPORTANT] ACP agents authenticate two ways: a subscription login, or an API key — and the onboarding fields are optional. If you're already signed in to the provider's CLI on the machine the agent runs on, it reuses that login automatically, so locally you often don't need a key at all. The login takes priority over an API key: while you're signed in, a key set in the environment isn't used — so the onboarding key fields do nothing and can be left blank.
- AGENTS.md
shouldThe detailed rules live in each skill's references/guide.md; do not copy them back into this file.
The detailed rules live in each skill's references/guide.md; do not copy them back into this file. Update the owning skill whenever an invariant changes.
- AGENTS.md
shouldDo not reimplement Agent Server endpoints or contracts in Canvas.
The normal dependency direction is Agent Server contract → TypeScript client → Agent Canvas. Do not reimplement Agent Server endpoints or contracts in Canvas.
Decisions its pull requests settled (26)
- #16439re-derive active profile stamp from event history on reload
- #16441expose the LLM-switching toggle in Agent settings
- #16534draw the ring track from the foreground, not a border token
- #16619preserve URL fragments in withBackendSelectionParams
- #16685use DB-driven free/default model flags in Canvas
- #16680install a catalog entry that ships a script bundle
- #16701do not silently persist ACP model picks to agent_settings when profile discovery fails
- #16703scope Cmd+Enter build shortcut to plan mode
- #16732keep the events socket alive across refetches and bound hung handshakes
- #16758follow next_page_id so cloud picks surface past the default page size
- #16759scope baked working_dir to the default-local backend
- #16860replace the all-on skill catalog with an explicit allow-list
- #17107percent-encode branch names in provider branch URLs
- #16961parse window-open URLs instead of prefix-matching localhost
- #17116keep ProgressEvent resolvable after jsdom teardown
- #17228force an explicit decision on every ACP harness the registry adds
- #17289scope an agent profile to specific MCP servers
- #17423tie the client ACP registry pin to agent-server, drop the codex shim
- #17502Disable PostHog autocapture
- #17511call agent-server runtime directly instead of /api/cloud-proxy (405 on verification confirm & compact-context)
- #17518advertise host services to Docker conversations
- #17523clarify Agent Canvas checkpoints
- #17598let triage and repository writers own readiness
- #17617keep the base path on links that leave the app
- #17624hide cloud orgs the server marks is_visible=false
- #17639clear a "Failed to send" bubble once its message is echoed back