Understanding the Difference Between /loop and /goal in Claude Code Agents

After years of R&D, many repetitive tasks—such as SDK version upgrades, feature‑flag clean‑up, dependency scanning, and CI failure handling—span code, Git, CI, deployment platforms, logs, monitoring, and team collaboration. Purely manual judgment or simple scripts cannot reliably cover all cases, which is where autonomous agents excel.

For example, an agent can run every Friday to scan core repositories, locate old SDK calls, assess upgrade impact, modify code, run unit and integration tests, and open a PR for low‑risk changes while leaving a rationale for high‑risk ones. However, when the agent returns, the environment may have changed: a CI job that turned red could be due to a Redis outage, or a PR awaiting review may have been merged three times since the last run.

Claude Code distinguishes two concepts: /goal and /loop. /goal defines *what* counts as finished—an acceptance‑criteria card that is evaluated each round. /loop defines *when* the agent should revisit the task, turning a time trigger into a scheduled execution. /goal does not execute commands; it merely records the desired end state. Completion is granted only when concrete evidence—such as a test‑run output, a remote build receipt, or a PR status—matches the criteria. The model cannot decide “it looks good” without verifiable proof. /loop has the syntax /loop [interval] <prompt>. If no interval is given, the default is 10m. Supported units are s, m, h, and d, and the parser also accepts forms like 5m or every 20m. After parsing, the interval is converted to a five‑field cron expression and handed to CronCreate to create the scheduled task. /loop [interval] <prompt> The prompt is executed immediately; the first run does not wait for the cron trigger. For example, /loop 30m check the deploy means “run the check now, then repeat every 30 minutes.” If only /loop 5m is supplied, the command shows usage and does not create a task because the prompt is empty.

Two durability modes exist. durable: false keeps the task in the current Claude process memory and disappears on exit. durable: true writes the task to .claude/scheduled_tasks.json, allowing it to survive restarts. By default, durability is on, but only tasks explicitly marked as permanent avoid the automatic 7‑day expiration (with a jitter of up to 10 % of the interval, capped at 15 minutes).

When a scheduled task is missed because Claude was offline, the runtime marks it as missed and lets the upper layer decide whether to replay it now or discard it. Loop tasks never “catch up” one‑by‑one; they recompute the next execution time from the current clock.

Execution respects several switches: the build‑time list AGENT_TRIGGERS, the runtime flag tengu_kairos_cron, and the environment variable CLAUDE_CODE_DISABLE_CRON, which can disable the entire scheduler. Ongoing tasks poll these switches each cycle, and a disabled flag stops further triggers.

To reason about task completion, the article proposes three layers of state:

Model context : the current round’s file snippets, command‑output summaries, and next‑step hints.

Harness run record : tool calls, parameters, start/end timestamps, timeouts, interruptions, retries, and the current execution pointer.

External facts : Git commits, PR status, build receipts, channel messages, approvals, and final business‑logic results in the database.

Only when all three layers agree can a /goal be considered satisfied. For instance, after scanning services/* and jobs/*, the agent must verify which commit the scan belonged to, whether a draft PR was actually created, and whether the responsible reviewer has responded.

Typical scenarios suitable for /loop include stable‑input tasks with a clear frequency and verifiable outcomes: SDK version compatibility checks, dead‑code detection, documentation‑link validation, and test‑coverage gap reporting. Each round should leave a concrete artifact—such as a commit, a report, or a checklist—so the next round can continue from that evidence.

When models become more capable, the harness can be “thinned”: hard‑coded step‑by‑step scripts may be removed, allowing the model to decide whether to search a directory, open a file, or run a command. However, facts that require authority, audit trails, or irreversible actions (e.g., repository scope, branch protection, credential checks, deployment approvals) must remain in the system, not left to the model’s intuition.

Practical advice: start with a small, well‑defined baseline task, separate the “continuation right” (what to do next) from the “trigger right” (when to run again), and encode acceptance criteria directly in the /goal. Ensure every loop records enough evidence to be audited later, and avoid automating decisions that still need human judgment, such as large‑scale data migrations or financial operations.

References:

Boris Cherny: “We Cut 80% of Claude Code’s Prompt” – Y Combinator

Boris Cherny: “Building Claude Code” – Y Combinator Library

Anthropic’s Boris Cherny: “Why Coding Is Solved, and What Comes Next” – Sequoia Capital

Claude Code official docs – “Keep Claude working toward a goal”

Claude Code official docs – “Run prompts on a schedule”

OpenAI Codex official docs – “Follow a goal”

GitHub – goals.rs source

Addy Osmani – “Loop Engineering”

Addy Osmani – “Practical Loop Engineering”

Addy Osmani – “Long‑running Agents”