# /loop — Local Recurring Task Scheduler (Boris-Style)

> Open-source slash command for recurring local Claude Code tasks with a 3-day safety cap. Inspired by Boris Cherny's /loop scheduler.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# /loop — Local Recurring Task Scheduler (Boris-Style)

## Quick Use

1. Save the file below to `.claude/commands/loop.md`.
2. Restart Claude Code (or `/commands reload`).
3. Schedule a recurring task (max 3 days, safety cap):
   ```
   /loop 1h "Run sentry-errors triage and post results to #engineering"
   ```
4. Stop a running loop:
   ```
   /loop-stop <task-id>
   ```

> Inspired by Boris Cherny's `/loop` slash command on howborisusesclaudecode.com — Boris's variant has a 3-day safety cap to prevent runaway scheduling.

---

## Intro

`/loop` is Boris Cherny's recurring-task pattern: instead of scheduling Cron jobs that outlive their usefulness, you fire-and-forget a Claude task with a hard 3-day cap. Boris uses it for short-horizon things — "run my morning triage every day for the next sprint", "ping me when this PR gets a review", "check the deploy every 5 minutes during a high-risk push."

The 3-day cap is the load-bearing constraint. Open-ended cron jobs accumulate as cruft; capped loops self-clean.

Works with: Claude Code 1.x. Persists state at `~/.claude/loops/<task-id>/`.

---

## How /loop Works

Save to `.claude/commands/loop.md`:

```markdown
---
description: Schedule a recurring Claude task with a 3-day safety cap
argument-hint: <interval> "<prompt>" [--end <ISO date>]
---

You will register a recurring task. Default cap: 3 days from now.

1. Parse `$ARGUMENTS`:
   - First token: interval (`5m`, `1h`, `1d`)
   - Second token (quoted): the prompt to fire each tick
   - Optional `--end <ISO>` to set a custom end (still capped at +3 days from now)

2. Generate a task-id (short hash from interval + prompt + now).

3. Write `~/.claude/loops/<task-id>/spec.json`:
   ```json
   {
     "interval": "<parsed>",
     "prompt": "<text>",
     "created_at": "<ISO>",
     "ends_at": "<ISO + 3d or user-supplied, whichever sooner>",
     "ticks": []
   }
   ```

4. Use `ScheduleWakeup` (or platform equivalent: launchd / systemd / cron) to fire the task at the next interval.

5. Each tick:
   - Read spec.json. If `now > ends_at`, mark `status: completed` and stop.
   - Run the prompt as a fresh Claude session.
   - Append result to `ticks` array (truncate to last 100 to avoid disk bloat).
   - Schedule next tick.

6. Output: `Loop registered. ID: <task-id>. Next fire: <ISO>. Cap: <ends_at>.`

## Companion command

Save to `.claude/commands/loop-stop.md`:

```markdown
---
description: Stop a running /loop by id
argument-hint: <task-id>
---

Read `~/.claude/loops/$ARGUMENTS/spec.json`. Set status=cancelled. Cancel the next ScheduleWakeup. Print confirmation.
```

## Boundaries

- Hard cap: 3 days. Never extend beyond +3d from now.
- One loop per task-id; do not overwrite existing.
- Never persist secrets in spec.json — the prompt is plaintext.
- /loop-list shows active loops; /loop-stop cancels.
```

### How it differs from Claude Code's native /loop

Claude Code 1.x has a built-in `/loop` skill that lets you self-pace iterations. Boris's variant adds:
- Hard 3-day cap (native /loop has no cap)
- On-disk spec.json for cross-session persistence
- Companion `/loop-list` and `/loop-stop` for management
- Safety: refuses to overwrite an existing task-id

If both exist, Boris's `.claude/commands/loop.md` overrides the native skill (file-based commands take priority).

---

## Example session

```
You:    "/loop 1h 'Run sentry-errors and DM me if any P0 surfaces'"
Claude: -> registered task abc1234
        -> Next fire: 2026-04-28T14:00:00Z
        -> Cap: 2026-05-01T13:00:00Z (3 days)
[1h later, automatically]
Claude: -> tick 1: sentry-errors found 0 P0 → no DM sent
[continues every hour for ≤72 ticks]
You:    "/loop-stop abc1234"
Claude: -> cancelled. 8 ticks fired. Final state archived.
```

---

## FAQ

**Q: Why a 3-day cap?**
A: Open-ended schedules become forgotten cruft. 3 days covers most real workflows (deploy watch, sprint triage); longer needs deserve a real cron job.

**Q: How is it different from native /loop?**
A: See "How it differs" section. Hard cap + on-disk persistence + companion commands.

**Q: What happens if my machine sleeps?**
A: Missed ticks are skipped (not queued up). Next fire is on next wake. This is intentional — backlog firing causes thundering herds.

**Q: Can I run multiple loops?**
A: Yes — each gets its own task-id. /loop-list to see all active.

**Q: Is this Boris's actual /loop?**
A: No — community-written. Boris's private command file is not open-sourced.

---

## Source & Thanks

> Inspired by Boris Cherny's `/loop` slash command (3-day-capped variant) on howborisusesclaudecode.com.

Citations:
- howborisusesclaudecode.com
- Pragmatic Engineer: https://newsletter.pragmaticengineer.com/p/building-claude-code-with-boris-cherny

<!-- ZH -->

## 快速使用

1. 落 `.claude/commands/loop.md` + `/loop-stop.md`
2. `/commands reload`
3. 起一个循环：`/loop 1h "跑 sentry-errors，有 P0 就给我发 DM"` —— 自动每小时跑，最多跑 3 天。
4. 停：`/loop-stop <task-id>`

## 与原生 /loop 的差别

- 硬性 3 天封顶（原生没有）
- spec.json 落盘，跨 session 持久
- 配套 /loop-list / /loop-stop 管理
- 文件版命令优先级高于原生 skill，会自动覆盖


---
Source: https://tokrepo.com/en/workflows/loop-local-recurring-task-scheduler-5f9f565c
Author: Skill Factory