Lesson 5.1 — Your First Agent: Folder Tidy

Introduction to AI · Module 5: AI Agents · About 80 min · Windows PC, PowerShell 5, Claude Max (no API key needed)

Tonight's goal: build a "Folder Tidy" agent. Claude Code looks at a messy folder, moves each file to the right place, checks its own work, and keeps going until a test prints PASS.

Before you start

• Phone on silent, water nearby
• Open Windows PowerShell (Start → type powershell → Enter). The prompt starts with PS C:\

Step 1 · Install Claude Code (⏱ 0:00–0:10)

Already installed? Run claude --version. If you see a version number, skip to Step 2.

Optional but recommended: install Git for Windows first from https://git-scm.com/download/win (accept all the defaults). It gives Claude Code a Bash tool.

Then in PowerShell:

irm https://claude.ai/install.ps1 | iex

It shows little or no progress while it downloads. Wait for the prompt to come back.

Close PowerShell, open a new window, then:

claude --version

You should see something like:

2.x.x (Claude Code)

• Version number shown

Step 2 · Log in (⏱ 0:10–0:15)

mkdir $HOME\agent-night -Force
cd $HOME\agent-night
claude

Choose Claude account with subscription (Pro/Max). A browser opens: log in and approve. Back in PowerShell, say Yes when asked whether to trust this folder.

You should see the Claude Code prompt box (>).

Now leave Claude: **type /exit and press Enter. Wait until you see PS C:\...> before the next command.**

• Logged in with your Max account

Step 3 · Make a messy test folder (⏱ 0:15–0:20)

Paste this whole block:

cd $HOME\agent-night
mkdir messy -Force | Out-Null
"a","b","c" | % { "x" | Out-File "messy\$_-receipt.pdf" }
"d","e","f" | % { "x" | Out-File "messy\$_-photo.jpg" }
"g","h","i" | % { "x" | Out-File "messy\$_-notes.txt" }
"j","k","l" | % { "x" | Out-File "messy\$_-budget.xlsx" }
(dir messy -File).Count

You should see 12.

• 12 files created

Step 4 · Write the finish line: check.ps1 (⏱ 0:20–0:25)

This script is how the agent knows it's done. Paste the whole block:

@'
$files = @(dir messy -Recurse -File | ? { $_.Name -ne "REPORT.md" })
$loose = @(dir messy -File | ? { $_.Name -ne "REPORT.md" })
$ok = (Test-Path messy\Documents) -and (Test-Path messy\Images) -and
      (Test-Path messy\Spreadsheets) -and (Test-Path messy\REPORT.md) -and
      ($loose.Count -eq 0) -and ($files.Count -eq 12) -and
      (@(dir messy\Images -File).Count -eq 3) -and
      (@(dir messy\Spreadsheets -File).Count -eq 3) -and
      (@(dir messy\Documents -File).Count -eq 6)
if ($ok) { "PASS" } else { "FAIL" }
'@ | Out-File check.ps1 -Encoding utf8
.\check.ps1

You should see FAIL. That's correct for now: nothing has been tidied yet.

• FAIL printed (if you get "running scripts is disabled", see Troubleshooting)

Step 5 · Give the agent its instructions: CLAUDE.md (⏱ 0:25–0:35)

Claude Code reads CLAUDE.md automatically every time it starts in this folder.

@'
# Folder Tidy Agent
Job: tidy the folder `messy`.
Rules:
- Only touch files inside `messy`. Never delete anything.
- PDF and TXT go in messy\Documents. JPG and PNG go in messy\Images.
  XLSX and CSV go in messy\Spreadsheets.
- Write messy\REPORT.md listing every move (old path -> new path).
Loop: look -> plan -> move -> run `.\check.ps1`.
If it prints FAIL, work out why, fix it, and run it again.
Stop only when it prints PASS.
'@ | Out-File CLAUDE.md -Encoding utf8
dir

You should see check.ps1, CLAUDE.md and the messy folder.

• CLAUDE.md created

Step 6 · Run the agent, interactive version (⏱ 0:35–0:50)

claude

Type this and press Enter:

Tidy the messy folder following CLAUDE.md.

Watch the loop: it looks (lists files), acts (makes folders, moves files), checks (runs check.ps1) and reads the result. When it asks permission, read what it wants to do and choose Yes. That makes you the human in the loop.

When it says PASS, leave Claude: **type /exit and press Enter. Wait until you see PS C:\...> before the next command.** Then confirm it yourself:

.\check.ps1

You should see PASS.

• PASS confirmed by you

Break (5 min). Stand up and stretch.

Step 7 · One-command (headless) agent (⏱ 0:55–1:10)

First reset the mess (paste the whole block):

dir messy -Recurse -File | Move-Item -Destination messy -Force
Remove-Item messy\Documents, messy\Images, messy\Spreadsheets -Recurse -ErrorAction SilentlyContinue
Remove-Item messy\REPORT.md -ErrorAction SilentlyContinue
.\check.ps1

You should see FAIL (it's messy again).

Now run the agent with no chat at all:

claude -p "Tidy the messy folder following CLAUDE.md. Report PASS or FAIL." --allowedTools "Bash,PowerShell,Read,Write,Edit,Glob"
.\check.ps1

You should see Claude's short summary, then PASS, and you didn't click anything.

• Headless run gave PASS 🎉

Step 8 · Reflect (⏱ 1:10–1:20)

1. My agent's loop was: ________ → ________ → ________, and it knew it was done when ________.
2. One everyday task I'd hand to an agent next: ________________________.

• Both lines written

✅ Pass check: lesson complete when ALL are ticked

• .\check.ps1 printed PASS after the interactive run
• .\check.ps1 printed PASS after the headless run
• You can explain the agent loop in one sentence
• Sent your reflection to Skills Coach so 5.1 gets marked done

⭐ Stretch (only if you've got energy left)

Work on a copy of Downloads, never the originals:

Copy-Item $HOME\Downloads $HOME\agent-night\real-copy -Recurse

Edit CLAUDE.md to point at real-copy, add Installers/Videos/Archives, and ask it to flag duplicates in REPORT.md.

Troubleshooting

Quick quiz