Skip to main content
command CX Codex

plan-loop — Claude Code command: planning and install

plan-loop — a planning-aware slash command runs recurring /loop checks against your plan files. Use it when phased work needs a regular progress tick.

MIT ★ 28,179 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files
Open on GitHub

What plan-loop does

plan-loop adds plan state to Claude Code’s /loop cadence. It accepts an interval such as 10m plus an optional task prompt, resolves the active plan, and sends the resulting prompt to /loop. With no custom prompt, the tick reads task_plan.md and progress.md, runs scripts/check-complete.sh, records progress when no update was made, and marks finished phases in the plan.

The command reports the interval and active plan ID after starting. Bare /loop uses Claude Code’s built-in maintenance prompt, while plan-loop keeps each tick tied to the planning files. Pair it with /plan-goal when the loop should stop after the plan is complete. It refuses to run without task_plan.md and directs you to /plan first. Available since v2.38.0.

What it helps with

  • check remaining plan phases on a schedule
  • record a progress update when work stalls
  • mark completed phases in task_plan.md
  • continue the next phase automatically
  • stop recurring work when the plan is complete

Example prompts for the agent

  • Run /plan-loop 10m and continue the active plan using task_plan.md and progress.md.
  • Run /plan-loop 5m to check unfinished phases and write a short update to progress.md when progress has stalled.
  • Use /plan-loop 10m with /plan-goal so the cadence ends when the plan is complete.

How to install plan-loop

1Plugin marketplace

/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-files

2Manually: put the files in place

.claude/commands/plan-loop.md

Call it with /plan-loop. For all projects use ~/.claude/commands/

Questions about plan-loop

How do I install plan-loop in Claude Code?

Run /plugin marketplace add OthmanAdi/planning-with-files, then /plugin install planning-with-files@planning-with-files. The command file is .claude/commands/plan-loop.md.

What does plan-loop do?

It gives /loop a planning context by rereading the plan files, running the completion check, and recording progress when needed.

What happens if task_plan.md is missing?

The command refuses to start and tells you to run /plan first.

Source text

plan-loop.md · MIT
---
description: "Run a planning-aware cadence with Claude Code's /loop. Default tick checks plan status, runs check-complete, nudges progress.md update if stalled. Available since v2.38.0."
disable-model-invocation: true
allowed-tools: "Read Bash"
---

Run a planning-aware cadence on top of Claude Code's `/loop` primitive.

Steps:

1. Parse args:
   - First arg matching `^\d+[smhd]$` is the interval (default `10m`).
   - Remaining args are an optional task prompt.
2. Resolve the active plan as in `/plan-attest`.
3. Compose the loop prompt:
   - If user passed a task prompt: use it verbatim.
   - Else: use the default planning tick prompt:
     ```
     Read task_plan.md and progress.md. Run scripts/check-complete.sh to see remaining phases.
     If no progress.md entry has been added since the last loop tick, write one summarizing the current state.
     If a phase finished, update its Status: line in task_plan.md.
     Continue the next phase if work remains.
     ```
4. Invoke `/loop <interval> <prompt>`.
5. Confirm to the user: print the interval, the active plan ID, and remind that bare `/loop` invocation alone (without args) runs Claude Code's built-in maintenance prompt — `/plan-loop` differs by always grounding the tick in the planning files.

If `task_plan.md` does not exist, refuse and direct user to run `/plan` first.

Why this exists:

`/loop` runs prompts on cron without any plan-state contract. `/plan-loop` injects a plan-aware default so the recurring tick always re-reads the planning files first, runs the completion check, and writes a progress entry. Users get "babysit my plan" UX without writing a custom loop prompt.

Notes:

- `/plan-loop` composes with `/loop`; it does not replace it. `/loop 5m "anything"` still works.
- For "babysit until plan is done" semantics: combine `/plan-loop 10m` (cadence) with `/plan-goal` (termination criterion). The loop runs every 10 minutes; the goal stops the loop when the plan is complete.
- The default tick prompt is intentionally short so it stays within compaction-safe length.

© OthmanAdi · MIT · OthmanAdi/planning-with-files

Similar slash commands

Slash commands catalog →

From the same set14

The whole set →
status Displays current task phases, completion percentage, and errors from task_plan.md. Runs when you need a quick status check without loading companion files into context. CX Codex +1 ★ 28,179repo stars plan-doctor The plan-doctor command for Claude Code checks planning-with-files plan lookup, injection, and attestation. Run it when hooks go silent or on a new machine. CX Codex +1 ★ 28,179repo stars plan-goal plan-goal builds a completion condition out of task_plan.md and feeds it to /goal, so the agent keeps moving through the whole plan. CX Codex +1 ★ 28,179repo stars plan-attest plan-attest locks the active task_plan.md file using a SHA-256 hash. Built-in hooks prevent plan injection into model prompts whenever the file content diverges from the attested hash. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files keeps a multi-step task plan in three markdown files and pulls the agent back to them every turn, so long sessions hold their context. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files saves agent task plans, research notes, and execution logs directly into project markdown files. Useful for multi-step tasks requiring 5 or more tool calls. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files — a skill for Claude Code and Codex that writes the task plan, research findings, and session log to disk as Markdown files. On the next run the agent reads those files and picks up from the last incomplete phase. CX Codex +1 ★ 28,179repo stars planning-with-files planning-with-files keeps the task plan in three markdown files on disk, so the agent resumes at the right phase after /clear, context compaction or a crash. CX Codex ★ 28,179repo stars

Project sponsors

Companies that keep this analytics open