Full setup without Docker

Use this only when you explicitly want to run the workshop on your own machine instead of the Docker workshop computer.

Docker is still the normal path because it pins the toolchain and keeps auth/state away from your host. This local path is for people who already have, or are willing to install, the tools themselves.

Agent contract

If a coding agent is helping with setup, give it these rules first:

1. Stay inside the cloned aie-loopcraft-workshop-2026 folder.
2. Install or verify host tools only after the person running the machine agrees.
3. Never paste secrets into files, shell history, docs, or chat. If auth is needed, ask the person to sign in through the tool's normal login flow.
4. Do not create lesson artifacts early. Lesson 01 creates VISION.md; Lesson 02 creates the first issue-event file and checks.
5. Leave a short setup receipt: OS, tool versions, commands run, what passed, and what still needs auth.

Copy/paste prompt for a setup agent

Use this when you want a coding agent to run the local setup with you:

You are helping me run the AI Engineer Loopcraft Workshop 2026 on this machine without Docker.

Stay inside the cloned aie-loopcraft-workshop-2026 repo once it exists. Do not create lesson artifacts yet. Do not edit product files to work around missing host tools. Do not handle secrets or paste tokens anywhere; if auth is needed, stop and ask me to sign in through the normal tool flow.

Goal: get the local machine ready to start Lesson 01. Verify Git, Node 22+, pnpm 11.9.0, Bun, Pi, and Herdr. Install only the missing tools I approve. Run herdr integration install pi, or choose plain terminal mode if Herdr is the blocker. Run pnpm run web:install, pnpm run web:check, and pnpm run web:build. Start or smoke-test node scripts/loop-daemon-stub.mjs. Open Pi from the repo root and confirm it can start or asks me to log in.

Before changing anything, show me the current tool/version audit and the exact install commands you plan to run. When done, report a setup receipt: OS, repo path, git status before lesson work, tool versions, Herdr mode or terminal mode, site checks, daemon test, Pi auth status, and blockers. Stop before Lesson 01 edits unless I explicitly say to continue.

Done when

• git, node, pnpm, bun, pi, and herdr are on PATH.
• The repo is cloned and git status --short is clean before lesson work starts.
• herdr integration install pi has run successfully, or you choose plain terminal mode.
• pnpm run web:check and pnpm run web:build pass after pnpm run web:install.
• node scripts/loop-daemon-stub.mjs starts and prints a status server message.
• Pi opens from the repo root and either logs in or clearly asks you to log in.
• You can open Lesson 01 and use /loop-lesson-01 or paste the fallback prompt.

1. Install host prerequisites

Recommended local host: macOS or Linux. On Windows, use WSL2 or the Docker path unless you already know how you want to run Herdr and shell tooling.

Required tools:

• Git
• Node 22+
• pnpm 11.9.0 through Corepack
• Bun, for the SvelteKit workshop site
• Pi
• Herdr

Optional comparison shells: Claude Code, Codex, and OpenCode.

The Docker image currently pins these versions as a known-good baseline:

Pi: 0.80.2
Claude Code: 2.1.195
Codex: 0.142.3
OpenCode: 1.17.11
Herdr: 0.7.1
pnpm: 11.9.0
Node: 22

macOS quick install

# Git and Node can come from Homebrew, mise, fnm, asdf, or your normal setup.
# This is one plain path, not the only path.
brew install git node@22 bun herdr

corepack enable
corepack prepare pnpm@11.9.0 --activate

npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.80.2
npm install -g @anthropic-ai/claude-code@2.1.195 @openai/codex@0.142.3 opencode-ai@1.17.11

Linux quick install

corepack enable
corepack prepare pnpm@11.9.0 --activate

# Pi
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.80.2

# Herdr. This follows the public Herdr installer.
curl -fsSL https://herdr.dev/install.sh | sh

# Optional comparison shells.
npm install -g @anthropic-ai/claude-code@2.1.195 @openai/codex@0.142.3 opencode-ai@1.17.11

Pi also has an installer alternative:

curl -fsSL https://pi.dev/install.sh | sh

2. Verify the tools

Run this before cloning or changing repo files:

git --version
node --version
corepack --version
pnpm --version
bun --version
pi --version
herdr --version

Optional shell checks:

claude --version
codex --version
opencode --version

If a command is missing, stop and fix that one tool. Do not edit the workshop repo to work around a missing host dependency.

3. Clone the workshop repo

git clone https://github.com/joelhooks/aie-loopcraft-workshop-2026.git
cd aie-loopcraft-workshop-2026

git status --short
git log --oneline --max-count=5

git status --short should be empty before lesson work starts.

4. Install the Herdr Pi integration

Run this once on the host account that will use Herdr:

herdr integration install pi

Then start Herdr from the repo root:

herdr --session aie-loopcraft-workshop-2026

Inside Herdr, open a pane in the repo root and run pi. If Pi asks for auth, the person running the machine signs in with /login or the provider flow Pi shows.

5. Plain terminal mode

If Herdr is the blocker, use two terminals from the repo root instead of debugging the whole day away.

Terminal 1:

pi

Terminal 2, when a lesson asks for status/runtime output:

node scripts/loop-daemon-stub.mjs

6. Install and check the workshop site

The public site source lives under web/. It is separate from lesson work, but checking it proves the local JavaScript toolchain is sane.

pnpm run web:install
pnpm run web:check
pnpm run web:build

To preview locally:

pnpm run web:dev

Then open the local URL printed by Vite, or use the published Lesson 01 page: Lesson 01.

7. Start Lesson 01

From Pi in the repo root:

/loop-lesson-01

If that command is unavailable, paste this fallback prompt:

/skill:grill-with-docs

Help me define a small local issue-progress loop before we write code.

Read README.md, AGENTS.md, WORKSHOP_RIG.md, lessons/, agents/skills/loopcraft-ta, agents/skills/grill-with-docs, and surface/lakebed.

Ask one question at a time. Capture what the loop should do, what it may change, what needs human approval, and what we are not building yet. Write the answers into VISION.md. Update AGENTS.md or README.md only if we agree on a clear repo rule. Do not create issue events, checks, Lakebed code, dispatch, or product code yet.

8. Save a setup receipt

Ask the agent to report this in chat before lesson work begins:

Local setup receipt
- OS:
- Repo path:
- git status before lesson work:
- Tool versions:
- Herdr mode or terminal mode:
- Site checks run:
- Runtime/status command tested:
- Pi auth status:
- Blockers:

Common failures

• Pi opens but no model is available: use Pi's normal /login flow. The agent does not handle tokens.
• herdr integration install pi fails: use plain terminal mode for the lesson, then debug Herdr separately.
• pnpm run web:check fails before lesson work: fix the local toolchain first.
• The daemon shows empty events: normal before Lesson 02. Lesson 02 creates data/issue-events.jsonl or issues.jsonl.
• The agent wants GitHub, Linear, schedulers, or product code: stop. Local setup changes how tools run, not the lesson order.