OpenHands/AGENTS.md

Repository Notes

General

• This repository is the OpenHands Agent Canvas React/TypeScript frontend.
• Primary verification commands are npm run lint, npm test, npm run build, and npm run build:lib.
• Direct dependencies and dev dependencies are exact-pinned. Use the committed package-lock.json with npm ci, and update package.json and package-lock.json together through npm.
• Public skills come from @openhands/extensions; project-specific contributor guidance lives under .agents/skills/.
• Default working-directory behavior must reuse DEFAULT_WORKING_DIR from src/api/agent-server-config.ts rather than hardcoding /workspace/project.
• All pull requests must comply with .agents/skills/custom-codereview-guide.md, in addition to the general contribution requirements and CI checks.

Repository Ownership

Before adding code, confirm that the change belongs in this repository.

Repository	Owns	Add code there when…
OpenHands/OpenHands	Agent Canvas UI, frontend state, backend selection, frontend service integration, and local-stack orchestration.	Changing UI, frontend state, or how Canvas consumes an existing API.
OpenHands/software-agent-sdk	Python SDK, Agent Server, agents/tools, conversations, events, canonical REST/WebSocket API, and clients/typescript/.	Adding or changing backend behavior, endpoints, wire contracts, or typed client access.
OpenHands/extensions	Reusable public skills, automations, plugins, and integrations.	Adding or editing reusable extension content rather than Canvas behavior.
OpenHands/automation	Automation definitions, scheduling, webhooks, run history, and dispatch.	Changing when automations run or their scheduling/webhook lifecycle.

The normal dependency direction is Agent Server contract → TypeScript client → Agent Canvas. Do not reimplement Agent Server endpoints or contracts in Canvas.

Shared Frontend Change Checklist

Before changing a shared adapter, conversation builder, setting, state selector, or presentation helper:

• Raise compatibility.minimumAgentServer in config/defaults.json when Canvas begins requiring a new Agent Server endpoint, field, schema, or behavior.
• Enumerate affected consumers across Local and Cloud backends, OpenHands and ACP agents, standard/planning/delegated conversations, and standalone and embedded Canvas. Test every path with distinct control or data flow without testing an irrelevant Cartesian product.
• Give durable frontend state one named owner and one obvious writer. Handle existing-state hydration or migration and all supported create, update, delete, default, and active-item transitions. Leave destructive transitions in a deterministic valid state or an explicit empty state handled by the UI.

PR Description Human Check

The HUMAN: section in PR descriptions is reserved for human contributors only. AI agents must not add to, edit, move, or remove it. If validation fails because it is missing or empty, stop and ask the human user to update it in their own words. If a human already updated it, report the exact validator error rather than editing it.

Functionality-Specific Skills

Detailed contributor knowledge is split into skills so it loads only for relevant work. Invoke every applicable skill before changing that area; cross-cutting changes may require several skills.

Skill	Use for
telemetry-analytics	PostHog, telemetry consent/identity, typed tracking events, Cloud funnel observability, and onboarding instrumentation.
e2e-testing	Live or mock-LLM Playwright suites, Docker E2E, E2E CI/reporting, artifacts, and failure diagnosis.
frontend-api-contracts	src/api, typed Agent Server calls, Cloud/runtime transport, compatibility, backends, settings, secrets, auth, and conversation contracts.
local-stack-runtime	Dev launchers, runtime-services metadata, ingress, automation startup, process shutdown, centralized versions, and Docker.
desktop-electron	Electron startup, branding, packaging, bundled Node/uv, universal macOS builds, and desktop CI.
frontend-development	React/UI work, i18n, named identifiers, MSW mock mode, lazy loading, bundle performance, and feature-specific UI invariants.
pr-design-doc	Writing the PR design document stored in the PR body.
release	Cutting and verifying an @openhands/agent-canvas release.

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.

Testing Baseline

Create TDD tests for behavioral changes. Keep tests focused on user behavior and real code paths:

• Use Arrange, Act, Assert structure and clear test data.
• Avoid duplicate cases and duplicate assertions.
• Mock an underlying service rather than the hook that consumes it.
• Extend an existing test file when it is a natural home; create a new file only when necessary.
• Avoid brittle presentation-only assertions. Test functional CSS contracts directly when they are behavior.
• Use the minimum number of cases that fully cover the intended behavior and edge cases.

Use the e2e-testing skill for suite selection and E2E-specific requirements.

Specifications and Releases

• Spec files live under specs/. Keep spec IDs stable and mark deprecated specs with strikethrough rather than renumbering them.
• Tag implementation code and tests with // @spec BM-002 — Short title comments immediately above the relevant block so coverage remains grep-able.
• Follow .agents/skills/release.md for release automation. Never hand-edit a release-please branch.