@jhlee0619/codexloop 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "cloop",
+  "owner": {
+    "name": "jhlee"
+  },
+  "metadata": {
+    "description": "CodexLoop — iterative improvement loop plugin that drives OpenAI Codex as a multi-role critic.",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "cloop",
+      "source": "./",
+      "description": "Drive OpenAI Codex through evaluate \u2192 suggest \u2192 rank \u2192 apply \u2192 validate \u2192 record iterations until convergence. Ships five slash commands (/cloop:start, /cloop:iterate, /cloop:status, /cloop:stop, /cloop:result) plus a stand-alone shell wrapper usable from Codex CLI.",
+      "version": "0.1.0",
+      "author": {
+        "name": "jhlee"
+      },
+      "repository": "https://github.com/jhlee0619/CodexLoop",
+      "license": "MIT",
+      "keywords": [
+        "codex",
+        "loop",
+        "iterative",
+        "refinement",
+        "review",
+        "adversarial",
+        "convergence",
+        "cloop"
+      ],
+      "category": "automation"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "cloop",
+  "version": "0.1.0",
+  "description": "CodexLoop: iterative improvement loop plugin that drives OpenAI Codex as a multi-role critic (evaluate \u2192 suggest \u2192 rank \u2192 apply \u2192 validate \u2192 record).",
+  "author": { "name": "jhlee" },
+  "keywords": ["codex", "loop", "iterative", "refinement", "review", "cloop"],
+  "license": "MIT"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,38 @@
+{
+  "name": "cloop",
+  "version": "0.1.0",
+  "description": "CodexLoop: drives Codex through strict evaluate \u2192 suggest \u2192 rank \u2192 apply \u2192 validate \u2192 record iterations via the `cloop` shell command. Activates ONLY when the user explicitly mentions one of `cloop`, `codexloop`, or `CodexLoop` by name.",
+  "author": {
+    "name": "jhlee",
+    "url": "https://github.com/jhlee0619/CodexLoop"
+  },
+  "homepage": "https://github.com/jhlee0619/CodexLoop",
+  "repository": "https://github.com/jhlee0619/CodexLoop",
+  "license": "MIT",
+  "keywords": [
+    "cloop",
+    "codex",
+    "loop",
+    "iterative",
+    "refinement",
+    "review",
+    "convergence"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "CodexLoop",
+    "shortDescription": "Iterative Codex loops with convergence guarantees.",
+    "longDescription": "CodexLoop drives OpenAI Codex through a strict six-step iteration cycle (evaluate \u2192 suggest \u2192 rank \u2192 apply \u2192 validate \u2192 record) until a goal is met or the loop converges. It forces Codex to emit at least two proposals per iteration, ranks them deterministically on six dimensions, applies the winner via git apply + commit, runs your tests, and records a full forensic trace under .loop/. This plugin activates ONLY when the user explicitly mentions `cloop` or `CodexLoop` by name \u2014 use it for iterative tasks the user wants to drive through cloop, not as a default strategy for generic iterative work.",
+    "developerName": "jhlee",
+    "category": "Automation",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://github.com/jhlee0619/CodexLoop",
+    "defaultPrompt": [
+      "Use cloop to iteratively fix the failing tests in tests/",
+      "Run a CodexLoop on src/ to eliminate the type errors",
+      "Start a cloop with goal X and budget 5 iterations"
+    ],
+    "brandColor": "#3B82F6",
+    "logo": "./assets/banner.png"
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhlee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,425 @@
+# CodexLoop
+
+<p align="center">
+  <img src="assets/banner.png" alt="CodexLoop — iterative improvement loop that drives OpenAI Codex as a multi-role critic" width="640">
+</p>
+
+> Iterative improvement loop plugin that drives OpenAI Codex as a multi-role
+> critic. Ships as a single repo that installs as both a **Claude Code
+> plugin** (via `/plugin marketplace`) and a **Codex CLI plugin** (via the
+> Codex marketplace), plus a standalone `cloop` shell binary for plain
+> terminals and CI.
+
+- **Repository**: <https://github.com/jhlee0619/CodexLoop>
+- **npm**: [`@jhlee0619/codexloop`](https://www.npmjs.com/package/@jhlee0619/codexloop) — installs the `cloop` binary globally
+- **Status**: MVP v0.1.0 — six slash commands + background workers + deterministic convergence. See [docs/future-work.md](docs/future-work.md) for the roadmap.
+
+---
+
+## What it does
+
+Every iteration strictly follows six steps:
+
+```
+evaluate → suggest → rank → apply → validate → record
+```
+
+Codex is used as a multi-role critic + improver (reviewer, adversarial
+critic, solution generator, refactor advisor, test designer). Every
+iteration is structurally forced to produce **at least two proposals**, a
+single "judge" Codex call ranks them on six dimensions (correctness,
+requirement satisfaction, simplicity, maintainability, riskInverse,
+testability), the runtime deterministically re-computes the winner,
+applies it with `git apply` + `git commit`, runs your configured
+test/lint/type commands, and records the full forensic trace under
+`<target-repo>/.loop/`.
+
+Loops terminate on: **goal-met**, **negligible-improvement**
+(convergence), **plateau**, **regression** / **divergence**, or a
+**budget limit** (iterations / time / codex calls).
+
+### Opinionated defaults
+
+- **Model**: `gpt-5.4`
+- **Reasoning effort**: `xhigh`
+
+These are forwarded to `codex exec` via `--model gpt-5.4 -c
+model_reasoning_effort=xhigh` and applied regardless of your
+`~/.codex/config.toml`, so loops are reproducible across machines and
+config changes. Override per loop with `/cloop:start --model <m>
+--effort <level>` or permanently for the active loop with `/cloop:model
+<m> --effort <level>`.
+
+### Interview + approval (Claude Code and Codex CLI)
+
+When you invoke CodexLoop through an LLM orchestrator (Claude Code or
+Codex CLI), the plugin runs a **five-phase interview** before launching
+the runtime:
+
+1. **Pre-flight** — git repo check, clean working tree, `codex`/`cloop` availability
+2. **Goal capture + clarification** — rewrite vague input into one concrete immutable sentence
+3. **Plan assembly** — infer test/lint/type commands from `package.json` / `Makefile` / `pyproject.toml`, confirm budget, choose `--wait` vs `--background`
+4. **Approval** — show the full plan and wait for explicit go/no-go
+5. **Invoke** — call `cloop start …` with every confirmed flag
+
+Direct shell callers (`cloop start …` in a plain terminal or CI job) skip
+the interview and take flags as-is, so CodexLoop remains deterministic
+and scriptable.
+
+CodexLoop is a **peer** of the `openai-codex` plugin, not a replacement.
+It uses the same `codex` CLI binary and expects you to have run
+`/codex:setup` once (or `npm install -g @openai/codex`).
+
+---
+
+## Requirements
+
+- **Node.js** 20 or newer.
+- **git** 2.20+ with a clean working tree in the target repository.
+- **`codex` CLI** installed and authenticated.
+
+---
+
+## Installation
+
+CodexLoop installs on three platforms from the same repo. Pick whichever
+matches your workflow — they compose freely and do not conflict.
+
+### 1. One-line install script (universal — recommended)
+
+Handles Claude Code + Codex CLI + plain shell in one go:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jhlee0619/CodexLoop/main/install.sh | sh
+```
+
+The script:
+
+1. Downloads the latest `main` tarball from GitHub into `~/.local/share/cloop/`
+2. Symlinks `~/.local/bin/cloop` to the shell wrapper (plain-shell + Codex CLI + CI)
+3. Symlinks `~/.claude/plugins/cloop/local/0.1.0/` to the install dir if `~/.claude/plugins/` exists (Claude Code plugin)
+4. Symlinks `~/plugins/cloop` to the install dir and adds a `cloop` entry to `~/.agents/plugins/marketplace.json` if `codex` is on `$PATH` (Codex CLI plugin)
+
+Override paths with env vars (`CLOOP_REPO`, `CLOOP_REF`, `CLOOP_INSTALL_DIR`,
+`CLOOP_BIN_DIR`). The script is idempotent and safe to re-run for updates.
+
+### 2. npm global install (shell binary only)
+
+If you only need the `cloop` shell wrapper (for CI, Codex CLI, or plain
+terminals) and do not want the Claude Code plugin:
+
+```bash
+npm install -g @jhlee0619/codexloop
+cloop --help
+```
+
+This installs `bin/cloop` onto your `$PATH` and carries the runtime
+scripts + prompts + schemas along with it. It does NOT register with
+Claude Code — use path 1 or path 3 for that.
+
+> **Why `@jhlee0619/codexloop` and not `@jhlee0619/CodexLoop`?** npm
+> requires all package names to be lowercase; scoped names cannot
+> contain capital letters. The package name is the closest lowercase
+> match to the GitHub repo name.
+
+### 3. Claude Code plugin marketplace
+
+If you only want `/cloop:*` slash commands inside Claude Code:
+
+```text
+/plugin marketplace add jhlee0619/CodexLoop
+/plugin install cloop@cloop
+```
+
+Claude Code clones `github.com/jhlee0619/CodexLoop` into
+`~/.claude/plugins/marketplaces/cloop/`, reads
+`.claude-plugin/marketplace.json`, and installs the single `cloop` plugin
+it lists. The six slash commands appear under `/help` immediately.
+
+Update later with:
+
+```text
+/plugin marketplace update cloop
+/plugin install cloop@cloop
+```
+
+### 4. Codex CLI plugin (manual)
+
+If you want the Codex CLI plugin without running the one-line installer:
+
+```bash
+# Clone or symlink into Codex's home-local plugin dir:
+git clone https://github.com/jhlee0619/CodexLoop.git ~/plugins/cloop
+# or, if you already have the repo somewhere:
+# ln -s /path/to/CodexLoop ~/plugins/cloop
+
+# Add cloop to your home-local Codex marketplace:
+mkdir -p ~/.agents/plugins
+cat > ~/.agents/plugins/marketplace.json <<'JSON'
+{
+  "name": "home-local",
+  "interface": { "displayName": "Home-local plugins" },
+  "plugins": [
+    {
+      "name": "cloop",
+      "source": { "source": "local", "path": "./plugins/cloop" },
+      "policy": { "installation": "AVAILABLE", "authentication": "NONE" },
+      "category": "Automation"
+    }
+  ]
+}
+JSON
+```
+
+Restart any active Codex session. Codex will auto-load
+`skills/cloop/SKILL.md`, which activates the skill **only** when you name
+cloop by keyword (see "Codex activation gating" below).
+
+### 5. Manual clone + symlink (for plugin development)
+
+If you are hacking on CodexLoop itself:
+
+```bash
+git clone https://github.com/jhlee0619/CodexLoop.git /path/to/CodexLoop
+ln -s /path/to/CodexLoop ~/.claude/plugins/cloop/local/0.1.0
+ln -s /path/to/CodexLoop ~/plugins/cloop
+ln -s /path/to/CodexLoop/bin/cloop ~/.local/bin/cloop
+```
+
+Edits under `/path/to/CodexLoop/` take effect immediately because the
+plugin caches are symlinks.
+
+---
+
+## Quickstart (Claude Code)
+
+```text
+/codex:setup                    # one-time Codex install + auth (from openai-codex plugin)
+
+# inside the target repo, with a clean working tree — just say what you want:
+/cloop:start fix the failing add tests
+```
+
+Claude Code walks you through:
+
+1. **Goal** — reads `TASK.md` / `GOAL.md` / `PRD.md` / `AGENTS.md` if present, or asks you directly; rewrites your wording into one concrete sentence and confirms.
+2. **Plan** — infers plausible `--test-cmd` / `--lint-cmd` / `--type-cmd` candidates from `package.json` / `Makefile` / `pyproject.toml` / `go.mod`; confirms the budget (iterations, time); defaults the model to `gpt-5.4` + `xhigh`.
+3. **Approval** — shows the full plan and asks `Start loop with this plan?` before launching anything. You can edit the goal or plan details without re-typing.
+4. **Run** — records the current HEAD as `seedCommit`, adds `.loop/` to `.gitignore`, and drives the six-step iteration cycle until the verdict is `goal-met` AND validation exits 0, OR the loop converges, OR a budget limit fires.
+
+Then check `/cloop:result --diff` for the final state.
+
+Power users can bypass the approval dialog by supplying every flag up front and adding `--yes`:
+
+```text
+/cloop:start --wait --yes \
+             --goal "fix the failing add test" \
+             --max-iter 3 \
+             --test-cmd "node --test tests/" \
+             --model gpt-5.4 --effort xhigh
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/cloop:start` | Start a new loop. Runs the five-phase interview + approval first (skip with `--yes`), then launches the runtime. `--wait` for foreground, `--background` for OS-detached. |
+| `/cloop:iterate` | Run exactly one iteration synchronously. `--model <m>` / `--effort <e>` override the loop's stored values for this iteration only. |
+| `/cloop:status` | Show loop state, iteration history, budget consumption, convergence metrics. |
+| `/cloop:stop` | SIGTERM a running background worker (graceful, waits 60 s). Use `--force` for SIGKILL. |
+| `/cloop:result` | Dump the full iteration history with ranking breakdowns and validation output. |
+| `/cloop:model` | Show or change the Codex model + reasoning effort used by the active loop. Defaults are `gpt-5.4` / `xhigh`. |
+
+See [docs/command-spec.md](docs/command-spec.md) for every flag on every
+command.
+
+### `--wait` vs `--background`
+
+| Flag | Mode | Use when |
+|---|---|---|
+| `--wait` | **Foreground** — `cloop start` blocks the tool session until the loop terminates. Claude streams every iteration transcript inline. | Short loops, `--dry-run`, watching reasoning live, budget sanity checks. |
+| `--background` | **OS-detached** — runtime spawns a detached Node worker via `spawnDetached({ detached: true, stdio: "ignore" }).unref()`, writes `.loop/loop.pid`, and exits. The worker runs independently of Claude Code; closing the session does NOT kill it. | Real multi-minute loops. Poll progress with `/cloop:status`, stop with `/cloop:stop`. |
+
+Never pass both flags. If you pass neither, the interview recommends one
+based on `--max-iter` and `--dry-run`.
+
+---
+
+## Codex activation gating
+
+Codex auto-loads `skills/cloop/SKILL.md` on session start, but the skill's
+`description` field gates activation on an **explicit keyword match**. The
+skill only runs when your request contains one of these tokens
+(case-insensitive):
+
+- `cloop`
+- `codexloop`
+- `CodexLoop`
+- `CODEXLOOP`
+
+Activation examples:
+
+| What you say to Codex | Skill activates? |
+|---|---|
+| "Use cloop to fix the failing auth tests" | **yes** |
+| "codexloop this failing build" | **yes** |
+| "Start a CodexLoop on src/add.js" | **yes** |
+| "CODEXLOOP — fix the broken adds function" | **yes** |
+| "iteratively fix the auth tests" | no — no cloop keyword |
+| "keep trying until the tests pass" | no — no cloop keyword |
+| "loop on this until it works" | no — no cloop keyword |
+
+When the skill activates, it walks through the same five-phase interview
+(pre-flight → goal → plan → approval → invoke) that `/cloop:start` does
+in Claude Code, and only then invokes `cloop start …` as a shell command.
+Defaults (`gpt-5.4`, `xhigh`) and the immutable goal hash apply
+identically on both platforms.
+
+Codex calls `cloop` as a regular shell command; because CodexLoop spawns
+its own `codex exec` children, the running Codex session is used only to
+orchestrate the wrapper — each loop iteration is an **independent**,
+ephemeral Codex invocation, so the outer Codex session's context is
+never burned by the loop.
+
+---
+
+## Using `cloop` directly from a shell (no LLM)
+
+When the `cloop` wrapper is on `$PATH` (via any install path above), you
+can drive it directly from any terminal or script. There is **no
+interview** on this path — the runtime takes your flags verbatim, so it
+is safe for CI, scripted automation, and power-user shell usage.
+
+```bash
+# Full-flag form:
+cloop start --wait --yes \
+            --goal "fix the failing add test" \
+            --test-cmd "node --test tests/" \
+            --max-iter 3
+
+# Positional shortcut — the goal is the free-form text:
+cloop start --wait --yes "fix the failing add test" \
+            --test-cmd "node --test tests/" --max-iter 3
+
+cloop status
+cloop result --diff
+cloop stop
+```
+
+The interview only runs when an LLM orchestration layer (Claude via
+`/cloop:start`, or Codex via the skill) sits above `cloop`. In a plain
+shell, `cloop` is deterministic and trusts its flags.
+
+---
+
+## Safety by default
+
+- **Clean working tree required.** Every iteration starts from a clean state so `git reset --hard` is an unambiguous rollback path.
+- **Atomic state writes.** Every write to `.loop/state.json` uses temp-file-plus-rename so a crash mid-write never corrupts the canonical state.
+- **Reward-hacking guards.** The runtime rejects patches that delete test files, add `.skip` / `xit` / `.only` in test files, or modify tests without a substantive justification. Both the `suggest` and `rank` prompts forbid these patterns, and `apply.mjs` hard-rejects them if they slip through.
+- **Deterministic ranking.** The judge's weighted sum is never trusted blindly — `rank.mjs::recomputeWinner` re-computes from the raw dimensional scores and uses the runtime's pick if the two disagree.
+- **Budget caps.** `--max-iter`, `--max-time`, and `--max-calls` are enforced before every iteration starts (including dry-run).
+- **Goal immutability.** `state.goal.goalHash = sha256(text + acceptanceCriteria + testCmd + lintCmd + typeCmd)` is asserted on every iteration. Any drift fails loudly.
+- **Single loop per repo.** An advisory lock at `.loop/loop.lock` (keyed by worker PID) refuses a second concurrent loop in the same repo.
+
+---
+
+## Documentation
+
+| File | Purpose |
+|---|---|
+| [docs/architecture.md](docs/architecture.md) | Design overview, directory layout, Codex invocation pattern |
+| [docs/iteration-policy.md](docs/iteration-policy.md) | The six-step cycle, role definitions, proposal rules |
+| [docs/state-schema.md](docs/state-schema.md) | The `.loop/state.json` shape + per-iteration dump shape |
+| [docs/command-spec.md](docs/command-spec.md) | Every flag on every slash command |
+| [docs/stopping-criteria.md](docs/stopping-criteria.md) | Quality score formula + convergence triggers |
+| [docs/known-limitations.md](docs/known-limitations.md) | What MVP does NOT do (yet) |
+| [docs/future-work.md](docs/future-work.md) | v0.5 / v1 roadmap |
+| [docs/examples/01-bugfix-loop.md](docs/examples/01-bugfix-loop.md) | Step-by-step walk-through of a real bugfix loop |
+
+---
+
+## Tests
+
+No framework dependency — every test is a standalone `node` script.
+
+```bash
+node tests/unit/state.test.mjs         # 55 tests: defaults, round-trip, lock, migration, model/effort
+node tests/unit/rank.test.mjs          # 15 tests: weighted score, tiebreaker, reward-hacking floor
+node tests/unit/convergence.test.mjs   # 16 tests: quality score, goal-met, budget, negligible, plateau, divergence
+node tests/integration/loop-smoke.test.mjs  # 50 tests: end-to-end dry-run with mock codex
+```
+
+The integration smoke test sets up a scratch git repo in `/tmp`, points
+the runtime at `tests/fixtures/mock-codex-exec.mjs` via
+`CODEXLOOP_CODEX_BIN`, and runs a full dry-run loop that reaches
+`goal-met`. It spends zero Codex budget.
+
+**Total: 136 tests passing.**
+
+---
+
+## Plugin manifests
+
+CodexLoop ships two platform manifests at the repo root:
+
+- `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` — Claude Code plugin + marketplace entry
+- `.codex-plugin/plugin.json` — Codex CLI plugin manifest (skills discovered from `skills/`)
+
+The same Node runtime (`scripts/loop-companion.mjs`) and the same shell
+wrapper (`bin/cloop`) back both plugins. No code is duplicated between
+platforms.
+
+---
+
+## Acknowledgments
+
+CodexLoop is an independent project but its design borrows generously
+from two upstream projects. Neither is a dependency — every line of
+CodexLoop is an original reinterpretation — but both deserve explicit
+credit.
+
+### [snarktank/ralph](https://github.com/snarktank/ralph)
+
+Ralph (after Geoffrey Huntley's "Ralph Wiggum" pattern) is the
+iterative-loop project that popularized the idea of **driving an LLM
+through a stateless fresh-context loop with file-based state carrying
+the only memory between iterations**. CodexLoop inherits that core
+principle:
+
+- Every Codex call runs `codex exec --ephemeral` — no session reuse, no conversational memory across iterations.
+- All state lives in files under `<repo>/.loop/` — `state.json` is the canonical shape, per-iteration dumps are in `iterations/NNNN.json`, and an append-only `progress.log` captures the learning trajectory the way Ralph's `progress.txt` does.
+- One story (one proposal) applied per iteration, scope-disciplined by design.
+- An explicit "completion marker" decides when the loop terminates — in CodexLoop the reviewer emits `verdict: "goal-met"` and the runtime verifies via one more validation pass before accepting it.
+
+Ralph's stateless-loop pattern is the mental model CodexLoop extends to
+a multi-role critic system.
+
+### [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
+
+The official Codex plugin for Claude Code is the reference architecture
+for how a Claude Code plugin should wrap the `codex` CLI. CodexLoop
+studies (but does not import) many of its structural conventions:
+
+- Minimal `.claude-plugin/plugin.json` manifest with auto-discovery for `commands/`, `skills/`, `agents/`.
+- Command file frontmatter with `description`, `argument-hint`, `disable-model-invocation`, `allowed-tools`, plus an inline `!`node ...`` body shell form for read-only commands.
+- `$ARGUMENTS` passthrough + the foreground-vs-background UX pattern using `AskUserQuestion`.
+- A Node companion script (`scripts/codex-companion.mjs`) that verb-dispatches, spawns detached background workers via `{ detached: true, stdio: "ignore" }` + `.unref()`, and manages workspace-scoped state directories.
+- JSON-schema-driven Codex outputs via `codex exec --output-schema`, with XML-tagged prompt templates (`<role>`, `<task>`, `<structured_output_contract>`, `<grounding_rules>`, `<final_check>`).
+- The `codex-rescue` subagent pattern — a thin forwarder that delegates to Codex via a skill-routed one-shot call.
+
+CodexLoop's `scripts/loop-companion.mjs`, `commands/*.md`,
+`prompts/*.md`, and `schemas/*.json` are original code written from
+scratch — no file is copied — but they are line-by-line recognizable as
+siblings of the openai-codex plugin's counterparts. A reader familiar
+with that plugin can navigate CodexLoop with zero cognitive tax.
+
+Thanks to both projects for publishing their work openly.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/cloop

@@ -0,0 +1,45 @@
+#!/usr/bin/env sh
+# cloop — shell wrapper for CodexLoop's loop-companion.mjs.
+#
+# Works from any directory, including when this script is symlinked into
+# /usr/local/bin or ~/.local/bin. It locates the companion script relative
+# to its own physical path and execs `node` against it.
+#
+# Usage:
+#   cloop start   [flags]
+#   cloop iterate [flags]
+#   cloop status  [flags]
+#   cloop stop    [flags]
+#   cloop result  [flags]
+#
+# See `docs/command-spec.md` or `cloop --help` for every flag.
+
+set -eu
+
+# Resolve the physical path of this script, following symlinks manually so
+# we do not depend on GNU `readlink -f` (macOS ships BSD readlink by default).
+SCRIPT=$0
+while [ -h "$SCRIPT" ]; do
+  DIR=$(cd -P "$(dirname "$SCRIPT")" && pwd)
+  LINK=$(readlink "$SCRIPT")
+  case "$LINK" in
+    /*) SCRIPT=$LINK ;;
+    *)  SCRIPT="$DIR/$LINK" ;;
+  esac
+done
+SCRIPT_DIR=$(cd -P "$(dirname "$SCRIPT")" && pwd)
+
+# bin/ lives at the plugin root; the companion is in scripts/.
+COMPANION="$SCRIPT_DIR/../scripts/loop-companion.mjs"
+
+if [ ! -f "$COMPANION" ]; then
+  printf 'cloop: cannot find loop-companion.mjs (looked at %s)\n' "$COMPANION" >&2
+  exit 1
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  printf 'cloop: node is not on PATH. Install Node 20+ first.\n' >&2
+  exit 1
+fi
+
+exec node "$COMPANION" "$@"

package/commands/iterate.md

@@ -0,0 +1,25 @@
+---
+description: Run exactly one iteration of the current CodexLoop (evaluate -> suggest -> rank -> apply -> validate -> record)
+argument-hint: '[--dry-run] [--skip-apply]'
+disable-model-invocation: true
+allowed-tools: Read, Bash(node:*), Bash(git:*)
+---
+
+Run exactly one iteration of the current CodexLoop. Always synchronous and foreground so the user sees the full per-iteration transcript (evaluation findings, ranked proposals, applied patch, validation summary, quality delta).
+
+Raw slash-command arguments:
+`$ARGUMENTS`
+
+Core constraint:
+- You do not generate proposals, apply patches, or run tests yourself.
+- Return the companion script's stdout verbatim to the user. Do not paraphrase.
+
+Run:
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" iterate $ARGUMENTS
+```
+
+Return the command stdout verbatim. Preserve the evaluation findings, proposal summaries, ranking breakdown, patch apply result, and validation output exactly as printed.
+
+If the companion script reports "No active loop", tell the user to run `/cloop:start` first.
+If the companion script reports `Codex CLI is not ready`, tell the user to run `/codex:setup` from the `openai-codex` plugin.

package/commands/model.md

@@ -0,0 +1,33 @@
+---
+description: Show, set, or clear the Codex model and reasoning effort used by the current CodexLoop
+argument-hint: '[<model>] [--effort <level>] [--list] [--clear] [--json]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" model $ARGUMENTS`
+
+Present the output verbatim to the user. Preserve the model name, the
+reasoning effort, the previous/current labels, and any alias-expansion note
+exactly as printed.
+
+Usage summary:
+- `/cloop:model` — show the current model and reasoning effort for the active loop
+- `/cloop:model <name>` — set the model (e.g. `/cloop:model gpt-5.4-mini`, or the `spark` alias)
+- `/cloop:model --effort <level>` — set the reasoning effort (one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`)
+- `/cloop:model <name> --effort <level>` — set both at once
+- `/cloop:model --clear` — reset BOTH model and effort to the codex CLI default (from `~/.codex/config.toml`)
+- `/cloop:model --list` — list known model aliases and valid reasoning effort values (repo-independent)
+- `/cloop:model --json` — emit structured JSON instead of Markdown
+
+**Defaults**: `cloop` ships with `gpt-5.4` as the default model and `xhigh`
+as the default reasoning effort. These are applied at `/cloop:start` time
+regardless of your `~/.codex/config.toml`, so the loop is reproducible even
+if your Codex config changes.
+
+If the command reports "No active loop", tell the user to run
+`/cloop:start` first, or run `/cloop:model --list` which works without an
+active loop.
+
+If the command reports that the loop is in a terminal state, tell the user
+to start a new loop with `/cloop:start --model <name> --effort <level>`.

package/commands/result.md

@@ -0,0 +1,17 @@
+---
+description: Retrieve the full result of the current or completed CodexLoop (iteration history, ranking breakdowns, validation results)
+argument-hint: '[--iteration N] [--json] [--diff]'
+disable-model-invocation: true
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/loop-companion.mjs" result $ARGUMENTS`
+
+Present the full command output verbatim. Preserve all details including:
+- status table and iteration history
+- per-iteration evaluation findings, proposals, ranking breakdown
+- applied patch results, validation summaries, quality scores
+- file paths and sha hints exactly as printed
+- any reported stopReason or error
+
+Do not summarize or condense the output.