Skip to content
Skills Library
AI & agents · Automation

loop

/loop

Run a Codex prompt repeatedly on a fixed interval. Use for "/loop", "run this every N minutes/hours", "poll X every 5 minutes", "repeat this Codex prompt", or any recurring interval-based Codex job. This is the interval-repeat companion to the separate `schedule` skill (cron / specific-time). For a durable, always-on alternative that survives reboots and terminal exits, prefer Codex app Automations; this local CLI is a terminal fallback that only fires while its daemon process is running.

Licence
MIT
Last repository change
24.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/loop.mjs, scripts/loop.test.mjs

What it does and when to use it

Run a Codex prompt repeatedly on a fixed interval. Use for "/loop", "run this every N minutes/hours", "poll X every 5 minutes", "repeat this Codex prompt", or any recurring interval-based Codex job. This is the interval-repeat companion to the separate `schedule` skill (cron / specific-time). For a durable, always-on alternative that survives reboots and terminal exits, prefer Codex app Automations; this local CLI is a terminal fallback that only fires while its daemon process is running.

Triggers from the description

run this every N minutes/hourspoll X every 5 minutesrepeat this Codex prompt
Original author description

Run a Codex prompt repeatedly on a fixed interval. Use for "/loop", "run this every N minutes/hours", "poll X every 5 minutes", "repeat this Codex prompt", or any recurring interval-based Codex job. This is the interval-repeat companion to the separate `schedule` skill (cron / specific-time). For a durable, always-on alternative that survives reboots and terminal exits, prefer Codex app Automations; this local CLI is a terminal fallback that only fires while its daemon process is running.

How it works

  1. Overview
  2. Durable Always-On: Use Automations First
  3. Local Fallback Usage
  4. Daemon Requirement
  5. Run Evidence
  6. Safety Defaults
  7. Reference
Original SKILL.md headings · 94 lines, 632 words
SKILL.md preview
---
name: loop
description: Run a Codex prompt repeatedly on a fixed interval. Use for "/loop", "run this every N minutes/hours", "poll X every 5 minutes", "repeat this Codex prompt", or any recurring interval-based Codex job. This is the interval-repeat companion to the separate `schedule` skill (cron / specific-time). For a durable, always-on alternative that survives reboots and terminal exits, prefer Codex app Automations; this local CLI is a terminal fallback that only fires while its daemon process is running.
---

## Overview

`loop.mjs` is a dependency-free Node ESM runner that registers and fires `codex exec` jobs on a **fixed interval**. It manages task state in `.codex/loop/` and exposes 8 subcommands: `parse-loop`, `add`, `list`, `cancel`, `status`, `run-due`, `daemon`, `doctor`.

It supports only the interval-repeat (`loop`) task kind. For cron schedules or a one-shot run at a specific time, use the separate `schedule` skill instead.

## Durable Always-On: Use Automations First

**Codex app Automations** is the official, always-on surface for durable recurring runs — recommend it first. It persists across reboots and terminal exits without a running process.

The bundled local CLI is a **terminal fallback only**: nothing fires unless the `daemon` process is running. It is NOT an OS service and does not survive terminal exits.

## Local Fallback Usage

All state-mutating commands require `--state-root <dir>`. Conventional path: `--state-root .codex/loop`.

### Add a loop task

User says `/loop 1m check CI status`:

```sh
node scripts/loop.mjs add \
  --state-root .codex/loop \
  --interval 1m \
  --prompt "check CI status" \
  --cwd "$PWD"
```

- `add` is loop-only: `--kind` is optional and, if given, must be `loop`.
- `parse-loop` validates a `/loop [interval] <prompt>` spec and returns JSON without writing state.
- Default interval when omitted: 10m. Units: `s` (rounds up to nearest minute, min 1m), `m`, `h`, `d`.
- Optional `--next-run-at <ISO>` overrides the first computed run time (testing/backfill).

### Manage tasks

```sh
# list all tasks (append --json for machine-readable output)
node scripts/loop.mjs list --state-root .codex/loop

# cancel one task
node scripts/loop.mjs cancel <id> --state-root .codex/loop

# cancel all active tasks
node scripts/loop.mjs cancel --all --state-root .codex/loop

# show task counts and lock state (append --json for JSON output)
node scripts/loop.mjs status --state-root .codex/loop
```

### Start the runner

