RealStop

A local Stop hook for Claude Code that catches work handed back to you. When an agent tries to end with “Want me to add the requested tests?”, RealStop can return feedback and keep the turn going. Approval stops still belong to you; harness permissions remain the authority.

See it work · Install · Model card · Evidence · Limits

uv tool install realstop
realstop setup --judge local
realstop serve

The local server needs Apple silicon. Keep it running in a separate terminal. For no model download, use realstop setup --judge rules instead. For Codex CLI, use the separate rules adapter below.

Codex CLI

RealStop 0.2.0 adds a rules adapter for main-agent turns on macOS and Linux. Tested with Codex CLI 0.166.0. Install or upgrade with uv tool install --upgrade realstop, then run:

realstop setup --host codex --judge rules
# In a fresh Codex CLI session, open /hooks and review the RealStop commands.
realstop status --host codex

The first install uses shadow mode. Status counts eligible offers (would_block), other phrase hits, and passes. To enable a single continuation for a matching offer, run realstop setup --host codex --mode block. Use --mode shadow to switch back. Pause, resume and uninstall each accept --host codex. Existing Claude installations have their own configuration.

The adapter reuses the phrase detector, then checks whether the offered action matches a direct instruction from this turn. For example, “add a changelog entry” matches “Should I add the changelog entry?” A different optional offer passes. Matching is deliberately narrow. Successful matching cannot verify the state of a file. The nudge asks the agent to check for remaining authorized work and respect approvals. Plan mode, subagents, ambiguous or missing evidence, and repeated stops pass. Keep host permission controls enabled.

The adapter consumes UserPromptSubmit, PostToolUse and Stop. It keeps task fingerprints and tool counts under $CODEX_HOME/realstop (default ~/.codex/realstop), expires turn records after 24 hours on the next submit, and retains aggregate counts. It reads no transcript and calls no model service. Local/model/cloud judges, correction learning and the performance figures below apply to the Claude integration. See OpenAI’s hook specification.

Experimental confirmed hook

Version 0.2.3 includes an opt-in evidence-confirmed Stop hook for Claude Code and Codex. The existing realstop command and Codex rules adapter retain their behavior. This experimental hook uses native authenticated CLI verifiers and can send selected transcript evidence to the configured provider. Synthetic replay results are not real-session accuracy estimates; incomplete, oversized or unsupported sessions can abstain. Review the release notes before enabling it.

The seven-hour live observation found 0/36 eligible completed checks in one large, branched session: all failed ancestry parsing, with no verifier calls or blocks. This session was unsupported; no real-session protection or intervention quality was demonstrated. Version 0.2.3 fixes a proven class of parallel-tool ancestry failures, but compaction and other evidence limits still cause abstention. See the parser fix.

From a checkout of this release, run python3 scripts/install-confirmed-hooks.py --help to prepare a dry-run installation and review its configuration paths. The installer supports --mode shadow and --mode enforce, creates an immutable release, and provides a guarded rollback. Codex hook trust still requires host review. The optional realstop-screen classifier requires a separately supplied experimental bundle; no model weights are included in this release.

Set REALSTOP_TELEMETRY_PATH to a JSONL file inside a private directory to opt into local metadata-only hook telemetry. It records identifiers, timing, fixed status labels and a transcript digest, not transcript text. Write failures do not prevent stopping.

Experimental RealStop Supervisor

Version 0.2.3 also ships realstop.supervisor, a separate opt-in Python package for explicit task contracts, bounded artifact checks, evidence storage, scoped permissions and native-confirmed advisory claims. It is not enabled automatically. A separate Claude-only pilot launches a fresh private workspace for one explicit file-writing contract, permits at most one native-confirmed Stop block, and checks the final file hash. It does not attach to existing sessions or install global hooks. Start with python -m realstop.supervisor --help and the Supervisor guide.

This is the beginning of the README. Read the rest at the original. Read the full README ↗