Llm Vs

Running

The game-loop.py script handles everything: prerequisite checks, system prompt generation, and the full turn loop with audio-synced long-polling. The game server must already be running and in PlayRound.

python3 .claude/skills/llm-vs/scripts/game-loop.py \
  --model-p1 MODEL \
  [--model-p2 MODEL] \
  [--no-pause] \
  [--json] \
  [--ollama-url URL] \
  [--game-url URL] \
  [--max-turns N]

Flags

Pause behavior (DEFAULT — no flag needed)

The script pauses by default — it starts paused and pauses again after every turn, writing status to /tmp/llm-vs-status.json and blocking until SIGUSR1 is received. This enables turn-by-turn orchestration from the skill. Use --no-pause to disable this.

IMPORTANT: The script starts in a paused state. After launching, you MUST send kill -USR1 <pid> to begin the first turn.

Resume methods:

• kill -USR1 <pid> — resume without orders
• Write /tmp/llm-vs-orders-p{1,2}.json then kill -USR1 <pid> — resume with commander orders injected into the next LLM call

Orders file format:

# P1 orders:
echo '{"order": "Focus on siege units"}' > /tmp/llm-vs-orders-p1.json
# P2 orders:
echo '{"order": "Play your spy card"}' > /tmp/llm-vs-orders-p2.json

Orders are wrapped in faction-themed language before injection (e.g., "The Jarl's war council demands: ...").

Mapping user args

Decision tree

1. Check if game-loop.py is already running: read PID from /tmp/pids/game-loop.pid
2. Validate the PID is actually alive: kill -0 <pid> 2>/dev/null
   • If PID file exists but kill -0 fails, the process is dead/stale — treat as "not running"
3. If running and user says "unpause", "continue", "next turn", "just unpause":
   • Read PID from /tmp/pids/game-loop.pid
   • Send kill -USR1 <pid> to unpause
   • Do NOT launch a new process
4. If NOT running: check current game state via curl -s http://localhost:8080/state | python3 -c "import json,sys; print(json.load(sys.stdin).get('active_stage',''))":
   • If stage is PlayRound → launch the game loop
   • If stage is anything else, or server is down → tell the user to start the server and deal cards first (use /dev-server)
5. Model mapping: /llm-vs --model-p1 ollama/deepseek-r1:14b → --model-p1 ollama/deepseek-r1:14b
6. Unattended: only pass --no-pause when user says "auto-play", "run unattended"
7. IMPORTANT: After launching, send kill -USR1 <pid> to start the first turn (script starts paused)

Turn-by-Turn Orchestration

The script pauses by default (no flag needed). Use this loop:

1. Launch in background

source ~/gwent-venv/bin/activate && \
source <(grep -v '^#' .env | sed 's/^/export /') && \
python3 .claude/skills/llm-vs/scripts/game-loop.py \
  --model-p1 MODEL [--model-p2 MODEL] --game-url http://localhost:8080 &

Capture the PID. The script starts paused — send kill -USR1 <pid> to begin the first turn. After each turn it pauses again.

2. Wait for pause and read status

After each turn, the script writes /tmp/llm-vs-status.json:

{"turn": 3, "current_player": "PLAYER.ONE", "round": 1, "scores": {...}, "pid": 12345}

Read the script's stdout for the turn summary, board state, and reasoning.

Then fetch the full game state for the rich summary:

curl -s http://localhost:8080/state | /home/dshanaghy/gwent-venv/bin/python3 -c "
import json, sys
s = json.load(sys.stdin)
b = s['state']['board']
print(json.dumps({
    'factions': b.get('factions'),
    'leaders': {p: v.get('name') for p, v in b.get('leaders', {}).items()},
    'hand_sizes': {p: len(v) for p, v in b.get('hands', {}).items()},
    'deck_sizes': {p: len(v) for p, v in b.get('decks', {}).items()},
    'scores': b.get('scores'),
    'weather': b.get('weather_rows', []),
    'horns': b.get('commander_horn_rows', {}),
    'current_player': b.get('current_player'),
    'round': b.get('round_number'),
}, indent=2))
"

