Recommend Stop hooks for repository quality gates

[neubig]

Summary

• Replace the repository customization page's .openhands/pre-commit.sh guidance with .openhands/hooks.json Stop hook guidance.
• Explain that Stop hooks work across current agent-server-backed OpenHands flows and can enforce formatting/lint/test checks before the agent finishes.
• Link readers to the Hooks guide for complete behavior and JSON response details.

Verification

• Reviewed rendered Markdown/MDX diff locally.

This PR was created by an AI agent (OpenHands) on behalf of the user.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	May 9, 2026, 10:43 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[all-hands-bot]

🟡 Acceptable - Documentation update is technically sound but could be more comprehensive.

[all-hands-bot]

[IMPROVEMENT OPPORTUNITIES]

The documentation change is sound, but consider these enhancements:

1. Example Coverage - The old documentation showed both frontend (npm lint) and backend (pytest) examples. The new example only demonstrates frontend linting. Adding a backend example or showing how to combine multiple checks would provide more comprehensive guidance.

2. Migration Path - Users with existing .openhands/pre-commit.sh files have no guidance on how to migrate to the new Stop hooks approach or what happens to their existing scripts.

3. Error Handling - The example script doesn't validate that OPENHANDS_PROJECT_DIR is set before using it, which could lead to confusing failures.

4. Pattern Extension - No mention of how to extend the pattern for multiple checks (linting + tests + formatting, etc.)

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

This is a documentation-only change that updates guidance from pre-commit scripts to Stop hooks. The change is well-scoped to a single file and the new approach appears to align with current OpenHands architecture (agent-server-backed flows). No code execution paths are modified, and the examples are syntactically correct.

VERDICT:
✅ Worth merging - The documentation update reflects current best practices. The improvement suggestions would enhance completeness but are not blocking issues.

KEY INSIGHT:
Replacing pre-commit script documentation with Stop hooks is architecturally sound, but maintaining example breadth (frontend + backend patterns) would better serve the diverse developer audience.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

[neubig]

@OpenHands /iterate, but at the same time we don't want the docs to be too complex

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[neubig]

Updated in ca30b6c to keep the Stop hook guidance concise: the example now uses one generic quality-gate script, includes a short migration note for existing .openhands/pre-commit.sh, and avoids adding multiple separate examples.

This PR comment was created by an AI agent (OpenHands) on behalf of the user.

[openhands-ai]

Since my last summary, there were no additional code or documentation changes.

Checklist:

• ✅ The PR feedback was addressed with a concise docs update.
• ✅ The reviewer’s concern about avoiding excessive complexity was followed.
• ✅ The changes remain focused: one simplified Stop hook example, one short migration note, and one small related wording cleanup.
• ✅ No extraneous changes were added after the last summary, so nothing needs to be reverted.
• ✅ The branch was pushed, checks passed, and review threads were resolved.

Current remaining state:

• PR Recommend Stop hooks for repository quality gates #498 is mergeable and checks are green.
• It is still waiting on required review approval.

[all-hands-bot]

🟡 Acceptable - Documentation update is technically sound but has minor clarity issues that would improve user experience.

[RISK ASSESSMENT]

• Overall PR: 🟢 LOW - Documentation-only change with migration guidance and links to detailed reference. No breaking code changes.

VERDICT:
✅ Worth merging - The shift from pre-commit.sh to Stop hooks is well-documented and technically correct. Minor clarity improvements would help users understand the migration path.

KEY INSIGHT:
The example would be more helpful if the code matched its explanatory comment, and the migration note clarified whether the old approach still works.

[neubig]

@OpenHands /iterate

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[all-hands-bot]

🟢 Good taste - Clear migration guidance with working examples.

[RISK ASSESSMENT]

• Overall PR: 🟢 LOW - Documentation-only change with clear migration path. No breaking code changes.

VERDICT:
✅ Worth merging - The documentation successfully guides users from .openhands/pre-commit.sh to Stop hooks with functional examples and appropriate links to comprehensive guides.

KEY INSIGHT:
Migration documentation strikes the right balance between providing working examples and linking to comprehensive guides.

[neubig]

Addressed the latest review feedback in aa1e7ca.

• Switched the placeholder quality gate command to make test so the example matches its generic comment and avoids implying pre-commit is required.
• Clarified that existing .openhands/pre-commit.sh checks should be migrated to Stop hooks when users want quality gates to apply to current agent-server-backed OpenHands flows.
• Resolved the two review threads.
• Checks are green on the latest SHA; the PR remains blocked only on required human review.

This PR comment was created by an AI agent (OpenHands) on behalf of the user.

[openhands-ai]

Since my last summary, there have been no additional changes.

Checklist:

• ✅ The PR comment was handled.
• ✅ The two latest review suggestions were addressed with concise documentation edits.
• ✅ The changes were pushed to the PR branch.
• ✅ Review threads were replied to and resolved.
• ✅ The OpenHands review bot re-reviewed the latest SHA positively.
• ✅ Checks were green at final status.
• ✅ No extraneous changes were added after the last summary, so nothing needs to be reverted.

Remaining state:

• PR Recommend Stop hooks for repository quality gates #498 is mergeable but still blocked by required human review.