The Six Building Blocks of a Loop¶
Addy Osmani frames every well-designed loop around six components in his June 2026 post "Loop Engineering" — building on the shift from prompting to loop design voiced by Peter Steinberger ("you shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents") and echoed by Boris Cherny, head of Claude Code at Anthropic ("I don't prompt Claude anymore ... my job is to write loops", Acquired Unplugged, presented by WorkOS, Jun 2026).
1. Automations (local) and Routines (cloud)¶
What triggers the loop: a cron/schedule, a GitHub event, a Slack message, a CI failure, a file watcher. The loop starts because something happened, not because you typed.
# Local: run Claude from GitHub Actions on every push
claude -p "$(cat .claude/prompts/review.md)" --permission-mode auto
Routines (a research preview — behavior, limits, and the API surface may change) extend automations to the cloud: Anthropic-hosted loop execution that runs without your machine. Three trigger types — Schedule (cron), API (webhook), and GitHub events (PR open/close, Release). Your laptop can be off; the loop runs.
# Inside a Claude Code session:
/schedule # create a scheduled Routine, or attach a GitHub trigger (CLI needs v2.1.225+);
# API triggers must be added on the web at claude.ai/code/routines
See Routines for the full model.
Source: Routines reference — research-preview
status, the three trigger types, the API-trigger-is-web-only rule and the v2.1.225 CLI floor
for GitHub triggers all confirmed there; cross-checked against claude --version 2.1.263,
2026-09-06.
2. Worktrees¶
Parallel work in isolated git checkouts so edits from different loop instances do not collide. Each worktree is its own sandbox.
git worktree add .worktrees/feature-auth -b feature/auth
# Run a Claude session inside it
claude --permission-mode auto -p "implement OAuth in this worktree"
The built-in flag: claude --worktree¶
git worktree add is the manual path. claude --worktree <name> (short -w) does the same setup
and then enforces the isolation, which the manual path cannot.
| Behaviour | Contract |
|---|---|
| Path | .claude/worktrees/<name>/ at the repository root |
| Branch | worktree-<name> |
| No name given | Claude generates one, e.g. bright-running-fox |
| From a PR/MR | --worktree "#1234", a GitHub pull request URL, or a GitLab merge request URL → worktree at .claude/worktrees/pr-<number>, branched from that change's head commit fetched from origin |
| Base ref | worktree.baseRef takes fresh or head only — never a branch name; default is fresh, so --worktree, EnterWorktree, and agent-isolation worktrees branch from origin/<default-branch>, not local HEAD (since v2.1.133) — unpushed local commits on your current branch are silently absent from a fresh worktree unless you set worktree.baseRef: "head". To start from a specific branch, create it with git directly |
Which ref gets fetched depends on the host origin points at:
| Host | Ref fetched |
|---|---|
github.com |
pull/<number>/head |
gitlab.com |
merge-requests/<number>/head |
| GitHub Enterprise, self-managed GitLab, any other host | tries pull/<number>/head first, then merge-requests/<number>/head |
Before v2.1.233, --worktree accepted only #<number> and GitHub-style PR URLs, and always
fetched pull/<number>/head.
--tmux (requires --worktree) opens a tmux session for the worktree — iTerm2 native panes when
available, --tmux=classic for traditional tmux. It is in the
CLI reference and claude --help, but not on the
worktrees page.
.worktreeinclude — getting .env into the worktree¶
A worktree is a fresh checkout, so gitignored files such as .env and .env.local are not there.
A .worktreeinclude file at the project root copies them in whenever Claude creates a worktree.
- Uses
.gitignoresyntax. - Only files that match a pattern and are gitignored are copied — tracked files are never duplicated. So yes: this is the supported way to get real secrets into the worktree, and it puts a second copy of them inside the repo tree. Know that before pointing an unattended loop at it.
- Applies to every worktree Claude Code creates with git:
--worktreeworktrees, subagent worktrees, and parallel sessions in the desktop app. - Not processed when a
WorktreeCreatehook replaces the default git logic (non-git VCS) — copy the files inside the hook script instead. - A
**/pattern reaches into a wholly-gitignored directory only when that directory itself matches the pattern, or the first name after the**/is one of the names in the directory's path. Name the directory instead:vendor/**/config.json, not**/config.json.
Resume and cleanup¶
| Situation | What happens |
|---|---|
| Resume a session that was in a worktree | The session returns to that worktree — interactive resume, --continue and --resume with -p, and the Agent SDK. Claude can still leave with ExitWorktree |
| Exit, worktree clean, unnamed session | Worktree and branch removed automatically |
| Exit, worktree clean, named session | Prompts first, so you can keep it |
| Exit, worktree has work (changed or untracked files, or new commits) | Prompts to keep or remove. Removing deletes the directory and branch with everything in them |
-p run |
No exit prompt and no cleanup. The lock taken at creation stays until a later session's stale-lock sweep. Remove with git worktree remove; if git refuses because it is locked, git worktree unlock first |
A periodic sweep also removes worktrees Claude created for subagents and background sessions once
they are older than your cleanupPeriodDays setting. Separately, claude rm <id> deletes a
background session "and its worktree when that is safe", including for sessions that have already
exited (claude --help; not documented on the worktrees page).
Do not assume the sweep covers your case. On 11 Aug 2026 the creator of Claude Code described handling this himself, in full:
Worktrees can be rough when they pile up. I use a loop to clean up stale worktrees. Should we build this into Claude Code?
— Boris Cherny (@bcherny), 11 Aug 2026.
Read narrowly, that is one practitioner's setup and an open product question — not proof the
built-in sweep was absent or inadequate. Read for what it is good for: the sweep above is scoped to
worktrees Claude created for subagents and background sessions, so worktrees you create with
git worktree add are outside it, and a cleanup loop of your own is the documented-by-example
remedy. The numeric default of cleanupPeriodDays is still unpublished — logged as V4 in
KB_GAPS.md; publish no day count until someone reads it.
Four isolation checks — enforcement, not convention¶
While a session is in a worktree, Claude Code applies four checks:
| # | Check | What it blocks |
|---|---|---|
| 1 | File edits | An Edit, Write, or NotebookEdit that targets a path in the main checkout |
| 2 | Command working directory | A Bash, PowerShell, or Monitor command whose working directory resolves to the main checkout, or whose working directory it can't verify stays outside it |
| 3 | Git redirects | A Bash or Monitor command that redirects git into the main checkout — via git -C, --git-dir, a GIT_DIR or GIT_WORK_TREE variable, or a cd into the main checkout before running git |
| 4 | Command shape | A Bash or Monitor command whose text can't be verified to keep git inside the worktree — a command name computed at runtime, or syntax that can't be parsed. Claude Code tells Claude how to rewrite it, such as splitting it into plain, separate commands |
(Monitor is the tool that "runs a command in the background and feeds each output line back
to Claude, so it can react to log entries, file changes, or polled status mid-conversation" —
Tools reference. It executes commands, so the worktree
checks, the session command cap and the permission rules treat it alongside Bash and
PowerShell.)
Scope, exactly:
- The checks cover the repository Claude Code was launched from, and the main checkout that a linked worktree is linked from.
- PowerShell commands get check 2 only.
- The same enforcement covers every subagent spawned from the isolated session, interactive or background; subagents running in their own worktree carry the same checks.
- "You can't turn this check off" is stated for check 4 only. The reference attaches it to Command shape, not to the set of four — don't quote it as if all four were undisableable.
Why this is the interesting part. A repo convention like this one's — "Always work in a git
worktree — never in the primary checkout" — is prose in a CLAUDE.md. It holds only while the
agent reads it, retains it through a long session, and resolves an edge case the way you would; a
subagent three layers down may never have seen it. --worktree converts the same rule into a
property of the harness: an Edit at the wrong path is refused, not discouraged, and the refusal
propagates to every subagent below without being restated. That is the difference between a STOP
condition stated in the prompt and one enforced by the runtime — the same distinction as
permissions.deny versus "please don't push to main". Where a constraint actually matters, take
the mechanical version and keep the prose for what the harness cannot check. See
Permissions and The Loop Contract.
Gotchas¶
| Gotcha | Detail |
|---|---|
| Workspace trust | Interactive --worktree needs trust already accepted in that directory — run claude once there first, or it exits with an error. -p skips the trust check |
| Symlinks | Creation is refused when .claude, .claude/worktrees, or the worktree directory itself is a symlink, and the error names the path. Before v2.1.212 it followed a committed symlink and could create files outside the repository |
| Git LFS | With git lfs install --local, a Claude-created worktree holds LFS pointer files: Claude Code deliberately skips the repository's filter drivers, because a filter driver is a shell command and anything that can write to the repo could have put one there. Run git lfs pull inside the worktree |
| Shared state | A worktree shares the repository's .git, project-scope plugins, and saved permission approvals with the main checkout. "Yes, and don't ask again" for a Bash command saves to the main checkout's .claude/settings.local.json (v2.1.211+), applies everywhere in the repo, and survives the worktree's removal |
EnterWorktree prompt |
Entering a path outside .claude/worktrees/ always asks first — it moves the session's working directory, write access, and project config. An EnterWorktree allow-rule or "don't ask again" does not suppress it; only bypassPermissions does. Before v2.1.206 Claude could enter any existing worktree path without asking |
| Non-git VCS | Worktrees require a git repository; other version control systems need WorktreeCreate/WorktreeRemove hooks replacing the git logic entirely |
Background sessions compose with all of this: claude --bg --worktree <name> "<task>" gives each
worker its own enforced sandbox — pass the worktree name explicitly, because --worktree [name]
takes an optional value and will otherwise swallow the prompt as the name (reproduced on 2.1.263:
state: failed, "Error creating worktree: Invalid worktree name", no worktree created) — see Background Agents.
Source: worktrees reference,
CLI reference, and
settings reference; cross-checked against
claude --version 2.1.261, 2026-09-05.
3. Skills¶
Reusable, invokable workflows packaged as .claude/skills/<name>/SKILL.md files.
Skills give Claude domain knowledge and step-by-step procedures it can execute on
command — without bloating CLAUDE.md.
<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true
---
Fix GitHub issue: $ARGUMENTS
1. `gh issue view $ARGUMENTS` — understand the problem
2. Search codebase for relevant files
3. Implement the fix
4. Write tests, run them, fix failures
5. Lint and typecheck
6. `git commit` with descriptive message
7. `gh pr create`
Invoke it: /fix-issue 1234
Source: Skills reference — the SKILL.md layout and
disable-model-invocation: true confirmed there; cross-checked against claude --version
2.1.263, 2026-09-06.
When skills beat subagents. Anthropic's own commerce-agent reference architecture chooses skills over domain-specific subagents by default: "a commerce conversation is one tightly coupled session across multiple intents and turns, and requires considerable shared context," and a subagent handoff is a "state-lossy operation" that loses that context — a concrete counter-example to reflexively reaching for subagents whenever a task looks delegable. A companion heuristic for what goes where: content relevant to roughly a third or more of traffic belongs in the system prompt; everything else goes in a skill. (Anthropic, "A guide to the anatomy of effective commerce agents", Sep 2026; reference implementation: anthropics/commerce-agents, Sep 2026 — the same agent definition (prompt, skills, tool contracts) runs unmodified across the Messages API, the Agent SDK, and Managed Agents.)
4. Plugins / Connectors¶
MCP servers that give the loop access to external systems: databases, browsers, APIs, Linear, Figma, Slack, GitHub. Add them once, and every loop session inherits the tools.
Plugins can also carry mods, TypeScript functions that hook Claude Code's own events (tool calls, permission requests, screen draws) and are not sandboxed — see Hooks § Beyond hooks: mods and the announcement (1 Oct 2026).
# `name` and `commandOrUrl` are both required — there is no interactive form
claude mcp add my-server -- npx my-mcp-server # stdio (default transport)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp # HTTP
claude mcp add --scope user my-server -- npx my-mcp-server # all projects (default: local)
Chrome extension — authenticated web access¶
The Chrome integration (claude --chrome) is a first-class connector that gives the
loop access to any site you're already logged into — including X/Twitter, Google
Docs, Notion, Linear, and internal tools — without API keys or MCP setup.
claude --chrome
# then:
> "Go to x.com, open this tweet: <url>, and extract the full thread text"
> "Monitor my X notifications every hour and summarise new replies"
> "Read this GitHub discussion and pull the key decisions into DECISIONS.md"
Key properties: - Shares your browser's existing login session — no OAuth setup - Browser actions run in a visible Chrome window (you can watch) - Claude pauses and asks you to handle CAPTCHAs or login walls manually - Works with Chrome, Edge, and other Chromium-based browsers (Brave, Arc, Vivaldi, Opera); not supported on WSL - Requires a direct Anthropic plan (Pro/Max/Team/Enterprise); not available via Amazon Bedrock, Google Cloud's Agent Platform (formerly Vertex AI), or Microsoft Foundry
# Enable by default so every session has browser access
# Run /chrome → "Enabled by default"
# Or per-session
claude --chrome -p "go to x.com/mikenevermiss and extract his last 5 posts about Claude"
For scraping research inputs into a loop: this is the cleanest path — navigate directly, extract text, write it to a local file, then pipe it into your loop prompt.
Source: Chrome reference — the shared login session,
visible window, CAPTCHA pause, the Chromium browser list (Brave, Arc, Vivaldi, Opera), the WSL
exclusion and the direct-plan requirement (not Bedrock, Google Cloud's Agent Platform, or
Microsoft Foundry) all confirmed there; claude mcp add's required name argument reproduced
on the CLI. Cross-checked against claude --version 2.1.263, 2026-09-06.
5. Sub-agents¶
Isolated Claude sessions spawned from the parent loop to handle focused subtasks. Each subagent starts with a fresh context window — it does not see the parent's turns. Only its final summary returns to the parent. Use sub-agents for:
- Investigation (reads many files without polluting parent context)
- Verification (a reviewer that never saw the code it's judging)
- Parallel work (multiple agents working on independent parts simultaneously)
Use a subagent to review the diff in @src/auth/ for edge cases.
Report only issues that affect correctness, not style preferences.
Define a specialized subagent in .claude/agents/:
<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: Audits code for injection, auth flaws, and secrets
tools: Read, Grep, Glob, Bash
model: claude-sonnet-5
---
You are a senior security engineer. Flag: SQL/XSS/command injection,
auth/authz flaws, secrets in code, insecure data handling.
Provide file:line references and suggested fixes.
Source: Sub-agents reference — name and
description required, tools and model optional, confirmed in its frontmatter table;
cross-checked against claude --version 2.1.263, 2026-09-06.
6. Memory¶
State that survives across conversations. Without memory, every loop starts blind. Memory is anything that lives outside a single conversation:
- A markdown file committed to the repo (
PROGRESS.md,PLAN.md) - A GitHub issue or project board
- A Linear ticket
- A file the loop writes at the end of each run