Agentic Loop Playground is an interactive, repository-native workshop for learning Loop Engineering by building and operating real loops with GitHub Copilot and GitHub.
It turns "let an AI agent work on my repo" into a measurable operating loop: define the goal, observe evidence, isolate the action, verify deterministically, separate maker/checker roles, persist decisions, and stop safely. Learners do the work inside a real local Git repository instead of watching a slide deck.
- Hands-on agentic coding practice: eight labs move from local setup to issue queues, custom agents, worktrees, recurring automation, verification, and a capstone pull request.
- Built for GitHub-native teams: the workshop uses GitHub Copilot CLI, GitHub Issues, pull requests, Actions, and the GitHub CLI as the loop's control plane.
- Safe by design: the practice scenario is intentionally broken, elevated actions require approval, and platform validation stays separate from learner failures.
- Easy to run in restricted environments: public npm, GitHub Release tarballs, and offline npm installs are all documented.
| Need | Start here |
|---|---|
| Try the workshop | npx -y agentic-loop-playground |
| Learn the teaching model | docs/LEARNING-PATH.md |
| See how this repo runs its own loop | docs/PLATFORM-LOOP.md |
| Plan community promotion | docs/PROMOTION-PLAN.md |
Start it from any directory:
npx -y agentic-loop-playgroundWithout a path, the command creates or resumes ./agentic-loop-playground-workspace. Pass one positional path to choose another empty directory or an existing playground:
npx -y agentic-loop-playground .
npx -y agentic-loop-playground ./my-loop-lab
npx -y agentic-loop-playground ./my-loop-lab --port 4173The path is resolved from the directory where npx runs. Missing and empty directories are initialized automatically. A non-empty directory without a compatible .loop-playground.json marker is rejected with a safety warning. AGENTIC_LOOP_PLAYGROUND_WORKSPACE is available as an environment-variable alternative; an explicit positional path takes precedence. Use -p, --port to request a port; if it is occupied, the launcher automatically selects an available port.
Run npx -y agentic-loop-playground --help for all options. Score a remote GitHub repository without starting the browser:
npx -y agentic-loop-playground eval github/docs
npx -y agentic-loop-playground eval https://github.com/github/docs --jsonThe launcher initializes local Git history, starts a loopback-only Node.js server, and opens the browser.
Each GitHub Release provides platform-specific, self-contained npm tarballs for Windows x64, Linux x64, and macOS arm64. Download the asset that matches the target computer, transfer it through your approved internal channel if necessary, and install it without registry access:
Windows x64:
irm https://github.com/chenxizhang/agentic-loop-playground/releases/latest/download/install.ps1 | iexLinux x64 or macOS arm64:
curl -fsSL https://github.com/chenxizhang/agentic-loop-playground/releases/latest/download/install.sh | shThe bootstrap scripts are published as validated Release assets rather than executed from a mutable branch. They require npm, an authenticated GitHub CLI (gh auth login), and access to GitHub Releases. They dynamically download the latest matching tarball, install it with npm's offline mode, remove temporary files, and then prompt you to run agentic-loop-playground -h.
For a tarball that was transferred manually:
npm install --global --offline .\agentic-loop-playground-<version>-win32-x64.tgz
agentic-loop-playground -hLinux and macOS assets use the same naming pattern with linux-x64 or darwin-arm64. The tarball bundles the Copilot SDK, Copilot runtime, and platform-specific native dependencies, so npm does not need to resolve packages from the public registry during installation. Other architectures require an asset built on that architecture or an approved internal npm proxy.
If company policy also blocks GitHub Releases, place the downloaded asset in an approved internal artifact repository or shared software distribution location. An internal npm proxy such as Azure Artifacts, GitHub Packages, Artifactory, or Verdaccio is preferable for organization-wide distribution because it provides access control, retention, auditing, and repeatable installs.
It does not teach Loop Engineering as a collection of definitions. Every lesson asks the learner to change the repository through the embedded Copilot workspace pane, use GitHub collaboration primitives, and pass an automated checkpoint.
The browser pane is backed by the official GitHub Copilot SDK and is scoped to the generated playground repository. Workspace reads are allowed automatically. File writes, shell commands, URL access, MCP operations, and other elevated actions require explicit one-time approval in the browser.
During the workshop, learners progressively create a closed engineering loop:
GitHub Issue -> discovery -> specialized agent -> isolated change
-> tests and review -> pull request -> recorded state
-> next issue or stop condition
The course maps the core Loop Engineering components to concrete GitHub tools:
| Loop component | GitHub Copilot CLI implementation |
|---|---|
| Automation | /loop, /every, programmatic copilot -p, GitHub Actions |
| Isolation | Git branches and git worktree |
| Skills | .github/skills/*/SKILL.md |
| Connectors | Built-in GitHub MCP server and GitHub CLI |
| Sub-agents | Custom agents, /agent, /fleet, review agents |
| Memory | GitHub Issues, pull requests, commits, evidence files, session resume |
| Verification | Tests, hooks, Actions, /review, independent verifier agent |
Prerequisites:
- Node.js 20.19 or newer, or Node.js 22.12 or newer
- Git
- A GitHub account with Copilot access
- GitHub CLI authenticated with
gh auth loginfor the embedded Copilot pane and private repository analysis
The package includes the Copilot runtime used by the SDK. A separate GitHub Copilot CLI installation is not required. The launcher creates the practice Git repository automatically.
Lab 07 uses the experimental /loop alias for /every. Enable it in that session with /experimental on, or start Copilot CLI with copilot --experimental.
Run the browser platform:
npm run web:openOr start only the server and open http://127.0.0.1:4173 yourself:
npm run webThe terminal dashboard remains available as a secondary interface:
npm startUseful source-repository commands for maintainers:
npm run doctor
node src/cli.js lesson 01
node src/cli.js check 01
npm run status
npm run gradeInitialize the GitHub-side exercises after pushing the repository:
npm run github:setupReset the intentionally broken CI repair scenario:
npm run scenario:reset
npm run test:practiceThe second command is expected to fail before the learner completes Lab 06. The platform's own npm test command deliberately runs only tests under test/, keeping teaching failures separate from platform health.
For application changes, use the local end-to-end regression loop.
npm run test:browser opens the actual application in an isolated browser with a
controlled runtime fixture and records layout, stream correctness, scrolling and
input-responsiveness evidence. It uses existing browser tools and never installs
packages. Fixture coverage, pinned-package validation and live Copilot/SSH evidence
are separate acceptance gates.
Start Copilot from the repository root:
copilotThen inspect the learning support included in the repository:
/skills list
/agent
Use @ file mentions when a lesson references a file. Do not enable --allow-all until you have reviewed the repository instructions, skills, hooks, and scripts.
| Lab | Outcome |
|---|---|
| 00 | Verify the local and GitHub environment |
| 01 | Design a measurable closed loop |
| 02 | Encode durable knowledge with instructions and a skill |
| 03 | Use GitHub Issues as the loop's discovery queue and memory |
| 04 | Isolate parallel work with worktrees and specialized agents |
| 05 | Separate maker and checker responsibilities |
| 06 | Repair a failing implementation through a test-driven loop |
| 07 | Automate recurrence and define safe stop conditions |
| 08 | Run the capstone loop through a pull request |
See docs/LEARNING-PATH.md for the teaching model and docs/PLATFORM-LOOP.md for how this platform applies Loop Engineering to itself.
The workshop deliberately creates branches, worktrees, issues, and pull requests. Read commands before approving them. Scheduled CLI prompts run only while their Copilot CLI session is open; GitHub Actions are the persistent automation mechanism used by this repository.