compozy
An operating system for AI agents. The autonomous control plane for your agents: see and steer every Claude Code, Codex, and Cursor session. Always-on agents check in on their own, and you step in only when one needs you.
- 2.9k
- Go
- MIT
- 5 h ago
Keep Codex tasks running until they meet a time or round-based completion target.
Repo compozy/codex-loop, read from GitHub 14 min ago. compozy has not joined Take My Repo.
compozy/codex-loop is a public repo on GitHub by compozy. Keep Codex tasks running until they meet a time or round-based completion target. It declares the MIT license on GitHub. It is written mainly in Go, has 36 stars and last changed on 2026-05-13. Nobody has reviewed it on Take My Repo yet, which says nothing about its quality. Read from GitHub on 2026-11-22.
In the maintainer's words. Shown from GitHub; Take My Repo does not keep a copy.
Keep Codex tasks running until they actually finish — by time, rounds, or independently confirmed goal.
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.
It 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.
min="6h"), deliberate round count (rounds="3"), or independently confirmed goal (goal="ship only after verification").[[CODEX_LOOP ...]] header, so day-to-day Codex use is untouched.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.codex-loop skill can bootstrap .codex/loop/<name>/ artifacts for restart-safe task state, per-iteration memory, validation evidence, and final completion signatures.UserPromptSubmit and Stop hooks, and mirrors managed registrations into ~/.codex/hooks.json for current Codex builds.~/.codex/codex-loop/, isolated by Codex session_id. Compact verdict metadata lands in ~/.codex/codex-loop/runs.jsonl.codex-loop upgrade release download path. User-configured continuation and goal commands run as external tools.go install github.com/compozy/codex-loop/cmd/codex-loop@latest
codex-loop install
For an exact release:
go install github.com/compozy/codex-loop/cmd/codex-loop@v0.1.1
codex-loop install
codex plugin marketplace add compozy/codex-loop --ref v0.1.1
codex plugin marketplace upgrade codex-loop-plugins
For an existing install, codex-loop can perform the release download, checksum verification, managed runtime refresh, and Codex marketplace refresh in one command:
codex-loop upgrade # latest GitHub release
codex-loop upgrade --version v0.1.1
codex-loop install creates or updates:
~/.codex/codex-loop/bin/codex-loop~/.codex/codex-loop/loops/~/.codex/codex-loop/config.toml~/.codex/skills/codex-loop/ with the managed built-in tracking skill~/.codex/hooks.json with managed UserPromptSubmit and Stop hook registrations~/.codex/config.toml with features.codex_hooks = trueRegister this repo as a Codex plugin marketplace:
codex plugin marketplace add compozy/codex-loop
For local development from this checkout:
codex plugin marketplace add /path/to/codex-loop
Then restart Codex, open the plugin directory, and install codex-loop from the Codex Loop Plugins marketplace.
The plugin contributes lifecycle hooks from plugins/codex-loop/hooks/hooks.json. codex-loop install mirrors the same managed hook commands into ~/.codex/hooks.json so current Codex builds execute them reliably while preserving unrelated user hooks.
The activation header must be the first line of the prompt. The task prompt starts on the line after the header.
[[CODEX_LOOP name="release-stress-qa" min="6h"]]
Run release-grade QA for this repository and keep expanding scope until the minimum duration is met.
[[CODEX_LOOP name="release-stress-qa" rounds="3"]]
Run three deliberate QA passes for this repository and treat each stop as the end of one round.
[[CODEX_LOOP name="release-stress-qa" goal="ship only after real verification"]]
Run release-grade QA for this repository and keep going until the work is actually complete.
[[CODEX_LOOP name="release-stress-qa" goal="ship only after real verification" confirm_model="gpt-5.5" confirm_reasoning_effort="xhigh"]]
Run release-grade QA for this repository and keep going until the work is actually complete.
| Field | Required | Notes |
|---|---|---|
name |
yes | Loop identifier |
min |
one of | Duration: 30m, 30min, 1h 30m, 2 hours, 45sec, etc. |
rounds |
one of | Positive integer |
goal |
one of | Free-form verification goal; goal="" reuses the task prompt as the goal |
confirm_model |
only with goal |
Model for the goal confirmation run |
confirm_reasoning_effort |
only with goal |
One of minimal, low, medium, high, xhigh |
Loop state is isolated by Codex session_id. Exactly one limiter — min, rounds, or goal — is required.
codex-loop install
codex-loop upgrade
codex-loop upgrade --version v0.1.1
codex-loop status
codex-loop status --all
codex-loop status --session-id <id>
codex-loop status --workspace-root <path>
codex-loop uninstall
codex-loop version
status prints JSON. By default it shows only active loops; use --all to include completed, superseded, and cut-short loops.
The global runtime config lives at ~/.codex/codex-loop/config.toml and supports:
optional_skill_name = "codex-loop"
optional_skill_path = ""
extra_continuation_guidance = ""
[hooks]
stop_timeout_seconds = 2700
[goal]
confirm_model = "gpt-5.5"
confirm_reasoning_effort = "high"
confirm_command = "codex exec --cd $WORKSPACE_ROOT --ephemeral --yolo --output-last-message $CONFIRM_OUTPUT_PATH $MODEL_ARGV $REASONING_ARGV --skip-git-repo-check -"
timeout_seconds = 2400
interpret_model = "gpt-5.4-mini"
interpret_reasoning_effort = "low"
interpret_timeout_seconds = 120
max_output_bytes = 12000
[pre_loop_continue]
command = ""
cwd = "session_cwd"
timeout_seconds = 60
max_output_bytes = 12000
optional_skill_name = "codex-loop" is the default installed behavior, so automatic continuations name the managed built-in tracking skill.optional_skill_name to another non-empty skill name to override the built-in tracking skill.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.extra_continuation_guidance appends extra text to every automatic continuation.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.Projects 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.
Project config overlays the global config by field:
defaults -> global ~/.codex/codex-loop/config.toml -> project codex-loop.toml.codex-loop.toml override the global value.codex-loop.toml inherit the global value or default.command = "" in project [pre_loop_continue] disables a global pre-loop command for that project.[hooks].stop_timeout_seconds remains an install-time global setting. Local project config does not rewrite installed Codex hook registrations.Project-local example:
# ./codex-loop.toml
optional_skill_name = "codex-loop"
extra_continuation_guidance = "Resume from .codex/loop/<name>/state.json and run one tracked action before stopping."
[pre_loop_continue]
command = ".codex/scripts/loop-context.sh --input $INPUT_FILE"
cwd = "workspace_root"
timeout_seconds = 30
max_output_bytes = 8000
The plugin ships a codex-loop skill with two lanes. codex-loop install
copies that skill into ${CODEX_HOME:-$HOME/.codex}/skills/codex-loop/ so
the name-only default optional_skill_name = "codex-loop" resolves as a
normal Codex skill instead of depending on a plugin cache path.
Tracked execution stores project-local artifacts under:
.codex/loop/<name>/
request.md
state.json
tasks/task-001.md
memory/MEMORY.md
memory/iter-001.md
To use it explicitly, include the skill in the prompt:
[[CODEX_LOOP name="release-stress-qa" goal="complete tracked QA with all tasks done, blockers closed, and verification PASS"]]
Use the codex-loop skill. Track the work under .codex/loop/release-stress-qa/.
codex-loop install creates new runtime configs with
optional_skill_name = "codex-loop" and migrates missing or blank
optional_skill_name values to that default. Non-empty custom skill names are
preserved. The managed skill copy is refreshed on every install. If
~/.codex/skills/codex-loop/ already exists without the codex-loop management
marker, install stops instead of overwriting it.
Goal 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.
The 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.
The 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.
Runtime behavior:
confirm_command is a shell-like string parsed to argv and executed without an implicit shell.--yolo, --ephemeral, and --output-last-message; it does not receive an output schema.$CONFIRM_OUTPUT_PATH or stdout.codex exec and produces the structured verdict internally.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.goal.max_output_bytes caps captured confirmation and interpreter output used for prompts and diagnostics.~/.codex/codex-loop/runs.jsonl.Confirmation command variables:
$PROMPT, $PROMPT_FILE, and $CONFIRM_OUTPUT_PATH expose the reviewer prompt and plain-text output file.$MODEL_ARGV expands to --model <model> when a model is configured; $REASONING_ARGV expands to --config model_reasoning_effort="<effort>" when reasoning is configured.$MODEL, $REASONING_EFFORT, $WORKSPACE_ROOT, $CWD, $SESSION_ID, $LOOP_NAME, $LOOP_SLUG, $RUNS_LOG_PATH, and $CODEX_HOME are also available.CODEX_LOOP_CONFIRM_ prefix.Custom runner example:
[goal]
confirm_model = "opus"
confirm_reasoning_effort = ""
confirm_command = "compozy exec --ide claude --model $MODEL $PROMPT"
pre_loop_continuepre_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.
Use 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.
Runtime behavior:
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.cwd = "session_cwd" runs from the same directory Codex reported in the Stop hook payload. This is the default.cwd = "workspace_root" runs from the root codex-loop resolved from .git or .codex.$INPUT_JSON and $INPUT_FILE.pre_loop_continue output:.pre_loop_continue warning: instead.max_output_bytes caps captured stdout before prompt injection.Example config:
# ~/.codex/codex-loop/config.toml or ./codex-loop.toml
[pre_loop_continue]
command = ".codex/scripts/loop-context.sh --format markdown --input $INPUT_FILE"
cwd = "session_cwd"
timeout_seconds = 30
max_output_bytes = 8000
Example script:
#!/usr/bin/env bash
set -euo pipefail
payload="$(cat)"
session_id="$(printf '%s' "$payload" | jq -r '.session_id')"
round="$(printf '%s' "$payload" | jq -r '.loop.continue_count')"
printf 'Session: %s\n' "$session_id"
printf 'Continuation round: %s\n\n' "$round"
printf 'Changed files:\n'
git status --short
printf '\nRecent test signal:\n'
if [ -f .codex/last-test.log ]; then
tail -n 40 .codex/last-test.log
else
printf 'No .codex/last-test.log found.\n'
fi
With 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.
codex-loop uninstall
This removes only ~/.codex/codex-loop/ and the managed skill copy at
~/.codex/skills/codex-loop/ when it was created by codex-loop. It leaves
~/.codex/config.toml and Codex plugin install state unchanged. It also
removes only the codex-loop-managed hook registrations from
~/.codex/hooks.json, preserving unrelated user hooks and unmanaged skill
directories.
make deps # Tidy and verify modules
make verify # Full pipeline: fmt → vet → lint → race tests → build
Release tooling mirrors the project CI:
make release-check # Validate .goreleaser.yml with current GoReleaser v2 CLI
make release-snapshot # Build local snapshot artifacts under dist/ (no publish/sign/SBOM)
make verify on pushes and pull requests to main.main runs the release workflow in release-PR mode. It uses github.com/compozy/releasepr@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/vX.Y.Z pull request.main creates the vX.Y.Z tag and publishes the GitHub release through GoReleaser using RELEASE_BODY.md.RELEASE_TOKEN secret with permission to push release branches/tags, open pull requests, and dispatch workflows.Manual release notes can be staged before the release PR is generated:
go run github.com/compozy/releasepr@v0.0.21 add-note --title "Short title" --type feature
Generated note files live in .release-notes/. The release PR archives consumed notes under .release-notes/archive/vX.Y.Z/ and keeps .release-notes/.gitkeep in place for future notes.
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 ~/.codex/codex-loop/.
Goal loops intentionally invoke the local codex exec command for default confirmation and interpretation, which uses the user's configured Codex provider/auth. 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.
compozy/codex-loop is a public repo on GitHub by compozy. Keep Codex tasks running until they meet a time or round-based completion target.
It declares the MIT license on GitHub.
Its maker has not tagged a system, so it is unknown here. Its README says what it needs.
Open "Take it" on its page: Take My Repo writes an install plan for your machine and hands it to your AI agent (Claude Code, Codex or Cursor), which asks you before each step. Take My Repo has not tested it on any machine.
Its last change on GitHub was on 2026-05-13. Take My Repo does not judge from that whether it is maintained.
Nobody has reviewed it on Take My Repo yet, which says nothing about its quality.

An operating system for AI agents. The autonomous control plane for your agents: see and steer every Claude Code, Codex, and Cursor session. Always-on agents check in on their own, and you step in only when one needs you.

An open workplace for AI agents — local-first runtime with durable sessions and agent-to-agent networking.

Version your spec artifacts — PRDs, tech specs, ADRs, AI plans — in a sidecar Git repository, without polluting your main PRs.

Context-pruning proxy for Claude Code and Codex: Jev judges which history is still needed, measured not claimed. POC here now, heading soon into https://github.com/compozy/compozy