The dashboard is the primary way most people will use WorldFork. It is designed to make branching simulations feel legible: submit a scenario, watch the live multiverse tree, inspect branch decisions and logs, and follow report progress from the same browser surface.

The CLI and dashboard wrap the same backend APIs, so you can move between them without changing the underlying run state.

After the backend stack is running, start the dashboard with:

cd frontend
npm install
npm run dev

The dashboard expects the backend at http://127.0.0.1:8003 by default and proxies browser requests through /backend/*. Everything it shows remains available through worldfork, so visual workflows and scripted workflows stay on the same runtime.

Paste this prompt into your coding agent:

Run this command to install the WorldFork skill, then use its setup module to set up WorldFork on this computer:

npx skills add Hilo-Hilo/WorldFork/skills/worldfork --all

After installing it, use the setup module in the skill to guide me through prerequisites, .env configuration with OPENROUTER_API_KEY, CLI installation, Docker Compose startup, migrations, seeding, readiness verification, a short explanation of Big Bangs, multiverses, ticks, branches, endpoint ledgers, and reports, and the onboarding demo if I confirm I want to spend live API credits. Be proactive: explain what each setup phase proves, use `worldfork setup` to show provider options, ask which providers I want to configure, recommend the fast-cheap cohort plus stronger governance/report split for Atlas, estimate time and cost before live runs, and narrate what Atlas is doing while it runs.

The single worldfork skill contains setup, CLI, debug, report, documentation, update, reinstall, and uninstall modules. You do not need separate worldfork-setup or worldfork-report skills.

Use this path when you want to run each command yourself.

• Docker Desktop or another Docker Compose runtime
• Python 3.11+
• uv
• Node.js 20+ for the dashboard and for installing agent skills with npx skills
• An OpenRouter API key
• OpenAI Codex authentication for the default strong-model routes. The example environment uses OpenAI Codex gpt-5.4 for governance-style work and final multiverse report synthesis.

git clone https://github.com/Hilo-Hilo/WorldFork.git
cd WorldFork
python3.11 -m pip install -e ./cli
worldfork --help

If worldfork resolves to an old global shim, inspect which -a worldfork and reinstall the editable CLI from this checkout. While repairing a shim, use the source-checkout fallback from cli/:

cd cli
uv run --extra dev worldfork --help
cd ..

cp .env.example .env

Set OPENROUTER_API_KEY in .env for the fast model lane. The default route split uses OpenAI Codex for the strong model lane, so authenticate it before live runs:

worldfork settings openai-codex-login

The recommended live split is:

Inspect provider options and effective routing before spending live API credits:

worldfork setup
worldfork settings llm

make build
make up
make migrate
make seed

Verify readiness:

worldfork status
worldfork query GET /readyz --no-api-prefix
worldfork agent discover

worldfork init \
  --name "Atlas onboarding" \
  --scenario-file examples/test-big-bang.md \
  --max-ticks 4 \
  --tick-duration-minutes 720

Inspect the initialized workspace:

worldfork runs workspace <big-bang-id>
worldfork watch big-bang <big-bang-id> --once
worldfork runs cost <big-bang-id>
worldfork ledgers list <big-bang-id>
worldfork logs list --status failed

worldfork init proves initialization and workspace creation. For the full tick, branch, endpoint-ledger, cost/timing, and report loop, run Atlas only after approving live API-credit use:

worldfork demo atlas

Refresh the skill first so your agent has the newest update runbook, then use the safe updater:

npx skills add Hilo-Hilo/WorldFork/skills/worldfork --all
worldfork update --dry-run
worldfork update --yes

The updater preserves .env, local Docker overrides, Docker volumes, run history, artifacts, reports, and local preferences by default.

WorldFork is a visual workspace for exploring branching futures. At the product level, it is a Monte Carlo tree search of the real world: start from a scenario, run simulated rollouts, branch when decisions matter, score terminal outcomes, and report the resulting distribution. Start with a Big Bang scenario, execute a checkpointed tick runtime, allow both autonomous and human-created forks, then compare the resulting multiverses through structured reports.

Most simulations answer "what happens next?" once. WorldFork keeps asking that question across forks.

WorldFork separates the scenario source from the question the report must answer. The scenario source can be a long Markdown dossier, while the dedicated report question is stored in scenario_input.primary_question with optional resolution_criteria and supporting_questions.

