From dd51c55c11832a1dc2b0ae7a69f6004a924ea9a9 Mon Sep 17 00:00:00 2001 From: openhands Date: Sat, 9 May 2026 10:42:21 +0000 Subject: [PATCH 1/3] docs: recommend stop hooks for repo quality gates Co-authored-by: openhands --- openhands/usage/customization/repository.mdx | 51 ++++++++++++++------ 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/openhands/usage/customization/repository.mdx b/openhands/usage/customization/repository.mdx index b242a1aae..500273943 100644 --- a/openhands/usage/customization/repository.mdx +++ b/openhands/usage/customization/repository.mdx @@ -29,26 +29,45 @@ blocking dangerous commands, enforcing linting before the agent finishes, or log See the dedicated [Hooks](/openhands/usage/customization/hooks) page for the full guide. -## Pre-commit Script -You can add a `.openhands/pre-commit.sh` file to create a custom git pre-commit hook that runs before each commit. -This can be used to enforce code quality standards, run tests, or perform other checks before allowing commits. +## Repository-specific Stop Hooks -For example: -```bash +For repository-specific quality gates, use a [Stop hook](/openhands/usage/customization/hooks) in `.openhands/hooks.json`. +Stop hooks run when OpenHands tries to finish a task and can block completion until checks pass. They work across current +OpenHands flows that use the agent server, so they are the recommended way to enforce formatting, linting, tests, or other +repo-specific checks before an agent reports that work is complete. + +For example, create `.openhands/hooks/lint_check.sh`: + +```bash .openhands/hooks/lint_check.sh #!/bin/bash -# Run linting checks -cd frontend && npm run lint -if [ $? -ne 0 ]; then - echo "Frontend linting failed. Please fix the issues before committing." - exit 1 -fi +cd "$OPENHANDS_PROJECT_DIR" -# Run tests -cd backend && pytest tests/unit -if [ $? -ne 0 ]; then - echo "Backend tests failed. Please fix the issues before committing." - exit 1 +if ! npm run lint 2>&1; then + echo '{"decision":"deny","reason":"Linting failed. Please fix the issues before finishing."}' + exit 2 fi exit 0 ``` + +Then register it in `.openhands/hooks.json`: + +```json .openhands/hooks.json +{ + "stop": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": ".openhands/hooks/lint_check.sh", + "timeout": 120 + } + ] + } + ] +} +``` + +See the dedicated [Hooks](/openhands/usage/customization/hooks) page for the full guide, including hook event types, +blocking behavior, and JSON response format. From ca30b6c2e3854e710d0426a73f59c96e036cc226 Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 10 May 2026 11:20:03 +0000 Subject: [PATCH 2/3] docs: simplify stop hook guidance Co-authored-by: openhands --- openhands/usage/customization/hooks.mdx | 2 +- openhands/usage/customization/repository.mdx | 28 +++++++++----------- 2 files changed, 13 insertions(+), 17 deletions(-) diff --git a/openhands/usage/customization/hooks.mdx b/openhands/usage/customization/hooks.mdx index 2adc4b7fa..0c75c9bb5 100644 --- a/openhands/usage/customization/hooks.mdx +++ b/openhands/usage/customization/hooks.mdx @@ -384,6 +384,6 @@ You can configure multiple hook types and multiple hooks per event: ## See Also -- [Repository Customization](/openhands/usage/customization/repository) - Setup scripts and pre-commit hooks +- [Repository Customization](/openhands/usage/customization/repository) - Setup scripts and repository-specific hooks - [Skills](/overview/skills) - Extend agent behavior with prompt-based skills - [Hooks (SDK Guide)](/sdk/guides/hooks) - Programmatic hooks for SDK developers diff --git a/openhands/usage/customization/repository.mdx b/openhands/usage/customization/repository.mdx index 500273943..2e7f3d7ae 100644 --- a/openhands/usage/customization/repository.mdx +++ b/openhands/usage/customization/repository.mdx @@ -29,21 +29,21 @@ blocking dangerous commands, enforcing linting before the agent finishes, or log See the dedicated [Hooks](/openhands/usage/customization/hooks) page for the full guide. -## Repository-specific Stop Hooks +## Repository-Specific Stop Hooks For repository-specific quality gates, use a [Stop hook](/openhands/usage/customization/hooks) in `.openhands/hooks.json`. -Stop hooks run when OpenHands tries to finish a task and can block completion until checks pass. They work across current -OpenHands flows that use the agent server, so they are the recommended way to enforce formatting, linting, tests, or other -repo-specific checks before an agent reports that work is complete. +Stop hooks run when OpenHands tries to finish a task and can block completion until formatting, linting, tests, or other +repo-specific checks pass. They work across current agent-server-backed OpenHands flows. -For example, create `.openhands/hooks/lint_check.sh`: +For example, create `.openhands/hooks/quality_gate.sh`: -```bash .openhands/hooks/lint_check.sh +```bash .openhands/hooks/quality_gate.sh #!/bin/bash -cd "$OPENHANDS_PROJECT_DIR" +cd "${OPENHANDS_PROJECT_DIR:-$PWD}" -if ! npm run lint 2>&1; then - echo '{"decision":"deny","reason":"Linting failed. Please fix the issues before finishing."}' +# Replace this with your repo's checks, such as npm run lint, pytest, or make test. +if ! pre-commit run --all-files 2>&1; then + echo '{"decision":"deny","reason":"Quality checks failed. Fix them before finishing."}' exit 2 fi @@ -58,16 +58,12 @@ Then register it in `.openhands/hooks.json`: { "matcher": "*", "hooks": [ - { - "type": "command", - "command": ".openhands/hooks/lint_check.sh", - "timeout": 120 - } + { "command": ".openhands/hooks/quality_gate.sh", "timeout": 120 } ] } ] } ``` -See the dedicated [Hooks](/openhands/usage/customization/hooks) page for the full guide, including hook event types, -blocking behavior, and JSON response format. +If you already have `.openhands/pre-commit.sh`, move the checks into a Stop hook script like the one above. See the +[Hooks](/openhands/usage/customization/hooks) guide for complete behavior and JSON response details. From aa1e7cad0de141f3be93783710a9ecef37cecd6f Mon Sep 17 00:00:00 2001 From: openhands Date: Sun, 10 May 2026 15:06:01 +0000 Subject: [PATCH 3/3] docs: clarify stop hook quality gate guidance Co-authored-by: openhands --- openhands/usage/customization/repository.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/openhands/usage/customization/repository.mdx b/openhands/usage/customization/repository.mdx index 2e7f3d7ae..472bd1e53 100644 --- a/openhands/usage/customization/repository.mdx +++ b/openhands/usage/customization/repository.mdx @@ -42,7 +42,7 @@ For example, create `.openhands/hooks/quality_gate.sh`: cd "${OPENHANDS_PROJECT_DIR:-$PWD}" # Replace this with your repo's checks, such as npm run lint, pytest, or make test. -if ! pre-commit run --all-files 2>&1; then +if ! make test 2>&1; then echo '{"decision":"deny","reason":"Quality checks failed. Fix them before finishing."}' exit 2 fi @@ -65,5 +65,6 @@ Then register it in `.openhands/hooks.json`: } ``` -If you already have `.openhands/pre-commit.sh`, move the checks into a Stop hook script like the one above. See the +If you currently use `.openhands/pre-commit.sh`, migrate those checks to Stop hooks when you want quality gates to apply +to current agent-server-backed OpenHands flows. Move the check commands into a Stop hook script like the one above. See the [Hooks](/openhands/usage/customization/hooks) guide for complete behavior and JSON response details.