Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
docs: add loop-sandbox subsection to QUICKSTART (#417)
Muhammad Zeshan Malikf202784056aa
diff --git a/README.md b/README.mdindex 0aa792e..d77c795 100644--- a/README.md+++ b/README.md@@ -108,6 +108,7 @@ For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agent| [loop-mcp-server](tools/mcp-server/) | MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server` || [loop-worktree](tools/loop-worktree/) | Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>` || [loop-gate](tools/loop-gate/) | Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>` |+| [loop-sandbox](tools/loop-sandbox/) | Ephemeral git worktree isolation + patch capture — `npx @cobusgreyling/loop-sandbox run -- <cmd>` || [Goal Engineering](https://github.com/cobusgreyling/goal-engineering) | **Companion:** loops discover, goals finish — `/goal` + [stack cookbook](https://github.com/cobusgreyling/goal-engineering/blob/main/docs/stack-cookbook.md) (`npx @cobusgreyling/goal doctor .`) || [Memory Engineering](https://github.com/cobusgreyling/memory-engineering) | **Companion:** stop re-explaining the repo — tiers, budget, Memory Ready score (`node tools/memory-init/cli.js .`) || [Fleet Engineering](https://github.com/cobusgreyling/fleet-engineering) | **Companion:** govern populations of agents — registry, inbox, Fleet Ready score (`npx @cobusgreyling/fleet-init .`) |diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.mdindex 4b6ccde..15805b3 100644--- a/docs/QUICKSTART.md+++ b/docs/QUICKSTART.md@@ -238,6 +238,26 @@ npx @cobusgreyling/loop-worktree listPair with the [circuit breaker](#circuit-breaker-for-l2-loops-optional) above: when `loop-context --check` exits `2`, mark the worktree `escalated` before handing off to a human. The two tools stay independent — see [tools/loop-worktree/README.md](../tools/loop-worktree/README.md).+### Ephemeral worktree isolation (`loop-sandbox`)++To run an agent command in a temporary, isolated git worktree and capture its changes as a reviewable `.patch` file without touching your working tree, use `loop-sandbox` ([tools/loop-sandbox/README.md](../tools/loop-sandbox/README.md)). It automatically spawns a clean worktree from HEAD, executes your process, captures all edits (including untracked files) into a `.patch` file, and destroys the worktree so your repo stays pristine.++```bash+# Run an agent command in an ephemeral sandbox+npx @cobusgreyling/loop-sandbox run -- npx my-agent++# Optional --shell to run raw shell commands (e.g. bash -c)+npx @cobusgreyling/loop-sandbox run --shell -- bash -c "echo 'fix' > file.txt"++# List and review generated patches before applying+npx @cobusgreyling/loop-sandbox review+git apply .loop-sandbox/patches/<patch-id>.patch+```++> **Windows compatibility:** On Windows, npm `.cmd` shims (`npx`, `tsc`, etc.) that fail with `ENOENT` are automatically retried through a shell, so you do not need to pass `--shell` just for `npx`.+>+> **Safety note:** `loop-sandbox` provides worktree isolation, but process execution retains OS-level filesystem and network access — see [docs/safety.md](./safety.md). Always inspect patch files before running `git apply`.+## Copy-paste cheat sheet```bash@@ -267,6 +287,10 @@ LOOP_PROJECT_ROOT=. npx @cobusgreyling/loop-mcp-servernpx @cobusgreyling/loop-worktree create --run-id <id> --pattern <pattern>npx @cobusgreyling/loop-worktree mark --run-id <id> --status rejectednpx @cobusgreyling/loop-worktree cleanup --older-than 24h++# Ephemeral worktree isolation + patch capture+npx @cobusgreyling/loop-sandbox run -- <command>+npx @cobusgreyling/loop-sandbox review```## Learn the why (optional, 10 minutes)