worldos

WorldOS

A playable living-world RPG engine and OpenWorlds app for tabletop-scale D&D 5e adventures.

WorldOS turns a persistent world into a playable campaign: an AI Dungeon Master narrates the scene, the deterministic SRD 5.2 engine resolves rolls and state, and OpenWorlds gives the player a real app surface for actions, maps, party state, journals, and live narration. The provider is configurable: use Anthropic through Claude Code, Codex/OpenAI through Codex CLI, or future OpenClaw lanes without changing the engine contract.

Agents/contributors: start at docs/OPERATIONS.md — the one-page bootstrap (vision → roadmap → active sprint → the loop). The product vision lives in VISION.md; the sequencing source of truth is docs/roadmap/PRODUCT-ROADMAP.md.

Scene	Chronicle	Actions

Screenshots above are public-safe scripted demo captures with private art disabled. See docs/images/README.md.

What WorldOS Does

• Plays a real campaign: start or resume a persistent living-world session with an AI DM and a player-facing action palette.
• Keeps rules deterministic: dice, checks, combat, spellcasting, inventory, rests, XP, and state writes live in the engine, not in model prose.
• Keeps the app thin: OpenWorlds and WorldOS.app read live engine state and submit /move intents; the engine remains the only campaign-state writer.
• Supports provider lanes: Anthropic/Claude Code and Codex/OpenAI are first-class provider families; OpenClaw is experimental/future-facing.
• Ships public and private content paths: original/redistributable content can be committed; user-owned or private worlds/art stay in ignored _private/ folders.
• Exports evidence: app-status snapshots, session surfaces, screenshots, logs, moves, and provider traces can be bundled for QA without committing raw evidence.

Choose Your Provider

Provider family	Typical use	Default model lane	Notes
Claude Code / Anthropic	Anthropic-only users, Opus release comparisons, Claude plugin workflows	Opus DM, Sonnet player/scorer where selected	Does not require Codex CLI.
Codex CLI / OpenAI	Codex/OpenAI-only users, same-family GPT proof, local provider QA	GPT-5.5 DM/player/scorer unless configured	Does not require Claude login.
OpenClaw	Experimental gateway/provider research	Not the default release lane	Keep gateway/plugin work gated until native provider lanes prove parity.

Provider parity means each family can configure, launch, play, test, and score through its own lane. It does not mean every model receives identical story/mechanical scores.

Read docs/PROVIDERS.md for setup, model selection, command overrides, and troubleshooting.

Quick Start

1. Clone and install runtime deps

git clone https://github.com/electricsheephq/WorldOS.git
cd WorldOS
curl -LsSf https://astral.sh/uv/install.sh | sh

You also need at least one provider login:

• Claude Code for the Anthropic lane.
• Codex CLI for the Codex/OpenAI lane.

2. Play in OpenWorlds

./worldos-play.command

or launch a specific world from a terminal:

scripts/play.sh sundered-reach

OpenWorlds serves at http://127.0.0.1:8765/openworlds/. The player acts through Continue, Look, Say, Do, skill/save buttons, travel, and combat actions. The selected provider resolves moves through the engine and writes the next narration beat.

3. Build and run the native app

script/build_and_run.sh

This builds dist/WorldOS.app from the Swift package under macos/WorldOSApp/ and opens the native OpenWorlds shell.

4. Configure providers

Use the native app provider/settings screens or wrapper environment variables to select a provider family and model. The code keeps modern WORLDOS_* names and legacy WORLDOS_* aliases additive for compatibility.

See:

• docs/GETTING_STARTED.md
• docs/PROVIDERS.md
• docs/TROUBLESHOOTING.md

How QA Works

WorldOS separates quick app confidence from release proof: