OpenHands/.openhands/microagents/repo.md

This repository contains the code for OpenHands, an automated AI software engineer. It has a Python backend (in the openhands directory) and React frontend (in the frontend directory).

General Setup:

To set up the entire repo, including frontend and backend, run make build. You don't need to do this unless the user asks you to, or if you're trying to run the entire application.

Running OpenHands with OpenHands:

To run the full application to debug issues:

export INSTALL_DOCKER=0
export RUNTIME=local
make build && make run FRONTEND_PORT=12000 FRONTEND_HOST=0.0.0.0 BACKEND_HOST=0.0.0.0 &> /tmp/openhands-log.txt &

IMPORTANT: Before making any changes to the codebase, ALWAYS run make install-pre-commit-hooks to ensure pre-commit hooks are properly installed.

Before pushing any changes, you MUST ensure that any lint errors or simple test errors have been fixed.

• If you've made changes to the backend, you should run pre-commit run --config ./dev_config/python/.pre-commit-config.yaml (this will run on staged files).
• If you've made changes to the frontend, you should run cd frontend && npm run lint:fix && npm run build ; cd ..
• If you've made changes to the VSCode extension, you should run cd openhands/integrations/vscode && npm run lint:fix && npm run compile ; cd ../../..

The pre-commit hooks MUST pass successfully before pushing any changes to the repository. This is a mandatory requirement to maintain code quality and consistency.

If either command fails, it may have automatically fixed some issues. You should fix any issues that weren't automatically fixed, then re-run the command to ensure it passes. Common issues include:

• Mypy type errors
• Ruff formatting issues
• Trailing whitespace
• Missing newlines at end of files

Repository Structure

Backend:

• Located in the openhands directory
• Testing:
  • All tests are in tests/unit/test_*.py
  • To test new code, run poetry run pytest tests/unit/test_xxx.py where xxx is the appropriate file for the current functionality
  • Write all tests with pytest

Frontend:

• Located in the frontend directory
• Prerequisites: A recent version of NodeJS / NPM
• Setup: Run npm install in the frontend directory
• Testing:
  • Run tests: npm run test
  • To run specific tests: npm run test -- -t "TestName"
  • Our test framework is vitest
• Building:
  • Build for production: npm run build
• Environment Variables:
  • Set in frontend/.env or as environment variables
  • Available variables: VITE_BACKEND_HOST, VITE_USE_TLS, VITE_INSECURE_SKIP_VERIFY, VITE_FRONTEND_PORT
• Internationalization:
  • Generate i18n declaration file: npm run make-i18n
• Data Fetching & Cache Management:
  • We use TanStack Query (fka React Query) for data fetching and cache management
  • Data Access Layer: API client methods are located in frontend/src/api and should never be called directly from UI components - they must always be wrapped with TanStack Query
  • Custom hooks are located in frontend/src/hooks/query/ and frontend/src/hooks/mutation/
  • Query hooks should follow the pattern use[Resource] (e.g., useConversationMicroagents)
  • Mutation hooks should follow the pattern use[Action] (e.g., useDeleteConversation)
  • Architecture rule: UI components → TanStack Query hooks → Data Access Layer (frontend/src/api) → API endpoints

VSCode Extension:

• Located in the openhands/integrations/vscode directory
• Setup: Run npm install in the extension directory
• Linting:
  • Run linting with fixes: npm run lint:fix
  • Check only: npm run lint
  • Type checking: npm run typecheck
• Building:
  • Compile TypeScript: npm run compile
  • Package extension: npm run package-vsix
• Testing:
  • Run tests: npm run test
• Development Best Practices:
  • Use vscode.window.createOutputChannel() for debug logging instead of showErrorMessage() popups
  • Pre-commit process runs both frontend and backend checks when committing extension changes

Template for Github Pull Request

If you are starting a pull request (PR), please follow the template in .github/pull_request_template.md.

Implementation Details

These details may or may not be useful for your current task.

Microagents

Microagents are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They are Markdown files that can include frontmatter for configuration.

Types:

• Public Microagents: Located in microagents/, available to all users
• Repository Microagents: Located in .openhands/microagents/, specific to this repository

Loading Behavior:

• Without frontmatter: Always loaded into LLM context
• With triggers in frontmatter: Only loaded when user's message matches the specified trigger keywords

Structure:

---
triggers:
- keyword1
- keyword2
---
# Microagent Content
Your specialized knowledge and instructions here...

Frontend

Action Handling:

• Actions are defined in frontend/src/types/action-type.ts
• The HANDLED_ACTIONS array in frontend/src/state/chat-slice.ts determines which actions are displayed as collapsible UI elements
• To add a new action type to the UI:
  1. Add the action type to the HANDLED_ACTIONS array
  2. Implement the action handling in addAssistantAction function in chat-slice.ts
  3. Add a translation key in the format ACTION_MESSAGE$ACTION_NAME to the i18n files
• Actions with thought property are displayed in the UI based on their action type:
  • Regular actions (like "run", "edit") display the thought as a separate message
  • Special actions (like "think") are displayed as collapsible elements only

Adding User Settings:

• To add a new user setting to OpenHands, follow these steps:
  1. Add the setting to the frontend:
     • Add the setting to the Settings type in frontend/src/types/settings.ts
     • Add the setting to the ApiSettings type in the same file
     • Add the setting with an appropriate default value to DEFAULT_SETTINGS in frontend/src/services/settings.ts
     • Update the useSettings hook in frontend/src/hooks/query/use-settings.ts to map the API response
     • Update the useSaveSettings hook in frontend/src/hooks/mutation/use-save-settings.ts to include the setting in API requests
     • Add UI components (like toggle switches) in the appropriate settings screen (e.g., frontend/src/routes/app-settings.tsx)
     • Add i18n translations for the setting name and any tooltips in frontend/src/i18n/translation.json
     • Add the translation key to frontend/src/i18n/declaration.ts
  2. Add the setting to the backend:
     • Add the setting to the Settings model in openhands/storage/data_models/settings.py
     • Update any relevant backend code to apply the setting (e.g., in session creation)