Problem / motivation
Ralph is useful because it can run AI coding CLIs in repeated unattended loops. After each iteration, the agent may have produced a diff that should ideally be checked before the loop continues, before a PR is opened, or before maintainers spend review time on it.
Right now, teams that want this kind of review gate probably need to wrap Ralph externally or rely only on CI after the fact. A small generic post-iteration hook would make this easier while keeping Ralph focused on orchestration.
Proposed solution
Add an optional post-iteration hook that runs after each agent iteration and receives enough context to inspect what changed.
The hook could receive either:
- the generated diff on stdin,
- a path to a diff file,
- or a small JSON envelope with repo path, iteration number, changed files, base/head refs, and log/output paths.
It could return a structured decision such as:
- "continue" — keep looping
- "warn" — continue, but show findings in the run summary
- "stop" — stop the loop because a blocking finding was detected
- "annotate" — attach findings to the final output or PR body
Example configuration shape:
[hooks.post_iteration]
command = "some-review-tool scan --diff --format json"
fail_on = ["high"]
This would allow teams to plug in their own review tools for generated diffs, missing tests, dependency/config changes, repository-specific policies, or approval gates without Ralph needing to know about any specific tool.
Alternatives considered
-
Run review tools only in CI after Ralph finishes.
- This works, but feedback comes later and cannot influence whether the loop should continue.
-
Wrap Ralph externally with custom scripts.
- This is possible, but each team has to solve the same orchestration problem independently.
-
Add direct support for a specific review tool.
- I think a generic hook is better. It keeps Ralph tool-agnostic and lets users bring their own scanner, policy engine, or review workflow.
Additional context
I maintain an open-source project called VibeGuard, which is a deterministic review gate for AI-generated diffs. It could be one possible example implementation for this kind of hook.
That said, the main proposal here is not “integrate VibeGuard directly”. The useful part would be the extension point itself: Ralph exposes a stable post-iteration hook contract, and users can plug in whichever review tool fits their environment.
Happy to prototype a minimal hook contract or draft a PR if this direction fits the project.
Problem / motivation
Ralph is useful because it can run AI coding CLIs in repeated unattended loops. After each iteration, the agent may have produced a diff that should ideally be checked before the loop continues, before a PR is opened, or before maintainers spend review time on it.
Right now, teams that want this kind of review gate probably need to wrap Ralph externally or rely only on CI after the fact. A small generic post-iteration hook would make this easier while keeping Ralph focused on orchestration.
Proposed solution
Add an optional post-iteration hook that runs after each agent iteration and receives enough context to inspect what changed.
The hook could receive either:
It could return a structured decision such as:
Example configuration shape:
[hooks.post_iteration]
command = "some-review-tool scan --diff --format json"
fail_on = ["high"]
This would allow teams to plug in their own review tools for generated diffs, missing tests, dependency/config changes, repository-specific policies, or approval gates without Ralph needing to know about any specific tool.
Alternatives considered
Run review tools only in CI after Ralph finishes.
Wrap Ralph externally with custom scripts.
Add direct support for a specific review tool.
Additional context
I maintain an open-source project called VibeGuard, which is a deterministic review gate for AI-generated diffs. It could be one possible example implementation for this kind of hook.
That said, the main proposal here is not “integrate VibeGuard directly”. The useful part would be the extension point itself: Ralph exposes a stable post-iteration hook contract, and users can plug in whichever review tool fits their environment.
Happy to prototype a minimal hook contract or draft a PR if this direction fits the project.