[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81730":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":12,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},81730,"codex-loop","compozy\u002Fcodex-loop","compozy","Keep Codex tasks running until they meet a time or round-based completion target.",null,"Go",34,1,32,0,3,0.9,"MIT License",false,"main",[],"2026-06-12 02:04:18","\u003Cdiv align=\"center\">\n  \u003Ch1>Codex Loop\u003C\u002Fh1>\n  \u003Cp>\u003Cstrong>Keep Codex tasks running until they actually finish — by time, rounds, or independently confirmed goal.\u003C\u002Fstrong>\u003C\u002Fp>\n  \u003Cp>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\u002Factions\u002Fworkflows\u002Fci.yml\">\n      \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg\" alt=\"CI\">\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fpkg.go.dev\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\">\n      \u003Cimg src=\"https:\u002F\u002Fpkg.go.dev\u002Fbadge\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop.svg\" alt=\"Go Reference\">\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\">\n      \u003Cimg src=\"https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\" alt=\"Go Report Card\">\n    \u003C\u002Fa>\n    \u003Ca href=\"LICENSE\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg\" alt=\"License: MIT\">\n    \u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fcompozy\u002Fcodex-loop\u002Freleases\">\n      \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fcompozy\u002Fcodex-loop?include_prereleases\" alt=\"Release\">\n    \u003C\u002Fa>\n  \u003C\u002Fp>\n\u003C\u002Fdiv>\n\n`codex-loop` is a local-first Codex CLI and plugin that keeps explicitly activated Codex tasks running until they satisfy a minimum duration, a target number of deliberate rounds, or an independently confirmed goal.\n\nIt is designed for release-grade QA, long-running hardening passes, and repeated review loops where stopping after the first apparently complete answer is not enough.\n\n## ✨ Highlights\n\n- **Three loop modes.** Pick the limiter that fits the work: minimum duration (`min=\"6h\"`), deliberate round count (`rounds=\"3\"`), or independently confirmed goal (`goal=\"ship only after verification\"`).\n- **Activation by header, not flag.** Loops only start when the prompt's first line contains a structured `[[CODEX_LOOP ...]]` header, so day-to-day Codex use is untouched.\n- **Independent goal confirmation.** Goal loops invoke a configurable headless reviewer that returns normal text, then codex-loop privately interprets that text into a structured verdict.\n- **Pre-continuation context hook.** `pre_loop_continue` runs right before each automatic continuation so the next prompt can carry fresh local context — test summaries, changed files, build status, custom checklists.\n- **Built-in tracking skill.** The bundled `codex-loop` skill can bootstrap `.codex\u002Floop\u002F\u003Cname>\u002F` artifacts for restart-safe task state, per-iteration memory, validation evidence, and final completion signatures.\n- **Codex lifecycle integration.** Ships as a Codex plugin, contributing `UserPromptSubmit` and `Stop` hooks, and mirrors managed registrations into `~\u002F.codex\u002Fhooks.json` for current Codex builds.\n- **Local-first state.** Loop state lives under `~\u002F.codex\u002Fcodex-loop\u002F`, isolated by Codex `session_id`. Compact verdict metadata lands in `~\u002F.codex\u002Fcodex-loop\u002Fruns.jsonl`.\n- **Single Go binary.** No Python runtime, no daemon, and no built-in network client except the explicit `codex-loop upgrade` release download path. User-configured continuation and goal commands run as external tools.\n\n## 📦 Installation\n\n#### Go\n\n```bash\ngo install github.com\u002Fcompozy\u002Fcodex-loop\u002Fcmd\u002Fcodex-loop@latest\ncodex-loop install\n```\n\nFor an exact release:\n\n```bash\ngo install github.com\u002Fcompozy\u002Fcodex-loop\u002Fcmd\u002Fcodex-loop@v0.1.1\ncodex-loop install\ncodex plugin marketplace add compozy\u002Fcodex-loop --ref v0.1.1\ncodex plugin marketplace upgrade codex-loop-plugins\n```\n\nFor an existing install, `codex-loop` can perform the release download, checksum verification, managed runtime refresh, and Codex marketplace refresh in one command:\n\n```bash\ncodex-loop upgrade              # latest GitHub release\ncodex-loop upgrade --version v0.1.1\n```\n\n`codex-loop install` creates or updates:\n\n- `~\u002F.codex\u002Fcodex-loop\u002Fbin\u002Fcodex-loop`\n- `~\u002F.codex\u002Fcodex-loop\u002Floops\u002F`\n- `~\u002F.codex\u002Fcodex-loop\u002Fconfig.toml`\n- `~\u002F.codex\u002Fskills\u002Fcodex-loop\u002F` with the managed built-in tracking skill\n- `~\u002F.codex\u002Fhooks.json` with managed `UserPromptSubmit` and `Stop` hook registrations\n- `~\u002F.codex\u002Fconfig.toml` with `features.codex_hooks = true`\n\n#### Codex Plugin\n\nRegister this repo as a Codex plugin marketplace:\n\n```bash\ncodex plugin marketplace add compozy\u002Fcodex-loop\n```\n\nFor local development from this checkout:\n\n```bash\ncodex plugin marketplace add \u002Fpath\u002Fto\u002Fcodex-loop\n```\n\nThen restart Codex, open the plugin directory, and install `codex-loop` from the `Codex Loop Plugins` marketplace.\n\nThe plugin contributes lifecycle hooks from `plugins\u002Fcodex-loop\u002Fhooks\u002Fhooks.json`. `codex-loop install` mirrors the same managed hook commands into `~\u002F.codex\u002Fhooks.json` so current Codex builds execute them reliably while preserving unrelated user hooks.\n\n## 🚀 Activation\n\nThe activation header must be the first line of the prompt. The task prompt starts on the line after the header.\n\n#### Minimum-duration loop\n\n```text\n[[CODEX_LOOP name=\"release-stress-qa\" min=\"6h\"]]\nRun release-grade QA for this repository and keep expanding scope until the minimum duration is met.\n```\n\n#### Rounds-based loop\n\n```text\n[[CODEX_LOOP name=\"release-stress-qa\" rounds=\"3\"]]\nRun three deliberate QA passes for this repository and treat each stop as the end of one round.\n```\n\n#### Goal-based loop\n\n```text\n[[CODEX_LOOP name=\"release-stress-qa\" goal=\"ship only after real verification\"]]\nRun release-grade QA for this repository and keep going until the work is actually complete.\n```\n\n#### Goal-based loop with custom confirmation model\n\n```text\n[[CODEX_LOOP name=\"release-stress-qa\" goal=\"ship only after real verification\" confirm_model=\"gpt-5.5\" confirm_reasoning_effort=\"xhigh\"]]\nRun release-grade QA for this repository and keep going until the work is actually complete.\n```\n\n#### Header rules\n\n| Field                       | Required                | Notes                                                                       |\n| --------------------------- | ----------------------- | --------------------------------------------------------------------------- |\n| `name`                      | yes                     | Loop identifier                                                             |\n| `min`                       | one of                  | Duration: `30m`, `30min`, `1h 30m`, `2 hours`, `45sec`, etc.                |\n| `rounds`                    | one of                  | Positive integer                                                            |\n| `goal`                      | one of                  | Free-form verification goal; `goal=\"\"` reuses the task prompt as the goal   |\n| `confirm_model`             | only with `goal`        | Model for the goal confirmation run                                         |\n| `confirm_reasoning_effort`  | only with `goal`        | One of `minimal`, `low`, `medium`, `high`, `xhigh`                          |\n\nLoop state is isolated by Codex `session_id`. Exactly one limiter — `min`, `rounds`, or `goal` — is required.\n\n## 🧰 Commands\n\n```bash\ncodex-loop install\ncodex-loop upgrade\ncodex-loop upgrade --version v0.1.1\ncodex-loop status\ncodex-loop status --all\ncodex-loop status --session-id \u003Cid>\ncodex-loop status --workspace-root \u003Cpath>\ncodex-loop uninstall\ncodex-loop version\n```\n\n`status` prints JSON. By default it shows only active loops; use `--all` to include completed, superseded, and cut-short loops.\n\n## ⚙️ Continuation Customization\n\nThe global runtime config lives at `~\u002F.codex\u002Fcodex-loop\u002Fconfig.toml` and supports:\n\n```toml\noptional_skill_name = \"codex-loop\"\noptional_skill_path = \"\"\nextra_continuation_guidance = \"\"\n\n[hooks]\nstop_timeout_seconds = 2700\n\n[goal]\nconfirm_model = \"gpt-5.5\"\nconfirm_reasoning_effort = \"high\"\nconfirm_command = \"codex exec --cd $WORKSPACE_ROOT --ephemeral --yolo --output-last-message $CONFIRM_OUTPUT_PATH $MODEL_ARGV $REASONING_ARGV --skip-git-repo-check -\"\ntimeout_seconds = 2400\ninterpret_model = \"gpt-5.4-mini\"\ninterpret_reasoning_effort = \"low\"\ninterpret_timeout_seconds = 120\nmax_output_bytes = 12000\n\n[pre_loop_continue]\ncommand = \"\"\ncwd = \"session_cwd\"\ntimeout_seconds = 60\nmax_output_bytes = 12000\n```\n\n- `optional_skill_name = \"codex-loop\"` is the default installed behavior, so automatic continuations name the managed built-in tracking skill.\n- Set `optional_skill_name` to another non-empty skill name to override the built-in tracking skill.\n- `optional_skill_path` is optional. When set for a custom workspace skill, it may point to a skill directory or directly to `SKILL.md`, and must resolve inside the active workspace.\n- `extra_continuation_guidance` appends extra text to every automatic continuation.\n- `hooks.stop_timeout_seconds` controls the managed Codex `Stop` hook timeout written by `codex-loop install`; rerun `codex-loop install` and restart Codex after changing it.\n\nProjects may also define `codex-loop.toml` in the workspace. During an active loop, codex-loop searches from the Codex hook CWD up to the resolved workspace root and uses the nearest `codex-loop.toml` it finds. It never searches above the workspace root.\n\nProject config overlays the global config by field:\n\n- Effective runtime config is `defaults` -> global `~\u002F.codex\u002Fcodex-loop\u002Fconfig.toml` -> project `codex-loop.toml`.\n- Fields defined in `codex-loop.toml` override the global value.\n- Fields omitted from `codex-loop.toml` inherit the global value or default.\n- `command = \"\"` in project `[pre_loop_continue]` disables a global pre-loop command for that project.\n- `[hooks].stop_timeout_seconds` remains an install-time global setting. Local project config does not rewrite installed Codex hook registrations.\n\nProject-local example:\n\n```toml\n# .\u002Fcodex-loop.toml\noptional_skill_name = \"codex-loop\"\nextra_continuation_guidance = \"Resume from .codex\u002Floop\u002F\u003Cname>\u002Fstate.json and run one tracked action before stopping.\"\n\n[pre_loop_continue]\ncommand = \".codex\u002Fscripts\u002Floop-context.sh --input $INPUT_FILE\"\ncwd = \"workspace_root\"\ntimeout_seconds = 30\nmax_output_bytes = 8000\n```\n\n### 🧭 Built-In Tracking Skill\n\nThe plugin ships a `codex-loop` skill with two lanes. `codex-loop install`\ncopies that skill into `${CODEX_HOME:-$HOME\u002F.codex}\u002Fskills\u002Fcodex-loop\u002F` so\nthe name-only default `optional_skill_name = \"codex-loop\"` resolves as a\nnormal Codex skill instead of depending on a plugin cache path.\n\n- setup\u002Fstatus guidance for installing, upgrading, activating, and inspecting the runtime;\n- tracked execution for long-running implementation, QA, review, or remediation loops that need durable state across restarts.\n\nTracked execution stores project-local artifacts under:\n\n```text\n.codex\u002Floop\u002F\u003Cname>\u002F\n  request.md\n  state.json\n  tasks\u002Ftask-001.md\n  memory\u002FMEMORY.md\n  memory\u002Fiter-001.md\n```\n\nTo use it explicitly, include the skill in the prompt:\n\n```text\n[[CODEX_LOOP name=\"release-stress-qa\" goal=\"complete tracked QA with all tasks done, blockers closed, and verification PASS\"]]\n\nUse the codex-loop skill. Track the work under .codex\u002Floop\u002Frelease-stress-qa\u002F.\n```\n\n`codex-loop install` creates new runtime configs with\n`optional_skill_name = \"codex-loop\"` and migrates missing or blank\n`optional_skill_name` values to that default. Non-empty custom skill names are\npreserved. The managed skill copy is refreshed on every install. If\n`~\u002F.codex\u002Fskills\u002Fcodex-loop\u002F` already exists without the codex-loop management\nmarker, install stops instead of overwriting it.\n\n### 🎯 Goal Confirmation\n\nGoal loops run a configurable headless confirmation command inside the `Stop` hook before deciding whether to continue. The public confirmation command returns normal text. codex-loop then runs a private interpreter command that converts that text into the internal verdict JSON.\n\nThe default confirmation run uses `codex exec --yolo`, `gpt-5.5`, and `model_reasoning_effort = \"high\"`. Model and reasoning are separate settings; use `confirm_model = \"gpt-5.5\"` plus `confirm_reasoning_effort = \"xhigh\"` rather than a combined model string. Codex documents `--yolo` as full access without sandboxing or approvals; use a custom `confirm_command` when you need a different safety profile or runner.\n\nThe interpreter always uses `codex exec --sandbox read-only --output-schema`. Its model defaults to `gpt-5.4-mini` and reasoning effort defaults to `low`; users can change only the interpreter model, reasoning effort, and timeout. The interpreter command itself is intentionally not configurable so codex-loop can rely on Codex structured output and the user's existing Codex auth.\n\n**Runtime behavior:**\n\n- `confirm_command` is a shell-like string parsed to argv and executed without an implicit shell.\n- Placeholder values are shell-quoted before parsing so injected values remain literal arguments.\n- The default confirmation command runs with `--yolo`, `--ephemeral`, and `--output-last-message`; it does not receive an output schema.\n- Custom confirmation commands may write normal prose to `$CONFIRM_OUTPUT_PATH` or stdout.\n- The interpreter command is fixed to `codex exec` and produces the structured verdict internally.\n- If the interpreted verdict is complete, codex-loop marks the loop completed and emits no continuation prompt.\n- If the interpreted verdict is incomplete, invalid, timed out, or either command fails, codex-loop continues with a warning and keeps the loop active.\n- `goal.timeout_seconds` controls the confirmation timeout; `goal.interpret_timeout_seconds` controls the interpreter timeout. Both are normalized to leave time before the outer Stop hook timeout.\n- `goal.max_output_bytes` caps captured confirmation and interpreter output used for prompts and diagnostics.\n- Each confirmation attempt appends compact metadata to `~\u002F.codex\u002Fcodex-loop\u002Fruns.jsonl`.\n\n**Confirmation command variables:**\n\n- `$PROMPT`, `$PROMPT_FILE`, and `$CONFIRM_OUTPUT_PATH` expose the reviewer prompt and plain-text output file.\n- `$MODEL_ARGV` expands to `--model \u003Cmodel>` when a model is configured; `$REASONING_ARGV` expands to `--config model_reasoning_effort=\"\u003Ceffort>\"` when reasoning is configured.\n- `$MODEL`, `$REASONING_EFFORT`, `$WORKSPACE_ROOT`, `$CWD`, `$SESSION_ID`, `$LOOP_NAME`, `$LOOP_SLUG`, `$RUNS_LOG_PATH`, and `$CODEX_HOME` are also available.\n- The same values are exported with the `CODEX_LOOP_CONFIRM_` prefix.\n\n**Custom runner example:**\n\n```toml\n[goal]\nconfirm_model = \"opus\"\nconfirm_reasoning_effort = \"\"\nconfirm_command = \"compozy exec --ide claude --model $MODEL $PROMPT\"\n```\n\n### 🪝 `pre_loop_continue`\n\n`pre_loop_continue` is a codex-loop runtime hook that runs inside the managed `Stop` hook, immediately before codex-loop asks Codex to continue the active loop. For goal loops, it runs only after goal confirmation decides another round is needed. It is not a separate Codex lifecycle hook, which matters because independent Codex `Stop` hooks may run concurrently and cannot guarantee ordering.\n\nUse it when the next continuation prompt should include fresh local context computed at stop time, such as a test summary, changed-file summary, issue tracker snapshot, custom QA checklist, or local build status.\n\n**Runtime behavior:**\n\n- It runs only when codex-loop has decided to continue the task.\n- It does not run when there is no active loop, when the loop has completed, or when codex-loop cuts the loop short.\n- `command` is a shell-like string parsed to argv and executed without an implicit shell. Point it at a script, or explicitly use `bash -lc '...'`, if you need shell features such as pipes or redirects.\n- `cwd = \"session_cwd\"` runs from the same directory Codex reported in the `Stop` hook payload. This is the default.\n- `cwd = \"workspace_root\"` runs from the root codex-loop resolved from `.git` or `.codex`.\n- The command receives structured JSON on stdin.\n- The same JSON is available through `$INPUT_JSON` and `$INPUT_FILE`.\n- Only stdout is appended to the next continuation prompt under `pre_loop_continue output:`.\n- Stderr is not injected into the prompt. Failures and timeouts keep the loop running and append a short `pre_loop_continue warning:` instead.\n- `max_output_bytes` caps captured stdout before prompt injection.\n\n**Example config:**\n\n```toml\n# ~\u002F.codex\u002Fcodex-loop\u002Fconfig.toml or .\u002Fcodex-loop.toml\n[pre_loop_continue]\ncommand = \".codex\u002Fscripts\u002Floop-context.sh --format markdown --input $INPUT_FILE\"\ncwd = \"session_cwd\"\ntimeout_seconds = 30\nmax_output_bytes = 8000\n```\n\n**Example script:**\n\n```bash\n#!\u002Fusr\u002Fbin\u002Fenv bash\nset -euo pipefail\n\npayload=\"$(cat)\"\nsession_id=\"$(printf '%s' \"$payload\" | jq -r '.session_id')\"\nround=\"$(printf '%s' \"$payload\" | jq -r '.loop.continue_count')\"\n\nprintf 'Session: %s\\n' \"$session_id\"\nprintf 'Continuation round: %s\\n\\n' \"$round\"\n\nprintf 'Changed files:\\n'\ngit status --short\n\nprintf '\\nRecent test signal:\\n'\nif [ -f .codex\u002Flast-test.log ]; then\n  tail -n 40 .codex\u002Flast-test.log\nelse\n  printf 'No .codex\u002Flast-test.log found.\\n'\nfi\n```\n\nWith that config, every automatic continuation prompt will include the script stdout after codex-loop's normal continuation instructions. If the script exits non-zero or exceeds `timeout_seconds`, codex-loop still continues the loop and injects a short warning instead of the script output.\n\n## 🗑️ Uninstall\n\n```bash\ncodex-loop uninstall\n```\n\nThis removes only `~\u002F.codex\u002Fcodex-loop\u002F` and the managed skill copy at\n`~\u002F.codex\u002Fskills\u002Fcodex-loop\u002F` when it was created by codex-loop. It leaves\n`~\u002F.codex\u002Fconfig.toml` and Codex plugin install state unchanged. It also\nremoves only the `codex-loop`-managed hook registrations from\n`~\u002F.codex\u002Fhooks.json`, preserving unrelated user hooks and unmanaged skill\ndirectories.\n\n## 🛠️ Development\n\n```bash\nmake deps        # Tidy and verify modules\nmake verify      # Full pipeline: fmt → vet → lint → race tests → build\n```\n\nRelease tooling mirrors the project CI:\n\n```bash\nmake release-check       # Validate .goreleaser.yml with current GoReleaser v2 CLI\nmake release-snapshot    # Build local snapshot artifacts under dist\u002F (no publish\u002Fsign\u002FSBOM)\n```\n\n- GitHub Actions runs `make verify` on pushes and pull requests to `main`.\n- Pushing normal changes to `main` runs the release workflow in release-PR mode. It uses `github.com\u002Fcompozy\u002Freleasepr@v0.0.21` to calculate the next semantic version, generate `CHANGELOG.md`, generate the current `RELEASE_BODY.md`, update historical `RELEASE_NOTES.md`, sync the Codex plugin manifest version, and open or update a `release\u002FvX.Y.Z` pull request.\n- Release pull requests run CI plus a GoReleaser dry-run check before merge.\n- Merging a release pull request to `main` creates the `vX.Y.Z` tag and publishes the GitHub release through GoReleaser using `RELEASE_BODY.md`.\n- The release workflow requires a `RELEASE_TOKEN` secret with permission to push release branches\u002Ftags, open pull requests, and dispatch workflows.\n\nManual release notes can be staged before the release PR is generated:\n\n```bash\ngo run github.com\u002Fcompozy\u002Freleasepr@v0.0.21 add-note --title \"Short title\" --type feature\n```\n\nGenerated note files live in `.release-notes\u002F`. The release PR archives consumed notes under `.release-notes\u002Farchive\u002FvX.Y.Z\u002F` and keeps `.release-notes\u002F.gitkeep` in place for future notes.\n\n## 🔒 Privacy\n\n`codex-loop` itself does not send data to a network service. It reads Codex hook JSON from stdin, writes hook decisions to stdout, and stores loop state locally under `~\u002F.codex\u002Fcodex-loop\u002F`.\n\nGoal loops intentionally invoke the local `codex exec` command for default confirmation and interpretation, which uses the user's configured Codex provider\u002Fauth. The local JSONL log stores compact verdict metadata only; it does not store the full original task prompt, full assistant message, confirmation prompt, confirmation review text, interpreter prompt, or `pre_loop_continue` output.\n\n## 📄 License\n\n[MIT](LICENSE)\n","Codex Loop 是一个用于持续运行 Codex 任务直到满足特定时间、轮次或独立验证目标的本地优先 CLI 和插件。其核心功能包括三种循环模式（基于时间、轮次或目标确认），通过在提示首行添加结构化头部来激活循环，支持独立的目标确认机制，并提供预继续上下文钩子以携带最新本地环境信息。此外，它还集成了 Codex 生命周期，提供内置跟踪技能，确保任务状态可重启且有迭代记忆。该项目适合需要进行高质量QA测试、长时间稳定性和重复审查的应用场景。使用 Go 语言编写，保证了良好的性能与简洁性。",2,"2026-06-11 04:06:09","CREATED_QUERY"]