```sh
node scripts/loop.mjs daemon \
  --state-root .codex/loop \
  [--poll-ms 5000]       # check interval in ms, default 5000
  [--once]               # run one poll pass then exit
  [--max-runs N]         # exit after N total task fires
  [--codex-bin /path/to/codex]
```

The daemon holds a **single-runner lock** (`scheduled_tasks.lock/`). A second daemon against the same state root fails while the first is alive and reclaims only a provably stale lock (dead PID).

`run-due` does one on-demand due-check pass without occupying the daemon lock continuously — useful for CI triggers or manual testing. It accepts the same `--codex-bin` and repeatable `--codex-arg` flags.

### Verify setup

```sh
node scripts/loop.mjs doctor --state-root .codex/loop
```

Checks state-root writeability, task count, lock state, and codex binary reachability. It is read-only and never creates the state root.

## Daemon Requirement

**Nothing fires unless `daemon` (or `run-due`) is running.** Keep the daemon in a persistent terminal or tmux session. It exits cleanly on SIGINT/SIGTERM, releasing the lock.

After each run, a loop task's next run is recomputed as `finishedAt + intervalMs`, so the interval is measured from run completion and never drifts.

## Run Evidence

Each task run is recorded under `.codex/loop/runs/<taskId>/` with timestamped `.jsonl` (full codex stdout), `.last.txt` (last Codex message), and optionally `.stderr.txt` files.

## Safety Defaults

- `--codex-arg` pass-through uses a **default-deny allowlist**: only a small, vetted set of flags that cannot weaken the sandbox, approval policy, or config is permitted — currently `--model`/`-m` (with its value). Every other flag is rejected with a `ValidationError` naming the arg. This explicitly rejects sandbox/approval/config overrides such as `--sandbox`/`-s danger-full-access`, `--config`/`-c ...`, `--ask-for-approval`/`-a never`, `--full-auto`, `--profile`, `--dangerously-bypass-approvals-and-sandbox`, and `--yolo` (in both space- and `=`-joined forms). Args are additionally constrained to the `[-A-Za-z0-9_.,:=/@+]` character set.
- Allowed pass-through args are inserted **before** the `-` stdin sentinel so codex parses them as flags and still reads the prompt from stdin.
- The script never emits approval- or sandbox-bypassing flags to `codex exec`.
- Does not install OS cron, launchd, or any system service.

## Reference

Read `references/loop-contract.md` for the full state/lock schema, interval grammar specification, and complete per-command contracts.
Files in this package (5)
  • SKILL.md 5 KB
  • agents/openai.yaml 1 KB
  • references/loop-contract.md 19 KB
  • scripts/loop.mjs 31 KB
  • scripts/loop.test.mjs 21 KB

Versions

RepositoryScoreLicence
This page · Mineru98/skills-store100MIT
mickeyyaya/evolve-loop100Apache-2.0
relai-ai/agent-eval-loop100Apache-2.0
SethGammon/Citadel100MIT
alirezarezvani/claude-skills100MIT
x-cmd/x-cmd100Apache-2.0
in-the-loop-labs/pair-review100Apache-2.0
railly/skills100MIT
slogsdon/loop-and-gate-foundation100MIT

Database snapshot: 13.11.2026 · package version 096550c1aa40 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90scheduler
    Use when user wants to schedule tasks for future, recurring, or interval execution. Manages one-time, cron, and interval tasks dispatched via C4 comm-bridge.
  • 100companion-automations
    Create, update, delete, enable, disable, run, stop, and inspect Gentle Companion automations with the companion_automation tool. Use for recurring repository tasks, scheduled agent work, and automation run history.
  • 100codex-exec
    Run one prompt through headless Codex and capture the result. Use when: wanting a one-shot `codex exec` run or CI step. Not for batches or retries.
  • 100codex-automation-architect
    Use when designing, reviewing, or updating Codex app automations, cron jobs, scheduled tasks, recurring runs, or heartbeat follow-ups.
  • 100codex
    Run tasks on OpenAI Codex through the local Codex app-server daemon — pick a role or model, run several in the background, answer Codex's questions, resume a thread by id, or run Codex's built-in review. Use whenever you need to call Codex.
  • 100loop-goal
    Discipline rules for long-running agent tasks — recurring loops and run-until-done goals. Use when about to run a task that repeats on an interval or runs until a completion criterion is met. Trigger phrases (English or Chinese) — "loop", "goal", "keep running", "run in a loop",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.