Claude ↔ Codex Autonomous Loop

A reusable Codex skill for the loop:

Claude Code runs a calculation → Codex checks hourly → reconciles and critically reviews the evidence → sends one next prompt → repeats until verified success or a stopping condition.

Derived from a working convex-hull research workflow. The reusable skill keeps its persistent ledger and marked prompts, adding configurable criteria, limits, artifact checkpoints and explicit claim/issue reconciliation.

flowchart LR
    C[Claude executes a milestone] --> H[Hourly Codex heartbeat]
    H --> R[Reconcile UI, artifacts, claims and issues]
    R --> V[Review and verify results]
    V --> S{Success or stop?}
    S -->|continue| P[Save one bounded prompt]
    P --> D[Record dispatch intent, send once, observe receipt]
    D --> C
    S -->|yes| F[Save outcome and pause schedule]

Install this repository's folder as claude-codex-loop in your client's skill directory. For clients using the current .agents/skills convention, from the repository root:

mkdir -p "$HOME/.agents/skills"
ln -s "$PWD" "$HOME/.agents/skills/claude-codex-loop"

Some clients discover ~/.codex/skills; use your client's directory. Do not replace an existing skill at the destination. Claude does not need the skill installed.

Specify them in your starting prompt to Codex. The skill saves them in a JSON configuration for that run. For example:

Use $claude-codex-loop for /work/my-calculation and my existing Claude Code conversation "My calculation," session SESSION_ID. Review every hour and automatically send follow-up prompts. Keep the work within this local project.

The goal is to produce a rigorous certificate for [precise claim]. Count success only when Codex has checked the certificate against that claim and resolved all blocking objections.

Stop after 20 follow-up prompts, 48 hours, or 3 consecutive reviews without verified progress, whichever comes first.

Replace the project path, conversation/session and claim with your own. The configuration template separates:

• goal: what you want accomplished.
• success_criteria: what evidence must establish before declaring success.
• max_rounds, max_hours, max_no_progress_reviews: limits that stop an unfinished run.

The controller checks the numerical limits. Whether the scientific criteria are satisfied depends on the recorded review and verification; reaching a limit does not count as success. Settings are fixed when a run starts. Editing the original configuration file does not alter an active run; use a newly authorized run with new settings and preserve the old ledger.

Codex records the scope and criteria, adopts the current calculation, performs a first tick, and creates a same-chat hourly schedule using the available tool. Routine rounds need no further confirmation. Installation itself starts nothing. See setup for configuration, commands, dependencies and limits.

The original goal and fixed success criteria remain the reference throughout the run. In each review, Codex checks:

• What the latest round actually accomplished, using its response and artifacts.
• Whether that work advances the original goal and what evidence supports each original success criterion.
• Whether earlier claims or unresolved objections need revisiting in light of the latest results.

Completing a milestone does not finish the overall task. The loop declares success only when every original success criterion is recorded as met and no blocking objections remain open. Earlier claims and objections stay in the record, with corrections, retractions and resolutions made explicit.

The controller enforces the criterion bookkeeping and stopping rules. Codex still has to judge whether the evidence supports each conclusion; the controller cannot establish scientific correctness from a passing label.

• Compare the ledger with the actual Claude conversation, sent marker and final response. Never infer completion from an inactive file or a handoff's PASS label.
• Hash selected inputs, code and outputs. If files change after review, require a fresh review before sending the next prompt.
• Link each review to its predecessor by hash. Carry forward every claim and issue ID, recording corrections, retractions and resolutions explicitly.
• Require evidence for every success criterion; an open blocking issue prevents success. A budget limit is recorded as an incomplete stop.
• Freeze prompt text and persist submitting before touching the UI. Recover an uncertain submission by observing its marker. Never replay it blindly.
• Use leases and atomic local writes to coordinate overlapping or interrupted ticks.

This is a cooperative workflow with crash recovery. It cannot establish truth from two model opinions, guarantee exactly-once UI delivery, sandbox project code, or enforce dollar budgets. Its drift coverage is limited to configured watched files.

The desktop workflow needs a same-chat scheduling tool, supported computer use that can operate Claude's UI, authenticated Claude Code/Codex sessions, and Python 3.10+ on macOS/Linux. Keep the local host and desktop app running. This repository does not install those tools, introduce an API runner, or bypass approvals/logins. Availability varies by client. Official scheduling documentation describes same-chat schedules and local-host requirements.

The source workflow has run on a real convex-hull project. The generalized controller is validated with isolated, simulated UI observations and temporary projects, covering interrupted sends, concurrent ownership, drift, stale evidence, claim continuity and stopping behavior. This is not an end-to-end demonstration on every desktop client. Tests never send a live Claude prompt.

Local validation on 2026-10-17: 28 tests passed on macOS with Python 3.14.6, and the Codex skill validator passed. GitHub Actions is configured for macOS/Linux with Python 3.10/3.12; those CI jobs have not yet run for this repository.

python3 -m unittest discover -s tests -v

Runtime state belongs in a private supervisor directory outside Claude's project and outside this skill repository. Do not publish actual transcripts, identifiers, prompts, credentials or research artifacts with the reusable package.

Licensed under the MIT License.