magicciv/tooling/claude-player

@magic-civ/claude-player

Claude Agent SDK adapter for the Magic Civilization Claude Player API (p2-67 Phase 4). Drives one player slot in a headless game while the production AI controls the others.

Run

cd tooling/claude-player
npm install
export ANTHROPIC_API_KEY=sk-ant-...
npm run dev                # tsx — no build needed
# or
npm run build && npm start # compiled JS

Each run writes append-only logs to .local/runs/<stamp>/:

• log.jsonl — agent decisions + notifications + run metadata.
• wire.jsonl — raw JSON-Lines between adapter and harness.
• result.json — final result (turns_played, reason, final_view).

Env vars

Var	Default	Purpose
ANTHROPIC_API_KEY	(required)	Claude API credentials
CP_MODEL	claude-opus-4-7	Model id
CP_MAX_TURNS	100	Hard turn cap
CP_MAX_IDLE_ENDS	3	Consecutive idle end_turns before bail
CP_SERVER	<repo>/scripts/claude-player-server.sh	Harness launcher
CP_SEED / CP_PLAYERS / CP_CLAUDE_SLOT / CP_OMNISCIENT / CP_TIMEOUT_SEC	see CLAUDE_PLAYER_API.md	Forwarded to harness

Architecture

@magic-civ/claude-player (Node)
        │
        ├── HarnessClient — spawn() + JSON-Lines pump
        │
        └── runAgent — Anthropic Messages API tool-use loop
                   ├── tool: view()
                   ├── tool: act(action)
                   └── tool: end_turn()
        │
        ▼ stdin/stdout
scripts/claude-player-server.sh
        │
        ▼
flatpak Godot --headless res://engine/scenes/headless/claude_player_main.tscn
        │
        ▼
GdPlayerApi → mc-player-api → mc-turn::action_handlers

Wire-protocol contract: src/game/engine/docs/CLAUDE_PLAYER_API.md. Owning objective: .project/objectives/p2-67-claude-player-api.md.