You can read the blog free from here
Most Claude workflows still start as manual prompting: you write the prompt, wait for the answer, inspect the result, and decide what to ask next. That works for one-off tasks, but it becomes inefficient when the work is repetitive, stateful, or needs several rounds of checking. At that point, the better abstraction is not a better prompt. It is a loop.
A Claude loop is a repeatable workflow around the model. It defines what triggers the run, what context Claude should read, what it is allowed to do, how the output is verified, where the state is stored, and when the loop should stop, repeat, or escalate to a human. The model still performs the reasoning and tool use, but the loop provides the operating structure.
In this guide, we will build the idea gradually. We will start with a minimum viable Claude loop using TASK.md, LOOP_INSTRUCTIONS.md, PROGRESS.md, and an outputs/ folder.
Then we will add verification, persistent state, scheduled execution with /loop, safer permission boundaries, and optional connectors. The goal is not to make Claude fully autonomous from the beginning. The goal is to design a controlled workflow that can iterate, verify, remember, and become more useful over time.
Table of Contents:
- What a Claude Loop Actually Is
- When You Should — and Should Not — Build a Loop
- The Minimum Viable Claude Loop
- Adding Persistent State with PROGRESS.md
- Verification: Separating the Worker from the Checker
- Scheduling the Loop with /loop
- Adding Tools, Connectors, and Safer Permissions
- Complete Walkthrough: Building Your First Claude Loop
I explained the complete framework through practical, hands-on examples in my latest course, Hands-On Loop Engineering with Claude.
The course includes 9 lessons, along with:
- An 117-page companion book, How to Create Loops with Claude Code
- Three complete, runnable loop projects, including an event-triggered loop that monitors a GitHub repository and reports only when the branch head actually changes
- The complete 247-slide presentation course deck
The course takes you from the core concepts behind loop engineering to building reliable, persistent, and verifiable workflows with Claude.
1. What a Claude Loop Actually Is
Most people start with Claude by writing prompts manually. They describe a task, provide some context, wait for the response, review the result, and then decide what to ask next. This works well for one-off tasks, but it does not scale when the work is repetitive, stateful, or needs several rounds of checking and refinement.
A Claude loop changes the control structure around the model. Instead of you manually prompting Claude at every step, you design a small system that gives Claude a goal, provides the right context, lets it act, checks the result, records progress, and decides whether another iteration is needed. The important shift is not that Claude becomes fully autonomous. The shift is that the prompting process itself becomes part of the system.
At the simplest level, a loop has six parts:
- Trigger — something starts the loop, such as a manual command, schedule, file change, Git event, or failed CI run.
- Context — Claude reads the task description, relevant files, project instructions, and previous progress.
- Action — Claude performs the next step, such as writing a report, editing a file, drafting a fix, or classifying failures.
- Verification — the result is checked against a concrete condition, such as a checklist, test suite, linter, schema, or expected output format.
- State update — the loop records what happened, what changed, what failed, and what should happen next.
- Decision — the loop either stops, asks for human review, or runs another iteration.
A useful way to think about a Claude loop is that Claude remains the reasoning and execution engine, while the loop provides the operating structure around it. The loop decides when Claude runs, what Claude reads before acting, what Claude is allowed to change, how the output is checked, and what information survives after the session ends.
This last part is important. Claude sessions are temporary. A loop needs a persistent state outside the model if it is going to continue across multiple runs. That state can be a markdown file, a task board, a database entry, a GitHub issue, or any other durable record. In the simplest version, it is just a file called PROGRESS.md.
A Claude loop is not just "ask Claude again." It is a repeatable workflow around Claude: trigger, context, action, verification, state update, and decision. The model performs the work, but the loop controls how the work continues.
For example, imagine a daily project review loop. Every morning, Claude opens a project folder, reads TASK.md and PROGRESS.md, checks what changed since the previous run, writes a short report, updates the progress file, and stops. You are not asking Claude from scratch each day. The loop gives Claude the same operating procedure every time and lets the state file carry information across runs.
A minimal folder for this kind of loop might look like this:
project-review-loop/
├── TASK.md
├── PROGRESS.md
├── LOOP_INSTRUCTIONS.md
└── outputs/
└── daily-review.mdTASK.md defines the purpose of the loop. PROGRESS.md stores what happened in previous runs. LOOP_INSTRUCTIONS.md tells Claude how to behave during each iteration. The outputs/ folder gives the loop a predictable place to write results.
The first version does not need connectors, sub-agents, worktrees, or complex automation. It only needs one constrained task and one reliable place to store progress. Once that works manually, you can add scheduling, verification, permissions, and tool access later.
The reason this pattern matters is that it changes the unit of work. With manual prompting, the unit of work is a single prompt-response interaction. With loops, the unit of work becomes a recurring process. You are no longer only designing what Claude should answer. You are designing how Claude should keep working toward a goal over time.
The simplest reliable loop should be deliberately small. It should read context, do one constrained job, write the result somewhere predictable, update state, and stop. More autonomy can be added later, but the first objective is repeatability.
This is also why loops are different from ordinary scripts. A script usually follows fixed instructions. A Claude loop can inspect the current state of a project, reason about what changed, decide which step is appropriate, and produce a new output based on the current situation. The loop provides structure, while Claude provides adaptive reasoning inside that structure.
However, that flexibility is also what makes loops risky if they are designed poorly. A loop with no state forgets what happened before. A loop with no verification trusts its own output too easily. A loop with no stop condition can waste time, tokens, and sometimes modify things it should not touch. The technical value of loop engineering is not simply making Claude run repeatedly. It is designing the boundaries that make repeated execution useful and safe.
Loop engineering is the practice of designing those boundaries: what starts the loop, what Claude can access, what Claude can change, how progress is recorded, how results are verified, and when a human must review the output.
In the next sections, we will build this idea gradually. Before creating a loop, we need to decide whether the task deserves one at all. Not every task should become an automation. Some work is too vague, too rare, too expensive, or too dependent on human judgment. A good Claude loop starts with the right task selection.
2. When You Should — and Should Not — Build a Loop
Before building a Claude loop, it is worth asking whether the task actually needs one. A loop adds structure, persistence, verification, and automation, but it also adds cost and operational complexity. For many tasks, a single well-written prompt is still the better option.
A loop is useful when the task is repetitive, stateful, and checkable. Repetitive means the task happens often enough that automation is worth the setup. Stateful means each run benefits from remembering what happened in previous runs. Checkable means there is some concrete way to decide whether the output is acceptable.
For example, a daily project review loop is a good candidate. The task happens repeatedly, the loop needs to remember previous progress, and the output can be checked against a simple structure: files reviewed, changes summarized, blockers listed, and PROGRESS.md updated. A one-time brainstorming session, on the other hand, is usually not a good candidate. It may be valuable, but it does not need persistent automation.
A Claude loop is most useful when the task repeats, the output can be checked, and the next run benefits from what happened in the previous run. Without those three conditions, a loop often becomes a more expensive version of a normal prompt.
A practical way to evaluate a task is to run a simple loop-readiness check.
The Loop Readiness Check
Before turning a task into a Claude loop, ask five questions:
- Does this task repeat? If the task does not happen regularly, the setup cost may not be worth it. A loop works best when it runs daily, weekly, on every pull request, after every meeting, or after a specific recurring event.
- Can the result be verified? The loop needs a way to reject bad output. In code workflows, this might be a test suite, type checker, linter, or build command. In document workflows, it might be a checklist, required output format, naming convention, or review rule.
- Does Claude have enough context to act? The loop should have access to the files, instructions, logs, tickets, documents, or connectors needed to complete the task. If Claude cannot inspect the relevant environment, the loop will operate from an incomplete context.
- Is there a clear stop condition? The loop must know when to stop, repeat, or escalate. "Continue until it looks good" is too vague. Better stop conditions include "the output file exists," "all required sections are filled," "tests pass," or "the issue is marked for human review."
- Is there a safe review point? Any loop that can modify files, open pull requests, send messages, update tickets, or touch external systems should have a human checkpoint at the beginning. Automation should start with drafts and reports before moving toward direct action.
This checklist is useful because many loop ideas fail before implementation. The problem is not Claude's capability. The problem is that the task has no stable trigger, no reliable verification step, or no clear definition of done.
Consider the difference between these two examples:
- Bad loop candidate: Every day, improve the product strategy document until it feels stronger.
This is vague. The loop has no objective stop condition and no clear verification signal. The output depends heavily on judgment. Claude may generate useful suggestions, but the process should remain human-led.
A better version would be:
- Better loop candidate: Every Friday, review the product strategy document, identify sections that changed during the week, list unresolved assumptions, and write a structured review note to outputs/strategy-review.md. Do not edit the strategy document directly.
This version is more suitable for a loop because it has a schedule, a limited scope, a predictable output file, and a safer permission boundary. Claude is not asked to make strategic decisions automatically. It is asked to inspect, summarize, and prepare material for human review.
Good First Loops
The best first loops are small and low-risk. They should produce outputs that are easy to inspect and safe to ignore if they are wrong. A useful first loop should usually write a report, update a state file, or draft a recommendation. It should not make irreversible changes.
Good first loop examples include:
Example #1: Daily project review:
Read the project folder every morning, summarize what changed, identify blockers, update PROGRESS.md, and write a report to outputs/daily-review.md.
Example #2: Meeting follow-up loop:
After a meeting notes file is added, extract action items, owners, deadlines, and unresolved questions into outputs/follow-up.md.
Example #3: Folder cleanup planning loop:
Inspect a messy folder, classify files by type, propose a cleanup plan, and write the plan to outputs/cleanup-plan.md. Do not move or rename files yet.
Example #4:CI failure triage loop:
When CI fails, read the logs, classify the failure, identify likely causes, and draft a report. Do not change code until a human approves the suggested fix.These tasks are good starting points because the loop can be constrained. It reads known inputs, produces known outputs, and updates the state in a predictable place. The loop can be useful even before it is allowed to make direct changes.
The first loop should usually be read-heavy and write-light. Let Claude inspect, summarize, classify, and draft before allowing it to modify important files or external systems.
Bad First Loops
Bad first loops tend to be broad, vague, high-risk, or difficult to verify. They usually sound attractive because they promise large automation gains, but they fail because the loop cannot reliably decide whether it has done the right thing.
Bad first loop examples include:
Example #1: Rewrite the entire backend architecture.
Example #2: Improve our product direction every week.
Example #3: Automatically modify authentication and payment code until all issues are fixed.
Example #4: Deploy changes to production when Claude thinks they are ready.
Example #5: Clean my whole computer and reorganize all files automatically.The common problem is not that Claude cannot help with these tasks. Claude can assist with planning, reviewing, drafting, and analysis. The issue is that these tasks involve high judgment, high impact, or unclear verification. They should be handled through supervised workflows, not unattended loops.
For example, "clean my whole computer automatically" is too broad for a first loop. A safer version is: "inspect the Downloads folder, group files by type, and write a proposed cleanup plan without moving anything." Once the plan is reliable over several runs, the loop can be extended to rename or move files inside a controlled sandbox folder.
The Permission Ladder
A useful way to think about loop design is through a permission ladder. You do not need to start with full autonomy. In fact, most loops should begin with very limited permissions.
A safe progression looks like this:
Level 1 — Read-only analysis
Claude reads files and writes a summary.
Level 2 — Draft output
Claude writes reports, plans, or suggested changes in an outputs/ folder.
Level 3 — Sandbox edits
Claude modifies files only inside a controlled sandbox or draft branch.
Level 4 — Draft external action
Claude opens a draft pull request, draft message, or draft ticket update.
Level 5 — Human-approved action
Claude applies changes only after explicit approval.
Level 6 — Fully automated low-risk action
Claude completes the task automatically, with logs, limits, and rollback options.Most first loops should stay at Level 1 or Level 2. That is enough to prove whether the loop is useful. You can inspect the output, correct the instructions, improve the state file, and check whether Claude is making the same mistakes repeatedly.
Only after the loop becomes reliable should you move it up the ladder. This is especially important when the loop has access to code, customer data, production systems, private documents, or communication tools.
Cost and Noise Also Matter
A loop can fail even if it technically works. It may run too often, produce too much output, consume too many tokens, or create review work that is larger than the task it was supposed to automate.
This is why the first loop should have a limited scope and a predictable output. Before scheduling it, run it manually several times. Check how much context it reads, how long the output is, and whether the result is useful enough to review repeatedly.
A good loop should reduce cognitive load. It should not create a new inbox full of low-value reports. Runs that find nothing important should either update the state quietly or write a short "no meaningful change" note. Runs that find something important should make the reason clear.
A loop is not successful because it runs automatically. It is successful when it produces useful work with less supervision than manual prompting, while staying within clear cost, permission, and review boundaries.
A Simple Rule for Choosing the First Loop
For the first implementation, choose a task that is useful even if Claude only produces a report. This keeps the risk low and still demonstrates the core loop pattern: trigger, context, action, verification, state update, and decision.
A good first loop might be:
Every morning, review this project folder, compare it with the previous state, summarize changes, identify blockers, update PROGRESS.md, and write a daily report to outputs/daily-review.md.This task is practical, repeatable, and easy to extend. Later, you can add more capabilities: checking Git history, reading issue trackers, connecting to Slack, opening draft tickets, or suggesting code changes. But the first version should prove the operating model before adding more autonomy.
In the next section, we will build the minimum viable Claude loop around this idea: one task, one state file, one output folder, one verification step, and one controlled run.
3. The Minimum Viable Claude Loop
Once you have selected a task that is repetitive, low-risk, and easy to verify, the next step is to build the smallest version of the loop. This first version should not include advanced automation, multiple agents, external connectors, or broad permissions. The goal is to prove the operating pattern before increasing autonomy.
A minimum viable Claude loop has five parts:
- One task — a clear, narrow job that Claude performs every run.
- One context file — instructions that define how the loop should behave.
- One state file — persistent memory that survives between runs.
- One output location — a predictable place where Claude writes results.
- One verification step — a simple check that decides whether the run is acceptable.
This version can run manually at first. Manual execution is not a weakness; it is the safest way to test the loop before scheduling it. You run the loop, inspect the output, adjust the instructions, and repeat until the behavior is stable.
The first Claude loop should be intentionally simple. It should read context, perform one constrained task, write output to a predictable location, update state, and stop. The objective is not full autonomy. The objective is repeatability.
For this section, we will use a practical example: a daily project review loop. The loop reads a project folder, summarizes what changed, identifies blockers, writes a short report, and updates its progress file. This example works well because it is useful, low-risk, and easy to adapt to code projects, writing projects, research folders, or course material.
The folder structure looks like this:
minimal-claude-loop/
├── TASK.md
├── PROGRESS.md
├── LOOP_INSTRUCTIONS.md
└── outputs/
└── daily-review.mdEach file has a specific role:
- TASK.md defines the loop's goal.
- PROGRESS.md stores state between runs.
- LOOP_INSTRUCTIONS.md defines the operating procedure Claude should follow.
- outputs/daily-review.md stores the generated report.
Step 1: Define the Task
The task file should explain what the loop is trying to accomplish. It should not contain too many operational details. Those belong in LOOP_INSTRUCTIONS.md. The task file is the high-level goal that remains stable across runs.
Create TASK.md with the following content:
# Daily Project Review Loop
## Goal
Review this project folder, summarize what changed, identify blockers, and produce a short daily review report.
## Expected Output
Each run should produce or update:
- `outputs/daily-review.md`
- `PROGRESS.md`
## Scope
Claude may inspect files in this workspace and write reports to the `outputs/` folder.
Claude should not modify source files, delete files, rename files, or move files during this first version of the loop.This file gives Claude a clear purpose while preserving the first version. The loop can inspect the project and produce a report, but it is not allowed to modify the actual project files.
This boundary matters. If the first version of the loop only writes to outputs/ and PROGRESS.md, then mistakes are easy to inspect and easy to reverse. You can evaluate the loop without risking accidental changes to the project itself.
Step 2: Add Persistent State
The state file is what makes the loop different from a repeated prompt. Without a state file, each run starts from zero. With a state file, Claude can understand what happened previously and continue from there.
Create PROGRESS.md with this starter structure:
# Loop Progress
## Last Run
- Date:
- Summary:
- Files checked:
- Output produced:
## Current Status
- In progress:
- Blocked:
- Needs human review:
## Next Run Should
-
## Decisions Made
-
## Do Not Repeat
-The sections should stay short. PROGRESS.md is not meant to become a full project history. It is operational memory. It should contain only the information Claude needs to make the next run better than the previous one.
A common mistake is to let the state file grow without structure. After several runs, it becomes too long for Claude to use effectively. A better pattern is to keep the latest status near the top, summarize older runs, and move detailed outputs into separate files inside the outputs/ folder.
PROGRESS.md is the loop's memory interface. Claude should read it before acting and update it before stopping. If the state file is missing, stale, or too long, the loop loses continuity.
Step 3: Define the Loop Instructions
The instruction file tells Claude exactly how to run the loop. This is where you define the sequence of actions, the safety rules, the output format, and the verification criteria.
Create LOOP_INSTRUCTIONS.md with this content:
# Loop Instructions
You are running a daily project review loop.
## Before You Start
1. Read `TASK.md`.
2. Read `PROGRESS.md`.
3. Inspect the project folder.
4. Identify what changed, what is incomplete, and what needs human review.
## What You Should Do
Write a short daily review report to:
`outputs/daily-review.md`
The report should include:
- Summary of current project state
- Files or areas reviewed
- Meaningful changes found
- Blockers or unresolved questions
- Recommended next actions
After writing the report, update `PROGRESS.md` with:
- Date of this run
- Summary of what happened
- Files checked
- Output produced
- What the next run should do
- Anything that needs human review
## Safety Rules
- Do not delete files.
- Do not rename files.
- Do not move files.
- Do not modify source files.
- Only write to `outputs/daily-review.md` and `PROGRESS.md`.
- If you are unsure whether an action is allowed, stop and ask for human review.
## Verification Checklist
Before ending the run, check that:
- `outputs/daily-review.md` exists.
- `outputs/daily-review.md` contains all required sections.
- `PROGRESS.md` has been updated.
- No files outside `outputs/daily-review.md` and `PROGRESS.md` were modified.This file is the control layer around Claude. It tells Claude what to read, what to write, what not to touch, and how to verify the result before stopping.
For a first loop, the instruction file should be explicit. You should not rely on Claude to infer safety boundaries from context. If the loop should not modify source files, say that directly. If the loop should only write to a specific folder, define that folder clearly. If the loop should stop when uncertain, include that as a rule.
Step 4: Create the Output File
The output file gives the loop a predictable destination. This makes the loop easier to inspect, easier to debug, and easier to schedule later.
Create outputs/daily-review.md with this starter content:
# Daily Review
No loop run has been completed yet.Claude will overwrite or update this file during each run. In a more advanced version, you may prefer timestamped reports, such as:
outputs/
├── daily-review-2026-06-22.md
├── daily-review-2026-06-23.md
└── daily-review-2026-06-24.mdFor the first version, however, a single daily-review.md file is enough. The goal is to reduce moving parts until the loop behavior is reliable.
Step 5: Run the Loop Manually
Now you can run the first iteration manually. Open the folder in Claude Code, Claude Desktop/Cowork, Cursor, or any environment where Claude can read and write the local workspace.
Use a simple command or prompt like this:
Run the daily project review loop for this workspace.
Follow `LOOP_INSTRUCTIONS.md` exactly.
Before acting, read `TASK.md` and `PROGRESS.md`.
Write the daily review to `outputs/daily-review.md`, update `PROGRESS.md`, and then report what you changed.
Do not modify any files except `outputs/daily-review.md` and `PROGRESS.md`.The first run should produce two visible changes:
- outputs/daily-review.md should contain the daily review.
- PROGRESS.md should contain the updated state.
After the run, inspect both files manually. Check whether Claude followed the instructions, whether the output was useful, and whether it respected the safety boundaries.
Step 6: Verify the Run
The minimum viable loop should include a verification step even before it is scheduled. Verification can be simple in the beginning. The point is to avoid trusting the loop only because it produced fluent text.
For this example, the verification checklist is:
- Did Claude read TASK.md?
- Did Claude read PROGRESS.md?
- Did Claude write outputs/daily-review.md?
- Did Claude update PROGRESS.md?
- Did Claude avoid modifying files outside the allowed paths?
- Is the daily review structured and useful?
- Is the next action clear?For code workflows, the verification step might be more objective:
- Did the test suite pass?
- Did the type checker pass?
- Did the linter pass?
- Did the build complete successfully?
- Did Claude only change files inside the allowed scope?For document workflows, verification may rely on structured criteria:
- Does the output include all required sections?
- Are unresolved questions listed separately?
- Are action items assigned clearly?
- Is the output saved in the expected location?
- Did Claude avoid editing the original document?The first version does not need a separate verifier agent. It only needs a concrete checklist. Later, you can split the worker and checker into separate steps, but the first implementation should stay simple.
Verification should exist from the first loop, even if it starts as a checklist. A loop that cannot check its own boundaries will eventually create review work instead of reducing it.
Step 7: Iterate Before Scheduling
After the first manual run, do not schedule the loop immediately. Run it manually three to five times with small changes in the workspace. Each run should test whether the loop can continue from the previous state.
For example, before each run, you can:
- Add a new note file.
- Edit TASK.md slightly.
- Add a sample project file.
- Add a blocker to PROGRESS.md.
- Add an unresolved question to the workspace.
Then run the same prompt again and inspect how Claude responds. The loop should not start from zero. It should read the current state, understand what changed, and update the progress file accordingly.
If the output is too long, tighten the instructions. If Claude modifies files it should not touch, make the safety rules stricter. If the state file becomes noisy, improve the PROGRESS.md structure. If the loop forgets important context, move that context into TASK.md or LOOP_INSTRUCTIONS.md.
This manual iteration phase is where the loop becomes reliable. Scheduling should come after the loop has demonstrated stable behavior, not before.
What the Minimum Viable Loop Proves
This small example may look basic, but it proves the core architecture of loop engineering:
Trigger:
A manual prompt starts the run.
Context:
Claude reads TASK.md, PROGRESS.md, and LOOP_INSTRUCTIONS.md.
Action:
Claude inspects the workspace and writes a daily report.
Verification:
Claude checks the required files and allowed modification scope.
State update:
Claude updates PROGRESS.md.
Decision:
The loop stops and waits for the next manual or scheduled run.Once this works, you can extend the loop in several directions. You can add a schedule so it runs every morning. You can connect it to Git so it reviews recent commits. You can add a meeting notes folder so it extracts follow-ups. You can connect it to Slack, GitHub, or Linear. You can also introduce a separate checker step for stronger verification.
But each extension should preserve the same basic structure: clear task, persistent state, constrained action, verification, and review.
The minimum viable Claude loop is not a final system. It is the controlled baseline that lets you safely build toward one. In the next section, we will focus on the most important part of that baseline: persistent state with PROGRESS.md, and how to structure it so the loop can remember without accumulating noise.
4. Adding Persistent State with PROGRESS.md
A Claude loop needs memory outside the chat session. Without a persistent state, every run starts from the same initial context, and Claude has to rediscover what already happened. This is manageable for a one-time task, but it becomes inefficient and unreliable when the loop runs repeatedly.
The simplest way to add persistent state is to create a markdown file called PROGRESS.md. This file acts as the loop's operational memory. At the beginning of each run, Claude reads it to understand the current state of the work. At the end of each run, Claude updates it with what changed, what remains unresolved, and what the next run should do.
This is one of the most important differences between prompting and loop engineering. In manual prompting, continuity often lives in the conversation. In a loop, continuity should live in the workspace.
PROGRESS.md is not just a note file. It is the memory interface of the loop. Each run should read it before acting and update it before stopping.
Why State Matters
Claude can reason about the current task, inspect files, and generate useful outputs, but the model should not be treated as the long-term memory of the workflow. A loop may run tomorrow, next week, after a file change, or after a scheduled trigger. The previous conversation may not be available, and even when it is available, relying on a long chat history is a fragile design.
A state file solves this by keeping the important loop context in a durable, inspectable format. It makes the loop easier to debug because you can open the file and see what Claude believes is true about the current state of the workflow.
For example, if a daily project review loop runs every morning, PROGRESS.md should answer questions like:
What happened during the last run?
Which files were reviewed?
What output was produced?
What is currently blocked?
What should the next run focus on?
What should Claude avoid repeating?
What still needs human review?This allows each run to continue from the previous one instead of starting from zero.
A Practical PROGRESS.md Template
A good state file should be short, structured, and easy for both Claude and humans to read. It should not become a full log of everything that ever happened. Detailed outputs can go into separate files. PROGRESS.md should store the current operational state.
Here is a practical template:
# Loop Progress
## Current State
- Status:
- Main objective:
- Current focus:
- Last updated:
## Last Run
- Date:
- Trigger:
- Summary:
- Files reviewed:
- Output produced:
## Open Items
-
## Blockers
-
## Needs Human Review
-
## Next Run Should
-
## Decisions Made
-
## Do Not Repeat
-This structure gives the loop enough information to resume without forcing Claude to parse a long, unorganized log. It also separates facts from instructions. "Open Items" tells Claude what still needs attention. "Blockers" tells Claude that it should not pretend progress was made. "Needs Human Review" prevents the loop from silently continuing when human judgment is required.
What Should Go Into PROGRESS.md
The state file should contain only information that helps the next run. If the content will not affect future execution, it probably belongs in a report file instead.
Good content for PROGRESS.md includes:
- The latest known status of the loop
- The files or areas checked in the last run
- Open tasks that still need work
- Blockers or missing information
- Decisions made by the human
- Instructions not to repeat failed actions
- The recommended focus for the next runBad content for PROGRESS.md includes:
- Full transcripts of Claude conversations
- Long generated reports
- Repeated copies of the same status update
- Large code snippets
- Raw logs
- Unfiltered brainstorming notesThe purpose of PROGRESS.md is not to preserve everything. The purpose is to preserve the minimum state needed for the loop to continue correctly.
A useful state file is closer to a control panel than an archive. It should tell the next run where the loop is, what matters now, what is blocked, and what should happen next.
Example: PROGRESS.md After the First Run
After the first manual run, the file might look like this:
# Loop Progress
## Current State
- Status: Active manual testing
- Main objective: Produce a daily project review report
- Current focus: Verify that Claude reads the instruction files and writes only to allowed paths
- Last updated: 2026-06-22
## Last Run
- Date: 2026-06-22
- Trigger: Manual run
- Summary: Claude reviewed the workspace structure and generated the first daily review report.
- Files reviewed:
- TASK.md
- LOOP_INSTRUCTIONS.md
- PROGRESS.md
- outputs/daily-review.md
- Output produced:
- outputs/daily-review.md
## Open Items
- Run the loop manually two more times before scheduling.
- Add a clearer output format if the report becomes too verbose.
## Blockers
- None.
## Needs Human Review
- Confirm whether the daily review format is useful.
- Confirm whether future runs should create timestamped reports or overwrite `daily-review.md`.
## Next Run Should
- Read this file first.
- Check whether any project files were added or changed.
- Update the daily review report.
- Keep the output concise.
## Decisions Made
- The loop is allowed to write only to `outputs/daily-review.md` and `PROGRESS.md`.
- Scheduling should not be enabled until the manual run is stable.
## Do Not Repeat
- Do not modify source files.
- Do not rename or move files.This gives the second run a clear starting point. Claude can see that the loop is still in manual testing, that scheduling is not yet allowed, and that it should keep changes limited to the approved files.
Keeping State Short
A common failure mode is letting the state file grow too much. If every run appends a long entry, PROGRESS.md eventually becomes difficult to read and less useful for the model. The loop then wastes context on stale information and may start following outdated instructions.
A better pattern is to keep PROGRESS.md focused on the latest state and move historical details into separate files when needed.
For example:
outputs/
├── daily-review.md
├── history/
│ ├── 2026-06-22-review.md
│ ├── 2026-06-23-review.md
│ └── 2026-06-24-review.mdIn this pattern, PROGRESS.md stores the current status and a summary of recent runs. The detailed reports live in outputs/history/. This keeps the loop memory compact while preserving an audit trail.
A practical rule is:
If Claude needs it to decide the next action, keep it in PROGRESS.md. If a human may want to inspect it later, store it in outputs/.
Updating State at the End of Every Run
The loop instructions should explicitly require Claude to update PROGRESS.md before stopping. This should not be optional. If a run produces a report but does not update the state, the next run loses continuity.
Add this rule to LOOP_INSTRUCTIONS.md:
## State Update Rule
Before ending every run, update `PROGRESS.md`.
The update must include:
- What happened in this run
- Which files were reviewed
- Which output files were created or changed
- Any blockers or unresolved questions
- What the next run should do
- Whether human review is needed
If you cannot update `PROGRESS.md`, stop and report the reason.This makes the state update part of the loop contract. The loop is not complete just because the main output exists. It is complete only when the output is written, the state is updated, and the next step is clear.
Separating the State from the instructions
PROGRESS.md should not become the main instruction file. It should describe the current state of the loop, not redefine how the loop works. The operating procedure belongs in LOOP_INSTRUCTIONS.md. The task objective belongs in TASK.md. The current memory belongs in PROGRESS.md.
A useful separation is:
TASK.md:
What is the loop trying to accomplish?
LOOP_INSTRUCTIONS.md:
How should Claude run the loop?
PROGRESS.md:
What is the current state of the loop?
outputs/:
What did the loop produce?This separation keeps the system easier to maintain. If the goal changes, update TASK.md. If the procedure changes, update LOOP_INSTRUCTIONS.md. If the current state changes, update PROGRESS.md.
When Markdown Is Not Enough
For the first loop, markdown is usually the right choice. It is easy to read, easy to edit, and easy to version-control. However, as loops become more complex, the state may need to move into a more structured system.
For example:
Markdown state:
Best for solo workflows, local projects, writing workflows, and simple code loops.
GitHub Issues or Linear:
Best when loop state needs to be visible to a team.
Database or JSON state:
Best when the loop needs structured querying, multiple concurrent runs, or programmatic state updates.
Slack or email summaries:
Best for human-facing notifications, but not ideal as the primary state source.The important point is not the storage format. The important point is that the state must persist outside Claude's temporary reasoning context and remain inspectable by humans.
For most readers, PROGRESS.md is the correct starting point. It is simple enough to use immediately and structured enough to teach the core loop pattern.
The State File as a Safety Mechanism
Persistent state is not only about memory. It is also a safety mechanism. A good PROGRESS.md file tells Claude what not to repeat, what is blocked, and what requires human review.
For example, the Do Not Repeat section can prevent the loop from retrying actions that already failed:
## Do Not Repeat
- Do not rerun the same cleanup plan until the human approves it.
- Do not modify files outside the outputs/ folder.
- Do not suggest deleting files unless they are duplicates confirmed by name and checksum.The Needs Human Review section can stop the loop from silently continuing when the next step requires judgment:
## Needs Human Review
- Confirm whether archived files should be moved or left in place.
- Confirm whether the loop should switch from overwriting daily-review.md to creating timestamped reports.This is why the state file should be visible and editable by a human. You can directly shape future loop behavior by editing PROGRESS.md before the next run.
Persistent state is also a control surface. By editing PROGRESS.md, you can redirect the next run, block unsafe actions, record decisions, and keep Claude from repeating known mistakes.
In the next section, we will add the other half of reliability: verification. A stateful loop can remember, but memory alone does not make the loop trustworthy. The loop also needs a way to check whether its output is correct, complete, and safe before it continues.
5. Verification: Separating the Worker from the Checker
A Claude loop becomes useful only when it can distinguish between output that looks complete and output that is actually complete. This is where verification becomes important. Without verification, a loop can keep producing fluent reports, confident summaries, or plausible code changes while quietly drifting away from the real task.
The simplest failure mode is this: Claude performs the work, says the task is done, updates the state file, and stops. From the outside, the loop appears successful. But if the output is missing required sections, the wrong files were modified, the tests were not run, or the state file was updated incorrectly, the loop has only created the appearance of progress.
Verification is the part of the loop that prevents this. It defines what must be true before a run can be treated as complete.
A Claude loop should not stop because Claude says it is finished. It should stop because a concrete condition has been checked: a file exists, a required structure is present, a test passes, a checklist is complete, or a human review is required.
Why "Done" Is Not Enough
In normal prompting, "done" is often a conversational signal. Claude gives you an answer, and you decide whether the answer is useful. In a loop, this is not enough because the loop may run repeatedly, on a schedule, or with less direct supervision.
A loop needs an operational definition of done. This definition should be explicit, observable, and ideally testable.
Weak completion criteria look like this:
- The report looks good.
- The task seems complete.
- Claude says the issue is fixed.
- The output is probably ready.These criteria are too subjective. They depend on Claude's own judgment or on a human reading the result every time.
Better completion criteria look like this:
- outputs/daily-review.md exists.
- outputs/daily-review.md contains all required sections.
- PROGRESS.md has been updated.
- No files outside the allowed paths were modified.
- The output includes blockers and next actions.
- If uncertainty exists, the run is marked as needing human review.For code workflows, completion criteria can be even stronger:
- Unit tests pass.
- Type checks pass.
- Linting passes.
- The build succeeds.
- No forbidden files were changed.
- A draft pull request was created instead of merging directly.The more objective the condition, the more reliable the loop becomes. This does not remove the need for human judgment, but it reduces the number of cases where a human has to inspect obvious failures.
The Maker-Checker Pattern
A useful way to design verification is to separate the worker from the checker. The worker performs the task. The checker evaluates the result against explicit criteria.
In the minimum viable loop, both steps may still be performed inside the same Claude run, but they should be written as separate phases. This matters because it forces the loop to slow down and inspect its own output before stopping.
A simple maker-checker pattern looks like this:
Worker phase:
- Read TASK.md, PROGRESS.md, and LOOP_INSTRUCTIONS.md.
- Inspect the workspace.
- Write outputs/daily-review.md.
- Update PROGRESS.md.
Checker phase:
- Confirm outputs/daily-review.md exists.
- Confirm all required report sections are present.
- Confirm PROGRESS.md was updated.
- Confirm no forbidden files were modified.
- If any check fails, fix the issue or mark the run as needing human review.
This is not yet a multi-agent system. It is a structured run with two modes: produce, then verify. For many practical workflows, this is enough to catch simple failures.
Later, you can make the separation stronger by using a second Claude run, a sub-agent, a script, a test suite, or an external checker. The important principle is the same: the system that generates the output should not be the only signal that approves the output.
The checker should not be another vague reviewer. It should evaluate the output against specific criteria. A second opinion is useful only when it has a standard to check against.
Adding a Verification Checklist to the Loop
For the daily project review loop, we can add a verification checklist directly to LOOP_INSTRUCTIONS.md.
Add this section near the end of the file:
## Verification Checklist
Before ending the run, verify the following:
### Required Files
- `outputs/daily-review.md` exists.
- `PROGRESS.md` exists.
### Required Report Sections
`outputs/daily-review.md` must include:
- Summary
- Files reviewed
- Meaningful changes
- Blockers or unresolved questions
- Recommended next actions
### State Update
`PROGRESS.md` must include:
- Date of the current run
- Summary of what happened
- Files checked
- Output produced
- What the next run should do
- Whether human review is needed
### Safety Boundary
Only these files may be modified:
- `outputs/daily-review.md`
- `PROGRESS.md`
If any other file was modified, stop and report the issue.This checklist gives Claude a concrete standard to apply before ending the run. It also gives the human reader a clear way to inspect whether the loop behaved correctly.
A Simple Verification Prompt
After Claude produces the output, you can ask it to run a separate verification pass. This is useful during manual testing before the loop is scheduled.
Use a prompt like this:
Run a verification pass for the latest loop execution.
Check the result against the Verification Checklist in LOOP_INSTRUCTIONS.md.
Report:
1. Which checks passed
2. Which checks failed
3. Which files were modified
4. Whether the run is safe to accept
5. Whether human review is required
Do not modify any files during this verification pass.This prompt keeps the checker phase read-only. Claude has not been asked to fix anything yet. It is asked to inspect and report.
During early testing, this separation is useful. First, run the loop. Then, run the verification pass. If the verification repeatedly passes, you can later merge both phases into one loop instruction or create a separate checker step.
Verification for Non-Code Workflows
Not every Claude loop writes code. Many useful loops are document, research, operations, or knowledge-management workflows. These loops still need verification, but the checks look different.
For a meeting follow-up loop, verification might check:
- Action items are listed separately.
- Each action item has an owner if one was mentioned.
- Deadlines are extracted when present.
- Open questions are separated from confirmed decisions.
- The original meeting notes were not modified.For a folder cleanup planning loop, verification might check:
- No files were moved or renamed.
- Files were grouped by type.
- Potential duplicates were marked for review.
- The cleanup plan was written to outputs/cleanup-plan.md.
- Risky actions were listed under "Needs Human Review."For a newsletter research loop, verification might include:
- Each claim has a source link or note.
- Open uncertainties are listed.
- Draft ideas are separated from verified facts.
- The loop does not publish or send anything automatically.These checks are less mechanical than a test suite, but they still create a clear standard. They make the loop easier to debug and reduce the chance that Claude silently treats incomplete work as complete.
Verification for Code Workflows
Code loops need stricter verification because code changes can break systems in ways that are not visible from the generated diff alone. A code loop should use existing project checks whenever possible.
For example:
Verification commands:
- npm test
- npm run lint
- npm run typecheck
- npm run buildOr for a Python project:
Verification commands:
- pytest
- ruff check .
- mypy .The loop instructions should tell Claude exactly which commands are allowed and when to run them:
## Code Verification
If this loop modifies code, run the following checks before marking the run complete:
```bash
npm test
npm run lint
npm run typecheckIf any command fails:
- Do not mark the run as complete.
- Summarize the failure.
- Update PROGRESS.md.
- Mark the run as needing human review if the failure is unclear.
The key point is that the loop should not rely only on generated reasoning. It should use the project's existing verification infrastructure. Tests, type checkers, linters, and builds are valuable because they can fail the work without needing Claude to decide subjectively.
### Preventing the Checker from Becoming Another Optimist
A weak checker simply reads the worker's output and agrees with it. This is common when the checker prompt is vague:
```text id="epfh9h"
Review the output and tell me if it looks good.This usually produces a polite review, not a reliable gate. A stronger checker prompt defines the acceptance criteria and asks for a pass/fail result:
Evaluate the latest loop output against the checklist below.
For each item, return PASS or FAIL.
Do not give partial credit.
Do not assume a missing section is present.
Do not mark the run complete if any required item fails.
Checklist:
- outputs/daily-review.md exists
- Summary section exists
- Files reviewed section exists
- Blockers section exists
- Recommended next actions section exists
- PROGRESS.md was updated
- No files outside the allowed paths were modified
If any item fails, mark the run as NOT ACCEPTED.This style makes the checker more useful because it reduces ambiguity. It also produces outputs that are easier to scan in a scheduled loop report.
A verifier needs a pass/fail standard. "Review this" is too weak. "Check these seven conditions and mark the run accepted only if all seven pass" is a much stronger loop boundary.
What Happens When Verification Fails
A loop should define what happens when verification fails. Otherwise, failure becomes another place where Claude improvises.
There are three common options:
1. Retry
Use when the failure is small, clear, and safe to fix.
2. Escalate
Use when the failure needs human judgment or touches a risky area.
3. Stop
Use when the loop hit its iteration limit, permission boundary, or budget limit.For the daily project review loop, the failure policy could be:
## Failure Policy
If verification fails:
1. If the failure is a missing section in `outputs/daily-review.md`, fix the report once.
2. If `PROGRESS.md` was not updated, update it once.
3. If any forbidden file was modified, stop immediately and report the issue.
4. If the same verification check fails twice, stop and mark the run as needing human review.This prevents the loop from retrying indefinitely. It also creates a clear escalation path when the loop cannot safely complete the task.
Add an Iteration Limit
Even with verification, a loop needs a maximum number of attempts. This protects against cases where Claude keeps trying to satisfy a condition that it cannot actually meet.
For a small manual loop, the limit can be simple:
Maximum attempts: 2
If verification still fails after 2 attempts, stop and ask for human review.For a scheduled or code loop, the limit should be stricter and more explicit:
Maximum attempts per scheduled run: 3
Maximum runtime: 20 minutes
Maximum files modified: 3
Stop immediately if a forbidden path is touched.Iteration limits are part of verification because they define when the loop should stop trying. Without them, the loop may keep spending tokens or making unnecessary changes.
Verification Should Update State Too
When verification passes or fails, the result should be recorded in PROGRESS.md. This gives the next run useful context.
For example:
## Last Verification
- Date: 2026-06-23
- Result: Failed
- Failed checks:
- Missing "Blockers" section in outputs/daily-review.md
- Action taken:
- Report was corrected once
- Final status:
- Passed after correctionOr:
## Last Verification
- Date: 2026-06-23
- Result: Failed
- Failed checks:
- Forbidden file modified: src/config.ts
- Action taken:
- Stopped immediately
- Final status:
- Needs human reviewThis prevents the loop from hiding failure. It also gives the next run an explicit warning about what happened.
A loop that fails and records the failure is still useful. A loop that fails silently is dangerous.
The Minimum Verification Setup
For the first version of the loop, you do not need a complex evaluation infrastructure. A practical minimum is:
- A verification checklist in LOOP_INSTRUCTIONS.md
- A manual verification prompt
- A rule that failed verification must be recorded in PROGRESS.md
- A rule that repeated failure escalates to human reviewThis gives you enough structure to test the loop safely. Later, you can replace parts of the checklist with scripts, tests, schemas, CI checks, or separate verifier agents.
The important point is to introduce verification before scheduling. Scheduling a loop without verification only makes failure faster and less visible.
In the next section, we will move from manual runs to scheduled execution with /loop. At that point, verification becomes even more important because Claude may be running on an interval rather than waiting for you to manually start each run.
6. Scheduling the Loop with /loop
At this point, the loop has the minimum pieces it needs: a clear task, an instruction file, a state file, an output location, and a verification step. The next step is scheduling. This is where the workflow moves from "I manually ask Claude to run this" to "Claude reruns the loop on a defined cadence."
Scheduling should come after manual testing, not before it. If the loop is unreliable when you run it manually, scheduling only makes the failure happen more often. A scheduled loop should be a stable manual workflow with a trigger attached to it.
Do not schedule the first version of a loop immediately. Run it manually several times, inspect the output, adjust the instructions, and only schedule it after the loop behaves predictably.
What /loop Does
In Claude Code, /loop is the lightweight way to rerun a prompt repeatedly inside a session. You give Claude a prompt and an interval, and Claude schedules that prompt to run again at that cadence.
For our daily project review example, the scheduled version could look like this:
/loop 24h Run the daily project review loop for this workspace.
Follow LOOP_INSTRUCTIONS.md exactly.
Before acting:
- Read TASK.md
- Read PROGRESS.md
- Inspect the workspace
Then:
- Write the daily review to outputs/daily-review.md
- Update PROGRESS.md
- Run the verification checklist
- Stop if human review is required
Do not modify any files except outputs/daily-review.md and PROGRESS.md.This turns the manual loop prompt into a repeated prompt. The loop still depends on the same files and safety rules. /loop only provides the trigger.
That distinction matters. /loop does not replace good loop design. It does not automatically give the task a state file, a verifier, a safe permission boundary, or a useful stop condition. It simply repeats the prompt. The quality of the loop still comes from the structure around the prompt.
Start with a Short Testing Interval
Before using a daily cadence, test the loop with a shorter interval. For example, you can run it every 10 or 15 minutes while you are actively watching the workspace.
/loop 15m Run the daily project review loop for this workspace. Follow LOOP_INSTRUCTIONS.md exactly.This is not meant to be the final schedule. It is a testing cadence. It lets you see how the loop behaves across multiple runs without waiting a full day.
During this testing phase, check:
- Does Claude read PROGRESS.md each time?
- Does it avoid repeating the same summary?
- Does it update the state correctly?
- Does the output remain concise?
- Does it respect the allowed file boundaries?
- Does it mark uncertain items for human review?
If the loop produces noisy reports, update LOOP_INSTRUCTIONS.md. If it forgets context, improve PROGRESS.md. If it modifies files it should not touch, tighten the safety rules. If the output is too long, define a stricter report format.
Move to the Real Cadence
Once the short testing interval works, move the loop to the cadence that matches the task.
For a daily project review loop:
/loop 24h Run the daily project review loop for this workspace. Follow LOOP_INSTRUCTIONS.md exactly.For a weekly folder cleanup planning loop:
/loop 7d Inspect the workspace for files that may need cleanup. Write a cleanup plan to outputs/cleanup-plan.md and update PROGRESS.md. Do not move, rename, or delete files.For a pull request monitoring loop:
/loop 30m Check whether the current pull request has new CI failures or review comments. Summarize findings in PROGRESS.md and do not modify code unless explicitly instructed.For a long-running build or deployment check:
/loop 10m Check whether the deployment has completed. If it succeeds, summarize the result and stop. If it fails, record the error and mark the run as needing human review.The cadence should match the rate at which the environment changes. A project review does not need to run every five minutes. A deployment check might. A weekly cleanup report does not need a daily trigger.
The schedule should follow the task, not the other way around. A loop should run only as often as new information is likely to appear or action is likely to be useful.
/loop vs /goal
It is useful to separate two different ideas: interval-based repetition and condition-based continuation.
Use /loop when the next run should happen because time has passed.
/loop 24h Run the daily project review loop.Use /goal when Claude should keep working because a completion condition has not been met yet.
/goal outputs/daily-review.md exists, PROGRESS.md is updated, the verification checklist passes, and no files outside the allowed paths were modified.In practice, /loop and /goal solve different problems.
/loop is useful for recurring checks:
- Check every morning
- Poll every 30 minutes
- Review the folder once per week
- Check the PR until new information appears/goal is useful for completion-driven work:
- Continue until tests pass
- Continue until the report has all required sections
- Continue until the issue queue is empty
- Continue until the output matches the acceptance criteriaFor the daily project review loop, /loop is the primary mechanism, as the task is time-based. It should run once per day. For a coding loop that fixes a failing test, /goal may be more appropriate because the loop should continue until a verifiable condition holds.
Scheduling Needs a Stop Policy
A scheduled loop still needs a stop policy. Without one, it can create repeated low-value output, retry the same failed action, or keep running even after the task needs human review.
For the daily project review loop, add this to LOOP_INSTRUCTIONS.md:
## Scheduled Run Policy
When this loop runs on a schedule:
- If there are meaningful changes, write a concise report to `outputs/daily-review.md`.
- If there are no meaningful changes, write a short "No meaningful changes" note.
- If human review is needed, mark it clearly in `PROGRESS.md`.
- If the same blocker appears in two consecutive runs, do not keep retrying. Escalate to human review.
- If verification fails twice, stop and mark the run as not accepted.This prevents the loop from becoming noisy. A scheduled loop should not generate a long report just because it ran. It should produce information proportional to what changed.
A useful scheduled loop has two output modes:
Quiet mode:
Nothing meaningful changed. Update state briefly and stop.
Attention mode:
Something changed, failed, or needs review. Write a clear report and flag the issue.This matters because humans stop reading automated reports when most of them contain no signal. A good loop should reduce review load, not create a new inbox.
Add a Review Window
For the first few days, treat the scheduled loop as supervised. Let it run automatically, but inspect each output.
A simple review process looks like this:
Day 1:
Run manually and verify output.
Day 2:
Run with a short /loop testing interval while watching.
Day 3:
Move to the real cadence.
Days 4–7:
Review every scheduled output.
After one week:
Decide whether to keep, adjust, or expand the loop.This review window helps you catch errors before the loop becomes part of your routine. It also gives you enough examples to improve the instructions.
During the review window, track three metrics:
1. Useful outputs
How many runs produced something worth reading?
2. False alarms
How many runs created noise or flagged issues that did not matter?
3. Missed issues
How many important changes did the loop fail to notice?You do not need a formal evaluation infrastructure for the first loop. A simple note in PROGRESS.md is enough.
## Loop Review Notes
- 2026-06-24: Output useful. Summary was concise.
- 2026-06-25: Too verbose. Reduced report length in LOOP_INSTRUCTIONS.md.
- 2026-06-26: Missed new file in docs/. Added instruction to inspect docs/ folder.This makes improvement part of the loop itself.
Be Careful with Permissions
Scheduling changes the risk profile. A manual loop runs while you are watching. A scheduled loop may run while you are not paying attention. This is why scheduled loops should start with limited permissions.
For the daily project review loop, the first scheduled version should remain read-heavy and write-light:
Allowed:
- Read workspace files
- Write outputs/daily-review.md
- Update PROGRESS.md
Not allowed:
- Delete files
- Rename files
- Move files
- Modify source files
- Send messages
- Open external tickets
- Push codeIf you later connect the loop to GitHub, Slack, Linear, or another external tool, keep the same principle. Start with draft outputs and human review. Do not give the loop direct write access until it has demonstrated reliable behavior across repeated runs.
Scheduling increases the value of a loop, but it also increases the cost of mistakes. The safest scheduled loops begin with read-only analysis, draft outputs, explicit verification, and human review.
When /loop Is Not the Right Tool
/loop is useful for session-based recurring work, quick polling, and testing loop behavior. However, it is not always the right scheduling mechanism.
Use a different scheduling approach when:
- The loop must run even when the current Claude Code session is closed.
- The loop must run when your machine is off.
- The loop should be triggered by an external event rather than time.
- The loop needs production-grade observability and logs.
- The loop is part of a CI/CD pipeline.In those cases, you may use a desktop scheduled task, a cloud routine, GitHub Actions, a CI job, a webhook, or a custom script that calls Claude through a controlled interface.
The architecture stays the same:
Trigger → Context → Action → Verification → State update → Stop / escalate / repeat
Only the trigger changes.
This is why it is useful to design the loop around files like TASK.md, LOOP_INSTRUCTIONS.md, and PROGRESS.md. They make the loop portable. You can start with a manual prompt, test with /loop, and later move the same workflow into a stronger scheduler if needed.
A Practical First Schedule
For the daily project review loop, a sensible first schedule is:
/loop 24h Run the daily project review loop for this workspace.
Follow LOOP_INSTRUCTIONS.md exactly.
Read TASK.md and PROGRESS.md first.
Write the report to outputs/daily-review.md.
Update PROGRESS.md before stopping.
Run the verification checklist.
If there are no meaningful changes, keep the report short.
If human review is needed, clearly mark it in PROGRESS.md.
Do not modify any files except outputs/daily-review.md and PROGRESS.md.This prompt is longer than a normal prompt because it is not just a request. It is an operating instruction that will be repeated. Clear repetition is better than clever phrasing. When a prompt becomes part of a loop, ambiguity compounds across runs.
After scheduling, do not judge the loop based on the first successful run. Judge it based on repeated stability. A useful loop does not work once. It keeps producing useful output without forcing you to supervise every detail.
In the next section, we will extend the loop beyond local files by adding tools, connectors, and safer permission boundaries. This is where a loop becomes more useful, but also where the security and review requirements become stricter.
7. Adding Tools, Connectors, and Safer Permissions
So far, the loop has worked inside a local workspace. Claude reads markdown files, inspects the folder, writes a report, updates PROGRESS.md, and stops. This is the right starting point because local files are easy to inspect, and the risk is limited.
The next stage is to let the loop interact with tools. This is where Claude loops become more useful, but also more dangerous. A loop that can read files is a controlled assistant. A loop that can update tickets, open pull requests, query databases, post in Slack, or trigger external workflows is now operating inside your real environment.
The goal is not to avoid tools. The goal is to add them gradually, with narrow permissions and clear review points.
Tools make loops useful beyond the local folder, but every new tool expands the loop's blast radius. A good loop should gain permissions slowly: read first, draft second, write only after repeated successful runs.
Start with Local Files
Before connecting Claude to external systems, make sure the local-file version of the loop is stable. Local files give you a controlled environment where you can test the loop's behavior without giving it access to production systems, customer data, or communication channels.
For the daily project review loop, the first tool layer is simple:
Allowed:
- Read files in the workspace
- Write outputs/daily-review.md
- Update PROGRESS.md
Not allowed:
- Delete files
- Rename files
- Move files
- Modify source files
- Send messages
- Open tickets
- Push codeThis setup may look limited, but it is enough to validate the core loop. Claude can still inspect the project, summarize changes, identify blockers, and write structured outputs. If this version is unreliable, adding more tools will not fix it. It will only make the failure harder to contain.
What Connectors Add
Connectors allow a loop to access systems outside the local workspace. In Claude workflows, this often means tools exposed through MCP servers or built-in integrations. A connector can give Claude access to issue trackers, repositories, databases, documentation systems, messaging platforms, or internal APIs.
For example:
GitHub:
Read issues, inspect pull requests, check CI status, open draft PRs.
Linear or Jira:
Read tickets, update status, link work to tasks, create follow-up items.
Slack:
Post summaries, notify humans on escalation, share daily reports.
Database or analytics tools:
Read metrics, query logs, inspect operational state.
Sentry or error tracking:
Read recent errors, group recurring failures, draft investigation notes.This changes the shape of the loop. The loop is no longer only summarizing a folder. It can now observe external systems and prepare actions.
A connected daily review loop might work like this:
Every morning:
- Read PROGRESS.md
- Inspect the local project folder
- Check open GitHub issues
- Check recent pull requests
- Check failed CI runs
- Write a daily review report
- Update PROGRESS.md
- Flag anything that needs human reviewThis is more useful than the local-only version, but it also requires tighter boundaries. Claude should not receive broad write permissions just because they can read these systems.
A connector should start as an observation channel, not an action channel. Let the loop read external systems and draft recommendations before allowing it to update or execute anything.
The Permission Ladder for Connected Loops
When adding tools, use a permission ladder. This makes autonomy explicit instead of accidental.
A practical progression looks like this:
Level 1 — Read-only access
Claude can inspect files, tickets, logs, issues, and dashboards.
Level 2 - Draft outputs
Claude can write reports, draft ticket comments, draft Slack messages, or draft PR descriptions.
Level 3 - Sandbox edits
Claude can modify files only in a sandbox folder, draft branch, or isolated worktree.
Level 4 - Draft external actions
Claude can prepare external actions, such as draft pull requests or draft issue updates, but not finalize them.
Level 5 - Human-approved writes
Claude can perform writes only after explicit human approval.
Level 6 - Fully automated low-risk writes
Claude can complete narrowly scoped actions automatically, with logs, limits, and rollback.Most connected loops should begin at Level 1 or Level 2. At these levels, the loop can produce useful work without being allowed to change important systems directly.
For example, instead of letting Claude update Jira automatically, start with:
Read open Jira tickets.
Summarize likely blockers.
Draft suggested ticket updates in outputs/jira-updates.md.
Do not update Jira directly.Instead of letting Claude post to Slack automatically, start with:
Draft a Slack update in outputs/slack-draft.md.
Do not send the message.
Mark the draft as needing human review in PROGRESS.md.Instead of letting Claude push code, start with:
Inspect the failing test.
Write an investigation report.
Suggest a fix.
Do not modify code unless explicitly approved.This approach gives you most of the value early: Claude can collect context, organize information, and prepare the next action. The human still controls the irreversible step.
Use Tool-Specific Rules
When the loop gains access to tools, the instructions should become tool-specific. A generic rule like "be careful with GitHub" is not enough. The loop needs clear boundaries for each tool.
For example, you can add a section like this to LOOP_INSTRUCTIONS.md:
## Tool Permissions Policy
### Filesystem
Allowed:
- Read files in this workspace
- Write `outputs/daily-review.md`
- Update `PROGRESS.md`
Not allowed:
- Delete files
- Rename files
- Move files
- Modify source files
### GitHub
Allowed:
- Read open issues
- Read pull request status
- Read CI status
- Draft a summary in `outputs/github-review.md`
Not allowed:
- Push commits
- Merge pull requests
- Close issues
- Change labels
- Comment publicly without human approval
### Slack
Allowed:
- Draft a message in `outputs/slack-update.md`
Not allowed:
- Send messages
- Mention users
- Post to channels without human approval
### Linear / Jira
Allowed:
- Read assigned tickets
- Draft suggested status updates
Not allowed:
- Change ticket status
- Assign tickets
- Close tickets
- Create new tickets without approvalThis makes the loop's allowed actions explicit. It also gives Claude a clear escalation path. If an action is outside the allowed scope, the loop should not improvise. It should mark the action for human review.
Use /permissions for Claude Code Tool Access
Instruction files define the behavioral policy, but tool permissions should also be enforced at the tool level when possible. In Claude Code, use the permissions interface to review what Claude is allowed to do.
For a loop, the important principle is to avoid broad permissions. Do not give an unattended or scheduled loop unrestricted shell access, unrestricted file editing, or broad connector write access.
A safer permission policy looks like this:
Allow:
- Read files in the project workspace
- Write specific output files
- Run specific safe commands if needed
Ask:
- Editing project files
- Opening pull requests
- Posting messages
- Updating external systems
Deny:
- Reading secrets
- Deleting files
- Moving large folders
- Pushing to protected branches
- Running unknown scripts
- Accessing unrelated directoriesThis gives the loop a technical boundary in addition to the written instructions. Written instructions are useful, but permission controls are stronger because they can prevent actions rather than simply asking Claude not to perform them.
Do not rely only on prompt instructions for safety. Use tool permissions, scoped access, and human approval gates so the loop cannot perform high-impact actions just because the prompt drifted or the task changed.
Command Allowlist for Code Loops
If the loop can run shell commands, use a command allowlist. A code loop often needs to run tests, linting, type checks, or build commands. It does not need unrestricted terminal access.
For a Node.js project, the allowlist might be:
Allowed commands:
- npm test
- npm run lint
- npm run typecheck
- npm run build
- git status
- git diffFor a Python project:
Allowed commands:
- pytest
- ruff check .
- mypy .
- git status
- git diffAvoid broad permissions like:
- Run any bash command
- Install any package
- Modify any file
- Execute any script found in the repoPackage installation is especially important. Installing dependencies or running arbitrary scripts can execute code you did not inspect. For early loops, dependency changes should be drafted and reviewed, not applied automatically.
A safer loop instruction is:
## Command Policy
Allowed commands:
- `git status`
- `git diff`
- `npm test`
- `npm run lint`
- `npm run typecheck`
Not allowed:
- Installing packages
- Running arbitrary scripts
- Deleting files
- Changing environment variables
- Reading `.env`, credentials, SSH keys, or cloud config files
If a command outside the allowlist appears necessary, stop and ask for human review.Worktrees for Safer Code Changes
If a loop will modify code, do not let it work directly on the main checkout. Use a separate branch or worktree. This isolates changes and makes it easier to review or discard the result.
A code loop should follow a pattern like this:
1. Create or use an isolated branch/worktree.
2. Apply the change only inside that isolated workspace.
3. Run tests and verification commands.
4. Write a summary of the changes.
5. Open a draft PR or ask for human review.
6. Do not merge automatically.This is especially important when multiple agents or loops may touch the same repository. Without isolation, two loops can edit the same files and create confusing conflicts. With worktrees or branches, each loop has its own workspace and its own reviewable diff.
Protect Secrets and Sensitive Data
Connected loops often fail at the boundary between useful context and sensitive context. A loop may need logs, tickets, or configuration files, but it does not need unrestricted access to secrets.
Add explicit rules:
## Sensitive Data Policy
The loop must not read, copy, summarize, or expose:
- `.env` files
- API keys
- SSH keys
- Cloud credentials
- Database passwords
- Customer personal data unless explicitly required and approved
- Private tokens in logs
If sensitive data appears in a file or tool response, do not include it in outputs. Replace it with `[REDACTED]` and mark the run as needing human review.This is particularly important for scheduled loops because their outputs may be stored in reports, logs, Slack messages, GitHub comments, or tickets. A loop that casually copies logs into a report can accidentally spread credentials or private information.
Draft First, Act Later
The safest pattern for connected loops is draft-first automation. The loop can prepare the action, but a human decides whether to send, merge, post, close, or deploy.
Examples:
Slack:
Write outputs/slack-draft.md instead of posting directly.
GitHub:
Open a draft PR instead of merging.
Linear/Jira:
Write suggested ticket updates instead of changing status.
Database:
Write a query result summary instead of modifying records.
Email:
Draft the message instead of sending it.This pattern is useful because it preserves human control over external effects. Claude still saves time by collecting context and preparing the work, but the final action remains reviewable.
In many cases, this is the best long-term design. Not every loop needs to climb to full autonomy. A loop that reliably prepares high-quality drafts can be more valuable than a loop that acts automatically and creates cleanup work.
Add Audit Logs
When loops interact with tools, state alone may not be enough. You should also keep an audit trail of what the loop attempted, what it changed, and what was escalated.
For a simple local workflow, PROGRESS.md may be enough. For connected workflows, add an audit file:
outputs/
├── daily-review.md
├── audit-log.md
└── history/
├── 2026-06-24-review.md
└── 2026-06-25-review.mdAn audit entry can be short:
## 2026-06-24 Scheduled Run
- Trigger: `/loop 24h`
- Tools used:
- Filesystem read
- GitHub issue read
- Files changed:
- outputs/daily-review.md
- PROGRESS.md
- External actions:
- None
- Human review required:
- Yes
- Reason:
- CI failure needs investigation before any code changesThis makes the loop easier to debug. If something goes wrong, you can inspect the audit log instead of reconstructing the run from memory.
Re-Audit Permissions Regularly
Permission boundaries tend to expand over time. A loop starts read-only, then gets permission to draft, then gets permission to update one field, then gets another permission for convenience. Without review, the loop's actual access may become broader than its original design.
Add a recurring permission review rule:
## Permission Review Rule
Review this loop's permissions every 30 days or whenever a new tool is added.
During review, check:
- Which tools the loop can access
- Which files the loop can modify
- Which external systems the loop can write to
- Whether any permission is broader than needed
- Whether human approval is still required before external actionsThis does not need to be complicated. The point is to make permission review part of the workflow rather than an afterthought.
A Connected Version of the Daily Review Loop
Once the local loop is stable, you can extend it with an external context while keeping actions constrained.
A connected version might use this instruction:
Run the daily project review loop.
Read:
- TASK.md
- LOOP_INSTRUCTIONS.md
- PROGRESS.md
Inspect:
- Local workspace
- Open GitHub issues
- Recent pull requests
- CI status
Write:
- outputs/daily-review.md
- outputs/github-review.md
- PROGRESS.md
Do not:
- Push commits
- Merge pull requests
- Close issues
- Post comments
- Send Slack messages
- Modify source files
If an external action seems useful, draft it in outputs/recommended-actions.md and mark it as needing human review.This is a good intermediate stage. Claude can use external tools to produce a better review, but they still cannot make irreversible changes. The human remains in control of the final action.
What to Avoid
The common mistakes with connected loops are predictable:
- Adding connectors before the local loop is stable
- Giving broad write access too early
- Letting the loop post directly to public channels
- Allowing unrestricted shell commands
- Letting the loop read secrets or private credentials
- Skipping audit logs
- Treating tool access as permanent instead of reviewed
- Allowing scheduled loops to modify production systems
These mistakes usually come from the same assumption: because the loop produced one useful output, it is ready for more autonomy. It is better to treat autonomy as something the loop earns through repeated successful runs.
Tools and connectors are what turn Claude loops from local routines into operational systems. They let the loop inspect the real state of work, prepare follow-ups, and coordinate across tools. But the more real the environment becomes, the more important the boundaries become.
In the next section, we will put everything together into a complete walkthrough: creating the files, running the loop manually, verifying the output, scheduling it with /loop, and deciding when to extend it with tools.
8. Complete Walkthrough: Building Your First Claude Loop
Now we can put the pieces together. The goal of this walkthrough is to build a small Claude loop that is useful, safe, and easy to extend. It will not modify source files, post messages, open tickets, or push code. It will only inspect a workspace, write a daily review report, update persistent state, and stop.
This is the right level of autonomy for a first loop. It proves the pattern without giving Claude broad permissions.
The loop we will build has this behavior:
- Read TASK.md
- Read PROGRESS.md
- Read LOOP_INSTRUCTIONS.md
- Inspect the workspace
- Write outputs/daily-review.md
- Update PROGRESS.md
- Run the verification checklist
- Stop or mark human review required
Once the manual version works, we will schedule it with /loop.
The first complete loop should be boring by design. It should do one useful thing: write to known files, verify its own boundaries, and leave a clear state for the next run.
Step 1: Create the Workspace
Start with a clean folder:
mkdir minimal-claude-loop
cd minimal-claude-loop
touch TASK.md
touch PROGRESS.md
touch LOOP_INSTRUCTIONS.md
mkdir outputs
touch outputs/daily-review.mdYour folder should look like this:
minimal-claude-loop/
├── TASK.md
├── PROGRESS.md
├── LOOP_INSTRUCTIONS.md
└── outputs/
└── daily-review.md
This folder structure is intentionally small. Each file has a specific role:
- TASK.md: Defines what the loop is trying to accomplish.
- LOOP_INSTRUCTIONS.md: Defines how Claude should run the loop.
- PROGRESS.md: Stores state between runs.
- outputs/daily-review.md: Stores the report generated by the loop.
Step 2: Write TASK.md
TASK.md should define the goal of the loop without overloading it with operational details.
Paste this into TASK.md:
# Daily Project Review Loop
## Goal
Review this project folder, summarize what changed, identify blockers, and produce a short daily review report.
## Expected Output
Each run should produce or update:
- `outputs/daily-review.md`
- `PROGRESS.md`
## Scope
Claude may inspect files in this workspace and write reports to the `outputs/` folder.
Claude should not modify source files, delete files, rename files, move files, send messages, open tickets, or interact with external systems during this first version of the loop.This gives the loop a stable purpose. Later, you can extend the scope, but the first version should remain local and controlled.
Step 3: Write PROGRESS.md
PROGRESS.md is the loop's state file. It tells Claude what happened before and what the next run should focus on.
Paste this into PROGRESS.md:
# Loop Progress
## Current State
- Status: Manual setup
- Main objective: Produce a daily project review report
- Current focus: Validate the loop manually before scheduling
- Last updated:
## Last Run
- Date:
- Trigger:
- Summary:
- Files reviewed:
- Output produced:
## Open Items
-
## Blockers
-
## Needs Human Review
-
## Next Run Should
- Read `TASK.md`, `PROGRESS.md`, and `LOOP_INSTRUCTIONS.md`.
- Inspect the workspace.
- Write `outputs/daily-review.md`.
- Update this file before stopping.
## Decisions Made
- The loop starts with local file access only.
- The loop is allowed to write only to `outputs/daily-review.md` and `PROGRESS.md`.
- Scheduling should happen only after stable manual runs.
## Do Not Repeat
- Do not modify source files.
- Do not delete, rename, or move files.
- Do not create extra files unless explicitly instructed.This gives Claude enough memory to continue without relying on the previous chat. The file is also editable by you, which means you can steer the next run by changing the state directly.
A good state file is both a memory and a control surface. It tells Claude what happened, what matters now, what is blocked, and what should not be repeated.
Step 4: Write LOOP_INSTRUCTIONS.md
LOOP_INSTRUCTIONS.md is the operating procedure. It should be explicit because this file will be reused across manual and scheduled runs.
Paste this into LOOP_INSTRUCTIONS.md:
# Loop Instructions
You are running a daily project review loop.
## Before You Start
1. Read `TASK.md`.
2. Read `PROGRESS.md`.
3. Inspect the project folder.
4. Identify what changed, what is incomplete, and what needs human review.
## What You Should Do
Write a short daily review report to:
`outputs/daily-review.md`
The report should include:
- Summary of current project state
- Files or areas reviewed
- Meaningful changes found
- Blockers or unresolved questions
- Recommended next actions
After writing the report, update `PROGRESS.md` with:
- Date of this run
- Summary of what happened
- Files checked
- Output produced
- What the next run should do
- Anything that needs human review
## Safety Rules
- Do not delete files.
- Do not rename files.
- Do not move files.
- Do not modify source files.
- Do not send messages.
- Do not open tickets.
- Do not interact with external systems.
- Only write to `outputs/daily-review.md` and `PROGRESS.md`.
- If you are unsure whether an action is allowed, stop and ask for human review.
## Scheduled Run Policy
When this loop runs on a schedule:
- If there are meaningful changes, write a concise report to `outputs/daily-review.md`.
- If there are no meaningful changes, write a short "No meaningful changes" note.
- If human review is needed, mark it clearly in `PROGRESS.md`.
- If the same blocker appears in two consecutive runs, do not keep retrying. Escalate to human review.
- If verification fails twice, stop and mark the run as not accepted.
- Keep scheduled outputs short unless there is something important to report.
- Do not create extra files unless explicitly allowed.
- Do not modify any files except `outputs/daily-review.md` and `PROGRESS.md`.
## Verification Checklist
Before ending the run, verify the following:
### Required Files
- `outputs/daily-review.md` exists.
- `PROGRESS.md` exists.
### Required Report Sections
`outputs/daily-review.md` must include:
- Summary
- Files reviewed
- Meaningful changes
- Blockers or unresolved questions
- Recommended next actions
### State Update
`PROGRESS.md` must include:
- Date of the current run
- Summary of what happened
- Files checked
- Output produced
- What the next run should do
- Whether human review is needed
### Safety Boundary
Only these files may be modified:
- `outputs/daily-review.md`
- `PROGRESS.md`
If any other file was modified, stop and report the issue.
## Failure Policy
If verification fails:
1. If the failure is a missing section in `outputs/daily-review.md`, fix the report once.
2. If `PROGRESS.md` was not updated, update it once.
3. If any forbidden file was modified, stop immediately and report the issue.
4. If the same verification check fails twice, stop and mark the run as needing human review.This file contains the full loop contract: what to read, what to write, what not to touch, how to behave on a schedule, how to verify the result, and what to do when verification fails.
Step 5: Add Starter Content to the Output File
Paste this into outputs/daily-review.md:
# Daily Review
No loop run has been completed yet.This gives the loop a known output location from the beginning. Claude can overwrite or update it during the run.
Step 6: Run the Loop Manually
Before using /loop, run the workflow manually. This is the most important testing step. Use this prompt in Claude Code or Claude Desktop/Cowork with access to the folder:
Run the daily project review loop for this workspace.
Follow `LOOP_INSTRUCTIONS.md` exactly.
Before acting, read:
- `TASK.md`
- `PROGRESS.md`
- `LOOP_INSTRUCTIONS.md`
Then inspect the workspace, write the daily review to `outputs/daily-review.md`, update `PROGRESS.md`, run the verification checklist, and report what changed.
Do not modify any files except `outputs/daily-review.md` and `PROGRESS.md`.After the run, inspect the two files Claude was allowed to modify:
outputs/daily-review.md
PROGRESS.mdThe daily review should contain a structured report. PROGRESS.md should contain the updated state, including the date, files checked, output produced, next run guidance, and human review status.
Step 7: Run a Separate Verification Pass
During early testing, keep verification separate from execution. This helps you confirm that the loop did not simply claim success.
Use this prompt:
Run a verification pass for the latest loop execution.
Check the output against the Verification Checklist in `LOOP_INSTRUCTIONS.md`.
Report:
1. Which checks passed
2. Which checks failed
3. Which files were modified
4. Whether the run is safe to accept
5. Whether human review is required
Do not modify any files during this verification passThe verification pass should be read-only. It should not correct the files unless you explicitly ask it to. This gives you a cleaner view of whether the loop actually followed the rules.
A good verification result should look like this:
Verification result: ACCEPTED
Passed:
- outputs/daily-review.md exists
- Required report sections are present
- PROGRESS.md was updated
- No forbidden files were modified
Human review required:
- No
A failed verification result should be specific:
Verification result: NOT ACCEPTED
Failed:
- Missing "Blockers or unresolved questions" section in outputs/daily-review.md
Human review required:
- No, this is safe to fix onceOr:
Verification result: NOT ACCEPTED
Failed:
- Forbidden file modified: src/config.ts
Human review required:
- YesThis makes failures visible. A loop that fails clearly is much easier to improve than a loop that silently marks incomplete work as done.
Manual verification is the bridge between a demo and a working loop. The loop should not be scheduled until its output, state update, and safety boundaries are verified across multiple runs.
Step 8: Run the Manual Version Several Times
Do not schedule the loop after one successful run. Test it with small changes.
For example:
Test run 1:
Initial workspace only.
Test run 2:
Add a notes.md file and check whether the loop notices it.
Test run 3:
Add a blocker to PROGRESS.md and check whether the loop carries it forward.
Test run 4:
Add a file inside outputs/ and check whether the loop avoids treating generated outputs as source material.
Test run 5:
Add an unresolved question and check whether it appears under human review.After each run, inspect:
- Did Claude read PROGRESS.md?
- Did Claude update PROGRESS.md?
- Did the report stay concise?
- Did it avoid modifying forbidden files?
- Did it correctly mark human review when needed?
- Did it avoid repeating stale information?This phase is where you tune the loop. If the output is too long, tighten the report format. If Claude misses files, specify what folders to inspect. If the state file becomes noisy, improve its structure. If Claude modifies too much, tighten the safety rules.
Step 9: Schedule the Loop with /loop
After several stable manual runs, schedule the loop.
For a daily cadence:
/loop 24h Run the daily project review loop for this workspace.
Follow `LOOP_INSTRUCTIONS.md` exactly.
Read `TASK.md`, `PROGRESS.md`, and `LOOP_INSTRUCTIONS.md` before acting.
Write the daily review to `outputs/daily-review.md`.
Update `PROGRESS.md` before stopping.
Run the verification checklist.
If there are no meaningful changes, keep the report short.
If human review is needed, clearly mark it in `PROGRESS.md`.
Do not modify any files except `outputs/daily-review.md` and `PROGRESS.md`.For testing, use a shorter interval while you are watching:
/loop 15m Run the daily project review loop for this workspace. Follow `LOOP_INSTRUCTIONS.md` exactly.Use the short interval only to validate behavior. Once the loop is stable, move to the real cadence.
Step 10: Review the First Scheduled Runs
For the first few scheduled runs, treat the loop as supervised. Review each output before trusting it.
Track a few basic signals:
Useful output:
Did the loop produce something worth reading?
Noise:
Did the loop create unnecessary summaries or false alarms?
Missed issue:
Did the loop fail to notice something important?
Boundary respect:
Did the loop only modify allowed files?
State quality:
Did PROGRESS.md remain short and useful?You can add review notes directly into PROGRESS.md:
## Loop Review Notes
- 2026-06-24: Output useful. Report was concise.
- 2026-06-25: Report repeated previous summary. Added instruction to focus on changes since last run.
- 2026-06-26: Missed new file in docs/. Added docs/ to inspection scope.This keeps the loop improvement process visible. The loop is not just running. It is being shaped by evidence from its own runs.
Step 11: Decide Whether to Extend the Loop
After the loop has run reliably for a while, you can decide whether to extend it. Do not add tools only because they are available. Add them when they clearly improve the workflow.
Possible extensions:
Git:
Inspect recent commits and include them in the daily review.
GitHub:
Read open issues, pull requests, and CI status.
Slack:
Draft a daily update, but do not send it automatically.
Linear or Jira:
Read assigned tickets and draft suggested status updates.
Worktree:
Allow code edits only inside an isolated branch or worktree.The safest extension path is:
1. Local file loop
2. Git read-only context
3. GitHub read-only context
4. Draft external updates
5. Human-approved actions
6. Automated low-risk actions only after repeated successEach new capability should come with a new permission rule, a new verification rule, and a review period.
For example, if you add GitHub read access, update LOOP_INSTRUCTIONS.md:
## GitHub Policy
Allowed:
- Read open issues
- Read pull request status
- Read CI status
- Summarize findings in `outputs/github-review.md`
Not allowed:
- Push commits
- Merge pull requests
- Close issues
- Add comments
- Change labels
- Modify milestonesIf you add Slack drafting:
## Slack Policy
Allowed:
- Draft a message in `outputs/slack-draft.md`
Not allowed:
- Send messages
- Mention users
- Post to channels
- Create alertsThis keeps the loop safe as it becomes more useful.
Common Mistakes in the First Loop
Most first loops fail in predictable ways. Watch for these:
- Scheduling before manual testing
- No state file
- State file too long
- No verification checklist
- Vague stop condition
- Broad write permissions
- Too many tools too early
- No human review window
- No audit trail
- Treating the first successful run as proof of reliabilityThe solution is not to make the prompt more clever. The solution is to make the loop more structured.
A useful Claude loop has a small number of reliable parts:
- A clear trigger
- A stable task file
- A persistent state file
- A constrained instruction file
- A predictable output location
- A verification checklist
- A human review path
- A permission boundaryWhen these parts are in place, the loop becomes easier to reason about. You can see what started the run, what Claude read, what it wrote, what it verified, and what should happen next.
What You Have Built
At the end of this walkthrough, you have built a working loop pattern:
Trigger:
Manual prompt first, `/loop` later.
Context:
TASK.md, PROGRESS.md, LOOP_INSTRUCTIONS.md.
Action:
Claude inspects the workspace and writes a daily report.
Verification:
Claude checks required files, required sections, state update, and safety boundaries.
State:
PROGRESS.md records what happened and what should happen next.
Review:
A human inspects outputs before the loop gains more autonomy.This is the foundation for more advanced Claude loops. You can apply the same pattern to CI triage, meeting follow-ups, research monitoring, folder cleanup, documentation review, issue summarization, or draft PR preparation.
The important point is that the architecture does not need to change when the task becomes more advanced. You still need a trigger, context, action, verification, state update, and review boundary. The tools may change. The permissions may expand. The loop may become connected to external systems. But the core design remains the same.
A Claude loop is not just a repeated prompt. It is a controlled workflow that lets Claude keep working with memory, boundaries, and verification. That is the practical shift from prompting to loop engineering.
The main shift in Claude loop engineering is that the prompt is no longer the whole system. A prompt gives Claude one instruction. A loop defines the environment around that instruction: when it runs, what context it reads, what files or tools it can touch, how the result is checked, what state survives, and when a human needs to review the output.
That shift matters because many useful tasks are not single-turn tasks. Project reviews, CI triage, folder cleanup, meeting follow-ups, issue summaries, documentation checks, and recurring research workflows all benefit from continuity. Claude can perform the work inside each run, but the loop is what gives the workflow memory and structure across runs.
The safest way to build the first loop is to keep it small. Start with one task, one instruction file, one state file, one output location, and one verification checklist. Run it manually before scheduling it. Inspect the output. Update the instructions. Run it again. Only after the loop behaves consistently should you schedule it with /loop.
The same principle applies when adding tools and connectors. A local loop should become reliable before it becomes connected. External tools such as GitHub, Slack, Linear, Jira, databases, or CI systems make the loop more useful, but they also expand the risk. Start with read-only access, then draft outputs, then sandbox edits, and only move toward write actions after repeated successful runs and clear human review points.
The practical architecture stays simple:
Trigger → Context → Action → Verification → State → Review
The tools can change. The cadence can change. The permissions can expand. The loop may eventually read from GitHub, draft Slack updates, inspect CI failures, or work inside an isolated branch. But the core structure should remain the same.
A reliable Claude loop does not depend on trusting the model blindly. It depends on clear boundaries: persistent state, explicit instructions, objective verification, narrow permissions, auditability, and human approval where the action is risky. This is what turns Claude from a one-off assistant into part of a repeatable workflow.
The goal is not to stop thinking or hand over responsibility. The goal is to move your attention to a higher level: selecting the right recurring task, designing the loop, reviewing the outputs, tightening the rules, and deciding when the system has earned more autonomy.
That is the practical difference between prompting Claude and engineering loops with Claude.
I explained the complete framework through practical, hands-on examples in my latest course, Hands-On Loop Engineering with Claude.
The course includes 9 lessons, along with:
- An 117-page companion book, How to Create Loops with Claude Code
- Three complete, runnable loop projects, including an event-triggered loop that monitors a GitHub repository and reports only when the branch head actually changes
- The complete 247-slide presentation course deck
The course takes you from the core concepts behind loop engineering to building reliable, persistent, and verifiable workflows with Claude.