Reports use that question context when extracting prediction predicates, resolving timeline evidence, and writing the final answer. This keeps a large scenario file from accidentally becoming the forecast contract.

A Big Bang is the root scenario. It initializes the world state and seeds the first multiverse. From there, WorldFork can create child multiverses at meaningful decision points while preserving lineage, inherited history, and auditable branch metadata.

Key ideas:

• A Big Bang creates the root timeline.
• The root timeline can fork into multiple child multiverses.
• Child multiverses inherit prior history up to the fork point.
• Branching is constrained by policy: depth, active multiverse cap, branches per tick, and score thresholds.
• When branch_score crosses the configured threshold, backend policy creates a branch even if the God-agent response only said to continue.
• Terminal or paused multiverses can later be reported on or continued.

The canonical runtime is the LangGraph-backed tick engine. Each tick is decomposed into observable, checkpointed stages so runs can be paused, resumed, inspected, or replayed safely.

The major stages are:

1. Tick request
2. Actor decisions
3. Event generation
4. Sociology update
5. Graph update
6. God-agent review
7. Tick summary
8. Final tick snapshot

Important runtime properties:

• Checkpointed execution with persisted nodes, attempts, and checkpoints.
• Resume-safe tool calls after interruption.
• Partial progress visibility inside a tick (for example 4 / 16 cohorts updated).
• Canonical durable state in Postgres, with LangGraph checkpoints used as resumability metadata.
• Auditable outputs including logs, attempts, tool results, and tick summaries.

WorldFork supports more than one kind of fork. A branch can happen because the simulation naturally diverges, because the God-agent identifies a branch-worthy outcome, or because a human operator intentionally intervenes.

Branch sources include:

• Model / simulation branch — decision divergence, event pressure, or emergent behavior.
• God-agent branch — explicit review-driven branching.
• Human operator branch — manual intervention, event injection, prompt editing, forced branch creation from checkpoints, replaying nodes, or editing world state.

All of this is kept auditable through persisted prompt packets, raw and validated LLM outputs, tool I/O, human interventions, branch metadata, and undo history.

Default reversibility model: human edits usually create a branched multiverse instead of mutating history in place.

WorldFork keeps the dashboard, CLI, and API on one runtime. The dashboard is the main user-facing workspace, worldfork is the stable operator and agent control surface, and the backend owns execution, persistence, and reporting.

Storage boundaries:

• Postgres is canonical for durable domain state.
• Regenerable report renders are ephemeral, generated only on request.
• Reports are structured database records first, then Markdown/PDF renderings when requested.
• Report LLM work is split by route: predicate and single-universe reports can use the fast default model, while the final multiverse report uses final_report_agent_model and the higher final-report budget.
• /api/big-bangs/<id>/report-status exposes report pipeline state so the frontend can show single-report, predicate-resolution, and final-report progress instead of an empty report page.
• Jobs can be paused, resumed, interrupted, requeued, or run synchronously.

WorldFork is a monorepo with installable and runnable surfaces around one core runtime. The layout is kept explicit so operators, agents, and maintainers can find the runtime, CLI, docs, examples, and infrastructure without hunting through generated artifacts:

The frontend uses the same API as the CLI, so visual actions and scripted operator workflows operate on the same state.

Use global flags before the command:

worldfork --verbosity summary runs list
worldfork --fields id,status,created_at jobs list
worldfork --json status

backend/app/          FastAPI app, runtime, jobs, storage, reports
backend/tests/        root regressions, unit, integration, and e2e tests
cli/                  standalone Python CLI package
frontend/             Next.js 15 dashboard for the primary browser experience
skills/               installable operator and agent skills
examples/             runnable scenario dossiers
source_of_truth/      prompt, report, and policy templates
scripts/              local validation and demo harnesses
infra/                Docker and Alembic infrastructure
docs/                 operator, developer, and agent documentation

WorldFork is a UI-led product with a scriptable CLI and API behind it. The current system is Dockerized, tested across unit/integration/e2e layers, and live-smoke validated against configured effective LLM routes. A common route policy is:

openrouter/deepseek/deepseek-v4-flash
openai-codex/gpt-5.4

If you want to understand the project quickly, start with the dashboard and the diagrams above. For CLI/API inspection, run:

worldfork agent discover
worldfork status

WorldFork is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.