Loop

Recursive goals for coding agents that need memory, budgets, and stopping rules.

Loop is a safety-first Loop Engineering toolkit for coding agents.

Instead of prompting an agent every turn, define a purpose and let the loop drive the agent through intake, planning, discovery, isolation, action, verification, memory, and stopping rules.

The MVP proves the shared core and Codex $loop adapter first. Claude Code /loop, connectors, scheduled write automation, and marketplace distribution are roadmap work after the core contract is stable.

Built by @rlaope · Art & Engineering

Loop Engineering Components

Loop is built around six working components:

• Automations: repeatable read-only discovery, triage, and scheduled checks.
• Worktrees: isolated branches or directories for code-changing work.
• Skills: durable workflow instructions such as $loop.
• Plugins/connectors: distribution and optional external context surfaces.
• Sub-agents: delegated maker/checker or specialist lanes.
• Memory: markdown, JSON state, or issue boards that survive one chat session.

What Ships In The MVP

• Durable local memory in .loop/runs/*.json, .loop/runs/*.md, and .loop/latest-runs.json.
• Loop Wiki second-brain storage in .loop/wiki/user/*.md, .loop/wiki/ai/*.json, .loop/wiki/index.json, and .loop/wiki/graph.json.
• A shared run-state schema with objective, phase, budget, stop condition, verification evidence, approval state, and next action.
• Budget and stop-condition helpers for bounded agent loops.
• Repo-boundary and isolation preflight helpers for code-changing work.
• A Codex plugin manifest and $loop skill.
• A dry-run CLI path that writes state without changing source files.
• A loop run command that can hand an objective to Codex or Claude Code after agent selection and optional goal clarification.
• loop wiki commands for listing, reading, opening, serving, deleting, and adding local second-brain notes.

Quickstart

Install Loop once:

npm install -g github:rlaope/loop
loop --version

Create or enter the project you want the coding agent to work on:

mkdir darkwear-exhibit
cd darkwear-exhibit
loop "Build a darkwear luxury exhibition site"

If the folder is not a git repository yet, loop initializes a local git repository there first. That keeps write-capable agent work bounded to the folder you started from, even when the folder lives inside a larger parent repo.

loop "prompt" asks you to type 1 or 2 to choose the prototype agent. The explicit form is loop run "prompt".

• codex
• claudecode

You can skip the picker by passing the agent explicitly:

loop run --agent codex "Build a darkwear luxury exhibition site"
loop run --agent claudecode "Build a darkwear luxury exhibition site"

If you want to try Loop without installing it first:

npm exec --yes --package github:rlaope/loop -- loop "Build a darkwear luxury exhibition site"

If Loop says the git root does not match, you probably passed an explicit --expected-root that does not match the current project. Run Loop from the folder you want the agent to edit, or pass the intended root explicitly.

If the prompt is too ambiguous for a loop, the CLI asks a short deep-interview style set of questions in the terminal, closes the interview, records the clarified objective, and then starts the selected coding agent.

When a Loop Wiki dashboard is already running, loop "prompt" and loop run open it automatically. If it is not running in an interactive terminal, Loop asks whether to start it; choosing Yes starts the localhost dashboard and opens it in your browser.

While an agent is running, Loop writes a live session record and log under .loop/runs. You can inspect the run from another terminal:

loop status
loop runs
loop logs --follow

loop status shows whether a Codex or Claude Code process is currently alive. loop runs lists previous sessions. loop logs <run-id> prints a captured agent log, and loop logs --follow streams the latest run log.

Running the same objective again creates a new run session. Older sessions are not reactivated; they remain in history and related wiki notes are connected in the graph view.

Dry-run mode is still available when you only want durable state and a wiki note without source edits:

loop --dry-run --objective "Build a darkwear luxury exhibition site"

Read the generated second-brain notes locally:

loop wiki list
loop wiki read <note-id>
loop wiki open <note-id>
loop wiki delete <note-id>
loop wiki

loop wiki starts and opens a localhost-only dashboard for .loop/wiki. The main run note under .loop/wiki/user is canonical for the loop session; AI memory, index, and graph files are derived from the local wiki. loop run does not start the dashboard in non-interactive automation unless --wiki-dashboard is passed. Most users can ignore that flag and open the dashboard later with loop wiki. The dashboard also includes note delete buttons and links from each note to the run log.

A loop is not limited to one markdown file. The run note is the parent context, and you can attach multiple implementation plans, verification findings, decisions, references, or ideas to the same run:

loop wiki add --kind plan --title "Implementation plan" --body "Build the gallery first, then verify responsive spacing."
loop wiki add --kind verification --title "QA findings" --body "Mobile product cards need another pass."
loop wiki add --kind idea --title "Curation angle" --body "Group pieces by silhouette instead of brand."

If you need to attach a note to a specific session, pass --run <run-id>. If you omit it, Loop attaches the new note to the latest run note in the local wiki.

To remove a run-state session and its captured log:

loop runs delete <run-id>

To verify the package:

npm install
npm test
npm run lint
npm run typecheck

After the package is published to npm, the shorter registry form will be:

npx @rlaope/loop "Build a darkwear luxury exhibition site"
npx @rlaope/loop run "Build a darkwear luxury exhibition site"
npx @rlaope/loop --dry-run --objective "Build a darkwear luxury exhibition site"
npm install -g @rlaope/loop

Codex Usage

Install or load this repository as a Codex plugin source, then invoke:

$loop <objective>

The skill tells the agent to record durable state, check repository boundaries, choose an isolation mode, enforce budgets, and keep maker/checker separation.

Safety Defaults

Loop is not an excuse to stop engineering. It is a way to make agent repetition observable and bounded.

• Every loop needs a budget and stop condition before work starts.
• Code-changing loops need a worktree, branch, or explicit local-mode acknowledgement.
• MVP automations are read-only or triage-only unless durable human approval exists.
• Passing tests are evidence, not proof that the human no longer owns the result.

Docs

• Loop Engineering concept
• Compatibility matrix
• Safety model
• Issue-to-commit map
• Roadmap
• Dry-run maintenance example

Development

npm install
npm test
npm run lint
npm run typecheck

Build the loop, stay the engineer.