Claude Code Loop Hierarchy: From Self‑Check to Unattended Four‑Tier Control

Loop definition

In Claude Code a Loop is an Agent that repeatedly executes a work cycle until a stop condition is satisfied.

Control‑delegation tiers

Turn‑based : the system receives the right to check results; a human decides whether to start the next round.

Goal‑based : the system receives the right to continue/stop based on a goal; a human defines the goal and budget boundaries.

Time‑based : the system receives the right to trigger on a schedule; a human defines rhythm, scope and lifecycle.

Proactive : the system receives the right to domain execution; a human manages permissions, audit, upgrade and downgrade policies.

Why the tiers matter

If a team enables a Loop without first writing clear inspection criteria (for example a /goal definition), the Agent may repeat uncertain work, producing noisy or unsafe outcomes. Unstable lower‑tier capabilities amplify problems when higher‑tier loops are added.

Tier‑by‑tier analysis

Turn‑based loop

Typical workflow: a prompt asks Claude to read code, modify files, run tests, and report results. The human still drives the next round. Embedding manual checks into a SKILL.md file (e.g., launch the page, operate key controls, capture console output or performance traces) makes the Agent aware that “completion” includes verification, not just code changes. The key signal at this tier is the ability to distinguish “modified” from “verified” and to leave evidence (logs, screenshots, diffs) when a check fails.

Goal‑based loop

The /goal command hands over the decision of whether to continue. A human writes a concrete goal with explicit success criteria and boundaries (e.g., “Lighthouse performance ≥ 90, max 5 attempts, no API changes”). An evaluator model checks only evidence already present in the transcript. Adding round or time limits (e.g., “stop after 20 rounds”) prevents open‑ended consumption. Suitable tasks have observable outcomes that can be judged from evidence, such as all tests passing or a migration compiling without errors. Vague wishes (“optimize the page”) are not appropriate; they must be expressed as condition‑based goals (“raise Lighthouse score to 90, ≤ 5 attempts, preserve existing interactions”).

Time‑based loop

Time‑based loops address situations where work may need attention without a prompt, such as new PR review comments, CI failures, or deployment status changes. The /loop or /schedule command runs a prompt at a defined interval within the current session, with a 7‑day expiration for recurring tasks. Before enabling a time‑based loop, three questions must be answered: how often does the external signal change, can empty runs be tolerated, and what is the maximum handling depth. The loop should stop after a configurable number of empty runs and should be upgraded to event‑driven triggers only after the sampling rate is tuned to avoid noise or missed signals.

Proactive loop

Proactive loops combine scheduling, goal definition, Skills, and dynamic workflows to orchestrate multiple sub‑agents. The workflow is expressed as JavaScript generated by Claude, which can invoke sub‑agents, persist state, and be replayed. Because the system now holds domain execution rights, additional safeguards are required: isolated identities, minimal permissions, audit logs, cost caps, and a manual escalation path. Suitable domains are high‑repeatability, well‑bounded tasks such as issue triage, dependency‑upgrade candidates, low‑risk documentation drift, or fixed‑format reporting. High‑risk domains (production configuration, billing logic, permission changes) should be deferred until lower tiers are stable.

Upgrade path and downgrade signals

Each step up the ladder should be gated by concrete evidence: test results, logs, screenshots, diffs, and explicit failure boundaries. If evidence stops arriving, the Loop is likely stuck and should be downgraded. Downgrading is a safety mechanism, not a regression.

Trial‑run strategy

Week 1: start with a small turn‑based Loop (e.g., monitor a low‑risk PR). Ensure the Agent can reliably self‑check via Skills.

Week 2: add a narrow /goal (e.g., all tests pass, lint has no new errors, only test‑related changes allowed, max 5 attempts, report unresolved items on failure).

Week 3: introduce a time‑based Loop (e.g., poll PR status every 20 minutes, handle only low‑risk review comments and CI failures, stop after several empty cycles).

Week 4 +: evolve into a routine or proactive workflow, adding independent identity, minimal permissions, execution logs, cost limits, and a manual escalation path.

Key insight

Loop Engineering shifts the focus from “can the model write code?” to “how should control be handed over safely?” The four tiers provide a structured way to progressively delegate control while ensuring verification, boundaries, and rollback mechanisms at each level.

References

Anthropic / Claude Blog – Getting started with loops Claude Code Docs – Keep Claude working toward a goal Claude Code Docs – Run prompts on a schedule Claude Code Docs – Orchestrate subagents at scale with dynamic workflows Addy Osmani – Loop Engineering Lenny's Newsletter / Claire Vo –

How to write AI agent loops in Claude Code and Codex