diff --git a/README.md b/README.md
index a09f1e3..6d12cfa 100644
--- a/README.md
+++ b/README.md
@@ -70,3 +70,43 @@ If you encounter API errors:
 - Uses GPT-5 (gpt-5-2025-08-07)
 - Gemini 2.5 Pro falls back to Gemini Pro if not available
 - Discussion time varies based on API response times (typically 5-10 minutes)
+
+## Using OpenHands Agents to Fix Issues
+
+This repository includes GitHub Actions that let OpenHands agents automatically work on issues and pull requests.
+
+Supported agents:
+- @openhands-claude
+- @openhands-gemini
+- @openhands-gpt
+
+Workflow definitions can be found in .github/workflows:
+- .github/workflows/openhands-claude.yml
+- .github/workflows/openhands-gemini.yml
+- .github/workflows/openhands-gpt.yml
+
+How to trigger an agent:
+- Comment on an issue or pull request, for example:
+  - @openhands-gpt — fix this issue
+  - @openhands-claude — please implement the change described above
+  - @openhands-gemini — investigate the failing tests
+- Alternatively, adding an appropriate label to an issue or PR can also trigger the workflows (see workflow files for details).
+
+Required repository secrets:
+- PAT_TOKEN: A GitHub personal access token with repo permissions (for creating branches, commits, and PRs)
+- PAT_USERNAME: The GitHub username associated with PAT_TOKEN
+- For @openhands-claude: LLM_API_KEY (Anthropic API key)
+- For @openhands-gpt: OPENAI_API_KEY (and optional OPENAI_BASE_URL if using a proxy)
+- For @openhands-gemini: GOOGLE_API_KEY
+
+Optional repository variables (Repository Settings -> Variables):
+- OPENHANDS_MACRO: Override the mention trigger (default is the agent handle above)
+- OPENHANDS_MAX_ITER: Maximum number of tool iterations (default 50)
+- OPENHANDS_BASE_CONTAINER_IMAGE: Custom base container image for the agent runtime
+- TARGET_BRANCH: Branch the agent should target (default main)
+- TARGET_RUNNER: Self-hosted runner label if not using GitHub-hosted runners
+
+Notes:
+- The agents run via the reusable workflow All-Hands-AI/OpenHands/.github/workflows/openhands-resolver.yml and will push a branch and open a PR with proposed changes.
+- See each workflow file for exact model selections and configuration.
+