Use this data to render the rich game state summary (see step 3).

3. Present game state summary and AskUserQuestion

After each turn completes, fetch the full game state from curl -s http://localhost:8080/state and present a rich, emoji-laden markdown summary before the AskUserQuestion. Use this template:

## ⚔️ Round {round} — Turn {turn}

### 🏰 {P1 Faction Emoji} {P1 Faction} vs {P2 Faction Emoji} {P2 Faction}

| | {P1 Faction Emoji} {P1 Faction} | {P2 Faction Emoji} {P2 Faction} |
|---|---|---|
| 👑 Leader | {P1 leader name} | {P2 leader name} |
| 🃏 Hand | {P1 hand size} cards | {P2 hand size} cards |
| 📚 Deck | {P1 deck size} remaining | {P2 deck size} remaining |

### 📊 Scoreboard

| Row | {P1 Faction Emoji} {P1 Faction} | {P2 Faction Emoji} {P2 Faction} |
|---|---|---|
| ⚔️ Close | {p1_close} | {p2_close} |
| 🏹 Ranged | {p1_ranged} | {p2_ranged} |
| 🔥 Siege | {p1_siege} | {p2_siege} |
| **🏆 Total** | **{p1_total}** | **{p2_total}** |

{weather_line}
{horn_line}

### 🎯 Next up: {Current Player Faction Emoji} {Current Player Faction}

Faction emojis:

Conditional lines:

• {weather_line}: If weather_rows is non-empty, show 🌨️ **Weather:** {comma-separated weather effects}. Omit if empty.
• {horn_line}: If any player has commander horns, show 📯 **Commander Horns:** {details}. Omit if empty.
• Show score cells with leading emoji when non-zero: e.g. ⚔️ 27 vs just 0
• If a player is winning, add 👑 next to their total

After the summary, present AskUserQuestion with these options:

• "Continue" — resume for one turn, then pause again
• "Run uninterrupted" — disable auto-pause, let agents play freely until game ends (sends SIGUSR2)
• "Order P1" — prompt for orders to P1's agent (use faction-themed label)
• "Order P2" — prompt for orders to P2's agent (use faction-themed label)
• "Stop" — kill the game loop

Use faction-themed labels for order options, e.g.:

• If P1 is Skellige: "Order the Jarl's army"
• If P2 is Monsters: "Command the Wild Hunt"

Note: max 4 options in AskUserQuestion. Use the 2 most relevant order options plus Continue and Run uninterrupted. Put Stop as the "Other" fallback.

4. Handle user choice

"Continue": kill -USR1 <pid> — plays one turn, pauses again

"Run uninterrupted": kill -USR2 <pid> then kill -USR1 <pid> — disables auto-pause and unpauses. The game runs freely. The skill should exit the AskUserQuestion loop and just let stdout flow.

Orders: Write the user's exact raw text — do NOT rephrase, sanitize, or summarize. The game-loop adds faction preamble automatically:

echo '{"order": "<user text VERBATIM>"}' > /tmp/llm-vs-orders-p1.json  # or p2
kill -USR1 <pid>

"Stop": kill <pid> (SIGTERM)

SIGUSR2 from outside the loop

If the user says "let them play", "auto-play", "run free", "uninterrupted" while the game is running (outside the AskUserQuestion loop), /llm-vs should:

1. Find PID: pgrep -f game-loop.py
2. Send kill -USR2 <pid> to toggle auto-pause off
3. If currently paused, also send kill -USR1 <pid> to unpause

To re-enable auto-pause from outside: kill -USR2 <pid> again (it's a toggle)

5. Repeat

Loop back to step 2 until the game ends.

Faction-Themed Commander Labels

Use these for AskUserQuestion labels/descriptions:

Output

Each turn shows:

1. Pre-turn summary (hand size, scores, weather, leader, orders)
2. LLM action and reasoning
3. Board state summary
4. JSON event (if --json)

After the game ends, report:

• Final scores and winner
• Total turns played
• Log file paths