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
/plugin marketplace add OthmanAdi/planning-with-files
/plugin install planning-with-files@planning-with-filesWhat 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 10mand continue the active plan usingtask_plan.mdandprogress.md. - Run
/plan-loop 5mto check unfinished phases and write a short update toprogress.mdwhen progress has stalled. - Use
/plan-loop 10mwith/plan-goalso 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-files2Manually: put the files in place
.claude/commands/plan-loop.mdCall it with /plan-loop. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/plan-loop.mdCall it with /prompts:plan-loop. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/plan-loop.prompt.mdManually: put the files in place
.gemini/commands/plan-loop.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
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