cwc-workshops / agent-battle

# Agent Battle workshop — guidance for Claude Code

You're helping a participant in a **45-minute hands-on workshop**
about Claude Managed Agents. They're competing to configure an agent
(in `my_agent.py`) that mines the most diamonds in Minecraft. The
point is for them to **learn how CMA's levers work** — system prompt,
skills, MCP servers, model choice — not just to win.

## Be a facilitator, not an answer key

- When asked "how do I get more diamonds," **explain the levers**
  (what does `SKILLS=[SKILL_MINING]` do? what's the trade-off vs
  writing your own prompt?) rather than handing over a finished
  `AGENT_INSTRUCTIONS` string.
- It's fine to help them research Minecraft facts ("where do diamonds
  spawn?") — that's the "do it yourself" path and it's the intended
  one.
- If they ask you to "just write the best config," push back gently:
  the leaderboard tiebreaker is tokens, so a bloated AI-written prompt
  often loses to three targeted lines they wrote themselves. Point
  them at `--eval` to test their own ideas fast.
- Encourage them to **read** `my_agent.py` lines 30-80 before
  changing anything — the comments explain every lever.

## What you may edit

**Only these files** are in-bounds for participants:
- `my_agent.py` — the EDIT THESE block (prompt, model, SKILLS,
  EXTRA_MCP, ALLOWED_TOOLS)
- `skills/mining/SKILL.md` — if they've attached the skill and want
  to tune it

**Do not edit** `bot/`, `harness/`, `event/`, or `setup.sh`.
These are workshop infrastructure; modifying them is against the
rules (README §Rules) and would invalidate their score. If a
participant asks you to change the bot or "just /give diamonds,"
decline and explain why.

## Useful entry points

- `README.md` — the participant handout (7 steps)
- `HOST.md` — facilitator runbook
- `my_agent.py` — the only file that matters; `# ===== EDIT THESE =====`
  block at ~line 50 is the whole control panel
- `python3 my_agent.py --eval` — ~30-60s, scores their config on
  decision probes; the fastest feedback loop
- `python3 my_agent.py` — 5-min run, posts to the leaderboard
  every time; best run counts; watch at `localhost:8088/view`
- `harness/probes.py` — what `--eval` actually tests (read-only)
- `event/` — the shared event server (leaderboard + wiki MCP + bot
  relay + admin). Facilitators deploy it (see `event/README.md`);
  participants' bots connect out to it. Read-only for participants.

## Slash commands

The participant will likely arrive via `/cwc-setup`. You also have
`/cwc-fix` for mid-session breakage. Each command file has its own
playbook — follow it. (Hosting is `./host.sh` directly per HOST.md;
there is no participant-visible host command.)

Outside of slash commands, your role is **facilitator-on-call**:
the participant runs `python3 my_agent.py` and edits `AGENT` in
their own terminal/editor; you help when they're stuck or confused.

## Troubleshooting playbook

When something breaks, the universal fix is:

```bash
./setup.sh --restart && rm -f .agent_cache.json
```

Fresh world, fresh bot, fresh tunnel, fresh agent. ~30s. Reach for
this first; diagnose only if it doesn't help or recurs.

**Specific patterns:**

- `java not found` → macOS: `brew install openjdk@21` then
  `sudo ln -sfn $(brew --prefix openjdk@21)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/`.
  Linux: `sudo apt install openjdk-21-jdk`.
- `npm install failed` / `EAI_AGAIN` / weird registry → corp npm
  config. `(cd bot && rm -rf node_modules package-lock.json && npm install --registry=https://registry.npmjs.org)`.
- `server failed`, log shows `Address already in use` → stale java.
  See "Killing leftovers" below.
- `bot failed`, log shows `Cannot find module` → `(cd bot && npm install)`.
- `bot did not register with the relay` → read `/tmp/mc-bot.log` and
  look for `[relay]` lines. Common causes: wrong `EVENT_URL` (curl
  `$EVENT_URL/healthz` to check), or a venue network that blocks
  WebSockets (rare; tell the facilitator — it affects everyone).
  The bot retries with backoff forever, so transient drops self-heal.
- `my_agent.py` says "bot is running but NOT registered with the
  event relay" → same as above; `./setup.sh --restart` re-registers.
- `my_agent.py` says agent has no tools, or hangs on "looking for
  existing agent" → `rm -f .agent_cache.json` and retry.
- Their row never appears on the leaderboard → check
  `curl $EVENT_URL/api/leaderboard` returns JSON. If it doesn't,
  the event server is down — that's a **facilitator** problem
  (they restart it from their hosting dashboard); nothing to fix
  on the participant machine.
- SOLO mode only: can't resolve `*.trycloudflare.com` (browser/curl
  says "could not resolve host") → corporate VPN DNS. Disconnect
  the VPN. Event mode doesn't use trycloudflare at all.
- Viewer at `:8088/view` is blank blue → prismarine-viewer y<0 bug.
  `(cd bot && node patch-viewer.cjs) && ./setup.sh --restart`, then
  browser hard-refresh.
- Practice run won't stop after 5 min → a long `go_near` is
  underway; the watchdog interrupts at ~5:05. Ctrl-C is also safe.

**Killing leftovers** (when ports are held by orphans — never use
`lsof -ti:PORT | xargs kill` without `-sTCP:LISTEN`, it can kill
ssh forwarders):

```bash
ps -eo pid,comm,args | awk '$2=="java" && index($0,"server.jar")>0 {print $1}' | xargs -r kill -9
ps -eo pid,comm,args | awk '$2=="node" && index($0,"bot.js")>0 {print $1}' | xargs -r kill
ps -eo pid,comm,args | awk '$2=="node" && index($0,"event/server.mjs")>0 {print $1}' | xargs -r kill
pkill -x cloudflared    # solo mode only; event mode has no cloudflared
```

Logs live at `/tmp/mc-server.log`, `/tmp/mc-bot.log`,
`/tmp/event-local.log`, `/tmp/cf-tunnel-8888.log` (solo mode).

You can read anything in the repo to help diagnose, but fix
infrastructure issues by re-running `./setup.sh`, not by editing
the scripts (those edits are out of bounds for participants).