Claude Kingdoms

An open-source medieval grand strategy game powered by Claude Code session activity.

---

⚠ Pre-alpha — NOT a working game yet

Status: pre-alpha / pre-V1. Not a playable game today. Read this section before cloning if you're hoping to play.

What works right now (verified, tested):

• A Python bridge daemon that ingests Claude Code hook events and keeps session state, scoring, plans, goals, momentum, tokens. 248 unit + integration tests pass on every push.
• A Textual TUI sandbox (python run_tui.py) where you can drive session state through keyboard bindings and watch resources accumulate. This is a developer sandbox, not the game.
• A small medieval-flavor JSON mod folder (mod/ClaudeKingdoms/) with civilization, building, belief, and tutorial content for Unciv.

What does NOT work yet (honest list):

• The actual game is not playable. The bridge↔Unciv integration leg is unimplemented. Earlier project iterations shipped a Lua "mod hook" that turned out to be architectural fiction — Unciv does not support runtime Lua scripting (see docs/unciv-research-2026-05-11.md). That code has been removed from the repo. The replacement model is an external save-edit tool that mutates an Unciv save file while the game is closed (per ADR-001). That tool has not been written yet.
• The mod has not been validated against Unciv. The JSON content in mod/ClaudeKingdoms/ uses plausible field names but has never been parsed by a running Unciv. Only Buildings.json and Units.json (which we don't have) are officially "schema-validated" per Unciv's docs. Loading the mod will probably surface JSON-shape errors that need fixing.
• No playtest has happened. PRD §M4 "fun-factor check" has not been performed. Whether the gameplay is fun is unknown.
• No GIF in the README. That's intentional — recording a real demo depends on the loop above actually working in Unciv first.

What's the right expectation? If you clone today, you'll get a clean tested Python bridge + a TUI you can poke + some Unciv mod JSON content. You will NOT get a Civ-like strategy game driven by your coding work. That's the goal, not the current state.

See .claude/handoff.md for the full honest status (acceptance-criteria grid + critical-path next steps) and docs/audit-2026-05-08.md (with its 2026-05-11 retraction header) for the audit history.

---

Vision

Turn your real Claude Code sessions into an empire. Every plan created, every goal completed, and every active session grows your kingdom. Idle hands stir nothing; active minds stir empires. The kingdom never decays when you step away — but it only grows when you return.

Quick Start (TUI sandbox only)

git clone https://github.com/SolshineCode/ClaudeKingdoms
cd ClaudeKingdoms
pip install -r requirements.txt
python run_tui.py

First launch shows the onboarding screen. After that, any save at ./saves/kingdom_save.json is auto-loaded.

Key bindings (TUI)

Key	Action
g	Inject TaskCompleted (goal +1, momentum +1)
p	Inject SubagentStart Plan (plan +1)
r	Inject PermissionDenied (Redirect: momentum → 0)
a	Inject UserPromptSubmit (mark active)
t	Advance turn (score → save → callbacks)
s	Save now
q	Quit (auto-saves first)

Run the daemon (production-shaped bridge, no UI)

python -m bridge.daemon              # turn loop + stdin hook ingestion
python -m bridge.daemon --no-hooks   # turn loop only

Writes ./saves/kingdom_save.json (state) and ./logs/audit.jsonl (event log). See docs/hooks-setup.md for how to actually wire Claude Code's hook stream into the daemon's stdin.

Critical-path next steps (not done yet)

1. Install Unciv (https://github.com/yairm210/Unciv) and try to load mod/ClaudeKingdoms/. Iterate on JSON field names until the mod loads cleanly.
2. Inspect an Unciv save file on disk. Determine its format and where per-city yields live.
3. Write the external save-edit tool that reads the bridge's kingdom_save.json and mutates an Unciv save file with per-city deltas while the game is closed. This is the missing piece.
4. Playtest with the actual loop running and make calibration decisions on the scoring constants.

Until step 3 is done, the game does not actually work. The Python bridge half is real. The Unciv half is a content pack with an unimplemented save-edit tool waiting to be built against it.

Development Status

Milestone	Bridge side	Unciv side
Pre-M0 Spikes (1+2)	✅ ADRs published	n/a
M0 Scaffolding	✅	n/a
M1 Vertical Slice	✅	❌ (needs save-edit tool)
M2 Core Economy	✅	❌ (needs save-edit tool)
M3 Medieval Aesthetic	✅ (TUI palette + onboarding)	🟡 (JSON content only, unvalidated)
M4 Operators + Campaign	❌	❌
M5 Community Launch	❌	❌

248 tests passing on main. CI runs pytest on every push and PR.

Architecture (current, after 2026-05-11 cleanup)

                     ┌──────────────────┐
                     │   Claude Code    │
                     │   (your work)    │
                     └────────┬─────────┘
                              │ JSONL hook events
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Python Bridge                          │
│                                                              │
│  HookListener  ──→  SessionState  ──→  ScoringEngine        │
│       │                  │                   │               │
│       └──────────────────┴───────────────────┘               │
│                          │                                   │
│                  ┌───────┴────────┐                          │
│                  ▼                ▼                          │
│            BridgeLoop        SaveExchange                    │
│            (turn pump)        (file I/O)                     │
└──────┬──────────┬─────────────────┬──────────────────────────┘
       │          │                 │
       ▼          ▼                 ▼
   Textual TUI   ./saves/          [save-edit tool: NOT BUILT]
   (live view)   kingdom.json              │
                                           ▼
                                     [Unciv save file]
                                           ▼
                                       Unciv game

The dotted-line section (save-edit tool through Unciv) is the unimplemented critical path.

See:

• docs/prd/ClaudeKingdomsPRD.md — full vision and milestone definitions
• docs/adr/ — architectural decision records
• docs/bridge-tui-schema.md — versioned bridge save-exchange JSON schema
• docs/unciv-research-2026-05-11.md — Unciv mod-system research
• docs/audit-2026-05-08.md — CTO audit (with 2026-05-11 retraction)
• .claude/handoff.md — current honest status

Repo layout

bridge/              Python bridge daemon (state, scoring, hooks, save, audit log)
  tests/             248 unit + integration tests
tui/                 Textual TUI (panels, bindings, onboarding, medieval voice)
  tests/             TUI tests (incl. Pilot)
mod/ClaudeKingdoms/  Unciv mod content (JSON only; unvalidated)
docs/                PRD, ADRs, schema, hooks-setup, audit, research
.github/workflows/   CI (pytest on push/PR)
run_tui.py           Cross-platform TUI launcher

Testing

pytest -q                                            # full suite (~5s)
pytest bridge/tests/test_e2e_vertical_slice.py -v    # bridge-side E2E
bash scripts/hello.sh                                # repo smoke test

Contributing

See CONTRIBUTING.md. TL;DR: pick one of four paths (Bridge / TUI / Mod content / Docs), write tests first when feasible, open a PR against main, CI must be green before merge. Five vetted good first issue candidate bodies live in docs/good-first-issues.md.

License

MIT. By contributing, you agree your contribution is MIT-licensed.

A note on what this is

This project is an experiment in "gamifying" real cognitive work through a strategy-game wrapper. It came out of a couple of intense multi-day collaborative sessions between a human (Caleb) and several AI agents (Hermes Agent + Claude Code). It is published in its honest current state — pre-alpha, partly fictional in places that have now been retracted, but with a clean tested core and a clear path forward — rather than a polished-looking-but-broken state. If that openness is useful to you, welcome. If you want a finished game, this is not yet that.