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 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.
- 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
$loopskill. - A dry-run CLI path that writes state without changing source files.
- A
loop runcommand that can hand an objective to Codex or Claude Code after agent selection and optional goal clarification. loop wikicommands for listing, reading, opening, and serving local human-readable run notes.
Install Loop once:
npm install -g github:rlaope/loop
loop --versionCreate 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".
codexclaudecode
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 --followloop 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 wikiloop wiki starts and opens a localhost-only dashboard for .loop/wiki. The
markdown note under .loop/wiki/user is canonical; AI memory, index, and graph
files are derived from it. 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.
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 typecheckAfter 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/loopInstall 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.
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.
- Loop Engineering concept
- Compatibility matrix
- Safety model
- Issue-to-commit map
- Roadmap
- Dry-run maintenance example
npm install
npm test
npm run lint
npm run typecheckBuild the loop, stay the engineer.