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.
• Optional local Obsidian filesystem sync for the human-facing .loop/wiki/user/*.md notes. AI memory JSON, index, graph, and logs remain local Loop artifacts.
• 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.
• Best-effort desktop notifications on macOS, Windows, and Linux when a run starts, needs human attention, or finishes and needs review.
• A no-argument loop Prompt Console with keyboard-first navigation: move between prompt, runs, selected run, status, and actions with Tab/arrows, then press Enter to open run pickers, action menus, confirmations, notes, logs, wiki context, Obsidian sync settings, follow-up prompts, agent choice, and Codex resume actions.
• loop wiki commands for listing, reading, opening, serving, deleting, and adding local second-brain notes.
• A localhost-only global Loop Wiki dashboard that indexes registered projects from ~/.loop/projects.json, then opens per-project graph views, markdown notes, live log pages, token-confirmed local actions, follow-up command preparation, and Codex terminal actions.

Quickstart

Install Loop once:

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

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, starts or opens the localhost Loop Wiki dashboard, then opens the Prompt Console processing view in the same terminal. The agent output is captured in the run log while the TUI shows the current run state, selected agent, wiki dashboard status, next action, graph count, and live log tail. When the agent exits, Loop finishes the state/wiki update and leaves you in the normal Prompt Console.

Use loop run "prompt" when you want the older explicit CLI stream that prints agent output and returns JSON for scripts. If you like the short command but want to skip the processing TUI for one run, use loop "prompt" --just-run.

• 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"
loop --agent codex "Build a darkwear luxury exhibition site" --just-run

After at least one run exists, typing only loop in an interactive terminal opens the local Prompt Console TUI. Use Tab/Shift+Tab to move between sections, the arrow keys to move within a section, Enter to open/select, and Esc to back out of overlays. The prompt box stages a new objective or connected follow-up; the run stack and action menu let you select a run, read wiki context, tail logs, add two-field notes, record verification, confirm completion, open the dashboard, switch agent choice, or open/resume Codex in a new terminal tab when a concrete Codex session id has been recorded. Follow-up commands include --parent-run lineage so the next loop remains connected to the previous run. In non-interactive shells, no-argument loop prints guidance instead of waiting for input.

If you want to try Loop without installing it first:

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

Before a first real run, loop doctor checks the local Node.js, git, package, repo-boundary, and optional agent CLI readiness without writing .loop, launching agents, starting the dashboard, or calling the network. loop demo prints a small command catalog for common first-run, explicit-agent, and dry-run follow-up workflows; it is also read-only.

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. Direct loop "prompt" starts it automatically because the processing TUI expects live Wiki observability. Explicit loop run "prompt" keeps the older CLI stream behavior and asks before starting the dashboard in an interactive terminal. In non-interactive automation, pass --wiki-dashboard if you want the dashboard process started.

Interactive CLI runs also send best-effort system notifications when the agent starts, when Loop needs human attention, and when the agent finishes and needs review. Disable them with --no-notify or LOOP_DISABLE_NOTIFICATIONS=1; use LOOP_FORCE_NOTIFICATIONS=1 for non-interactive shells.

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 the localhost-only global dashboard. The home page is intentionally not tied to only the current folder: it reads the global project registry at ~/.loop/projects.json and shows every registered Loop project on one screen. Running loop "prompt", loop run, or loop wiki from a project registers that project. Click a project card to open its project-scoped Wiki under /projects/<id>.

The main run note under each project's .loop/wiki/user directory is canonical for that loop session; AI memory, index, and graph files are derived from that local wiki. CLI commands such as loop wiki list, loop wiki read, and loop wiki add still operate on the current project's .loop unless you pass --state-dir.

Optionally mirror the human-facing Loop Wiki markdown into an Obsidian vault:

loop wiki obsidian status
loop wiki obsidian init --vault ~/Documents/MyVault
loop wiki obsidian sync
loop wiki obsidian watch --interval 2000
loop wiki obsidian install-service

status is read-only and can auto-detect local folders that contain .obsidian. init creates a project-scoped mirror under <vault>/Loop/<project-name>-<project-id>/, so different projects with the same folder name do not collide. sync is bidirectional for markdown content edits in .loop/wiki/user/*.md; when Obsidian edits are imported back into Loop, the AI memory, index, and graph are regenerated from the markdown. Delete and rename propagation is intentionally not part of the MVP: if an Obsidian mirror file is missing, Loop restores it from the canonical .loop/wiki/user note. Delete notes through Loop commands or the local dashboard when you want Loop state to change. If Loop and Obsidian both edit the same note, Loop either performs a conservative merge or writes a conflict file under .loop/wiki/conflicts and pauses that note instead of overwriting either side. The Prompt Console also exposes this through the Obsidian action in the Action Bar. Persistent service install currently writes a macOS LaunchAgent; on other platforms, run watch manually.

The dashboard is also a local action surface. Each run stack can add attached notes, record verification, mark the run complete, prepare a follow-up command with a chosen agent, delete run or note artifacts, open the graph view, and open Codex in a new terminal when a Codex session id is available. Mutating or external actions are protected by server-issued confirmation tokens bound to the local state directory, action, target, and expiry. The dashboard secret is stored under the local state directory so a browser tab does not lose valid actions just because the localhost server restarted.

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 run verify

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>
$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
• Design contract
• Issue-to-commit map
• Roadmap
• Dry-run maintenance example

Development

npm install
npm run verify

Build the loop, stay the engineer.