Skip to main content
unofficial.voyage wiki
Builder

Guides

Build a World with an AI Agent

Set up a coding agent like Claude or Codex to author a Voyage V33 world against the wiki's API — folder structure, instruction files, the validate loop, an offline mirror, local models, and what it all costs.

Overview

A Voyage world is a large structured JSON document, and this wiki publishes the V33 schema in a machine-readable form: per-section docs, the raw codec, and a validator endpoint. That combination makes a coding agent — something like Claude or Codex — a natural way to draft and refine a world. The agent reads the field rules for the section it is working on, writes the JSON, checks it against the live validator, and fixes whatever is flagged, looping until clean.

This guide sets that workflow up end to end: which tools to use, how to lay out the project folder and instruction files, how to point the agent at the wiki without burning tokens, how to work offline, and how to drive it with example prompts. The core is tool-agnostic — the same loop drives any capable agent — with concrete setup shown for Claude and Codex.

If you would rather not wire it up by hand, there is a faster on-ramp: see Fastest start: World-Puppeteer.

Coming from Voyage: Studio. Voyage has announced Studio, a native feature for building a world by talking to an agent directly on the site — the same idea as this guide, built in. When it ships it may change the manual UI steps below (create a world, toggle JSON), and for many authors it will be the simplest path. Until then, this guide is how you drive your own agent against the wiki.

What it costs (read this first)

These agents are metered. You pay per token, and a full world is many iterations, so this is real spend, not a free tool. Cost scales with two things: the model you pick, and how much text you feed it each turn. The most capable Claude models are the priciest per token; smaller models cost a fraction.

The single biggest lever is how the agent reads the wiki. Point it at the targeted endpoints, never the firehose:

  • Do: fetch only the section being worked on — GET /api/sections/<section>.md (for example /api/sections/npcs.md). That is a few KB.
  • Don't: pull the whole reference every turn. /api/wiki.md is the entire wiki in one payload, and scraping the rendered HTML pages is worse still — page markup the agent does not need. Loading either into context on every step multiplies your bill for no benefit.

Other ways to keep usage down:

  • Use a smaller, cheaper model for bulk and mechanical passes (generating many similar entries, reformatting) and reserve the top model for the hard reasoning — world design, canon, tricky validator fixes.
  • Mirror the wiki once and read from disk, so the agent never re-fetches the same docs.
  • Keep each task scoped to one section or one change instead of asking for the whole world in a single sprawling turn.

Desktop clients also carry a subscription cost: Claude Cowork is paid-plan only (Pro and up), and Codex needs a paid ChatGPT plan or an API key. Budget for it before a long session.

Running a model locally (optional)

You can skip per-token billing entirely by running an open-weight model on your own machine — free after hardware, and fully private and offline. The catch is quality: open models trail the frontier ones at the demanding parts of this task (strict JSON, canon accuracy, not inventing fields), so expect more babysitting and re-validation. Local is best for cheap bulk passes and experimentation rather than as the primary driver of a polished world.

  • Run it with Ollama (the de-facto runner — pull a model by name) or LM Studio (a polished GUI). Get models from Ollama's library, LM Studio's in-app browser, or Hugging Face; the Qwen Coder and DeepSeek Coder families are among the stronger open coding models.
  • Both clients in this guide can point at a local model. Claude Code talks to Ollama's Anthropic-compatible API — set ANTHROPIC_BASE_URL=http://localhost:11434 and ANTHROPIC_AUTH_TOKEN=ollama, then map its model-tier variables to your local model. Codex runs local with codex --oss, or a [model_providers.ollama] block in ~/.codex/config.toml. Prefer a local-first agent instead? Aider (terminal) and Cline (in your IDE) are built for it.
  • Hardware is the real limit. It is RAM/VRAM-bound — roughly 16–32 GB for small or quantized models, 32–64 GB for mid-size coding models, and 64 GB+ for the larger ones. Claude Code also wants a large context window (64k+), which raises the bar.

Either way the workflow below is identical: point the agent at /api/sections/<section>.md and /api/validate just the same.

Fastest start: World-Puppeteer

World-Puppeteer is a community-built, customised Claude Code setup for exactly this task. It runs in VS Code or Cursor through the Claude Code extension, with a .claude/ config that gives Claude a worldbuilder persona: it interviews you about your vision, then spawns a troupe of specialist sub-agents — one per content type (NPCs, locations, items, quests, factions, traits, triggers, and more) — that write the tabs/*.json files, with validation hooks that catch malformed content before the build.

To start in minutes, clone it and follow its SETUP.md rather than building the structure by hand. You'll need VS Code or Cursor with the Claude Code extension and Node.js (plus an optional Gemini API key if you want it to generate portraits). The rest of this guide still applies either way — it explains the moving parts Puppeteer automates, and works with any agent (Codex included), not just this Claude Code setup.

Prerequisites

  • An agent. Either the Claude track — Claude Code (the CLI, also available in your IDE) or Claude Cowork (the desktop app, paid plan) — or the Codex track — the Codex CLI or its desktop app (paid ChatGPT plan or API key).
  • A working folder for the project. Your world JSON lives here (in ./worlds), alongside the agent's instruction file.
  • A world JSON to edit. In the Voyage editor, create a new world, toggle JSON (top-right), and copy the whole document into a file in your working folder — ./worlds/my-world/world.json is a good spot. That editor-generated JSON is always current and valid, which makes it the right starting point.
  • Comfort running a terminal command if you take the CLI route. The desktop clients need less of this.

Set up the project structure

Both ecosystems use the same idea: a plain-text instruction file at the project root that the agent reads every session, plus optional reusable "skills" it can pull in on demand.

Claude (Claude Code / the IDE extension):

  • CLAUDE.md at the project root — your standing instructions: what the project is, the per-section workflow, and where worlds live.
  • ./.claude/skills/<name>/SKILL.md — optional reusable skills, for example one per schema section carrying that section's field rules and the endpoint to consult.

Codex (CLI / IDE):

  • AGENTS.md at the project root — the same role as CLAUDE.md. Codex reads it for project conventions.

A minimal layout:

voyage/                       # your working folder
├── worlds/
│   └── my-world/             # one folder per world
│       └── world.json        # pasted from the editor's JSON toggle
├── CLAUDE.md                 # Claude's standing instructions (AGENTS.md for Codex)
└── .claude/
    └── skills/
        └── npcs/
            └── SKILL.md      # optional per-section authoring skill

Work out of one folder, and keep returning to it. In Claude Cowork, set that folder as the working folder and reuse the same conversation for all your Voyage work, so the world's context carries across sessions. With the Claude Code CLI, cd into the folder, start the agent, and use /resume to continue your previous session instead of starting cold. Codex is the same: run codex resume --last (or codex resume to pick from history) to continue a prior session in that folder. The CLAUDE.md/AGENTS.md and .claude/skills/ conventions above are read by the CLI and IDE tools; the desktop apps run the same engine on the same folder.

For anything bigger than a quick edit, use the agent's plan mode first — Claude Code's plan mode, or Codex's plan/approval controls — so it proposes an approach for you to approve before it touches files.

Keep the instruction file short and durable — it is reloaded every session, so it should carry rules, not raw data the agent can fetch. A workable CLAUDE.md (or AGENTS.md) skeleton:

# Voyage V33 worlds

This project builds and edits Voyage V33 worlds. Each world lives in its own
folder: `worlds/<name>/world.json` (the source of truth). Work on whichever world
the task names. Validate after every change; never call a section done until the
validator is clean.

Workflow (per section)

  1. Fetch only that section's rules first: GET https://unofficial.voyage/api/sections/<section>.md. Read just that section, never /api/wiki.md or the HTML pages.
  2. Draft or edit the section in that world's world.json, following the field list and rules in the doc you just fetched. If a field is not in that doc, it does not exist; never invent fields.
  3. Validate: POST https://unofficial.voyage/api/validate with the whole world.json as the body. Fix every error; review every warning.
  4. Repeat until clean, then add a dated entry to that world's changelog.md.

Before writing a trigger script, fetch the triggers section doc first; script capabilities are narrow.

Standing rules

  • The fetched section doc is the authority for that section's fields, formats, and limits. Follow it rather than memory; the wiki changes, so don't bake its specifics into your assumptions.
  • A clean validator proves structure, not quality; passing does not mean the content is good. Don't stop at a clean validate.

Canon (for worlds based on existing IP)

  • Verify every canon fact against the source, not memory. Query the setting's wiki API, e.g. https://<wiki>.fandom.com/api.php (action=parse to read a page, action=query to search). If you did not look it up, do not state it.

Per-world notes

  • Keep each world's bible (premise, factions, central conflict, player role) in its own folder, e.g. worlds/<name>/DESIGN.md, and decide it before mass-authoring. CLAUDE.md holds project-wide rules only, not one world's lore.

Wire the agent to the wiki (the API workflow)

The whole method is a tight read-write-check loop, and it lives in the instruction file (or a skill). Three endpoints matter:

  • GET /api/sections.json — once, to discover the section keys (npcs, locations, traits, aiInstructions, and so on).
  • GET /api/sections/<section>.md — per section being worked on. This is the targeted, cheap read: prose, field notes, and the schema fragment for just that section.
  • POST /api/validate — after every change. The body is the entire worlds/my-world/world.json; the response is { counts, errors, warnings, recommendations, validatorVersion }.

Read the validator output by severity: errors will break at runtime (fix them all), warnings might (review each), recommendations are optional quality nudges. The endpoints are CORS-open, unauthenticated, and free, but rate-limited — on HTTP 429 the response carries a Retry-After; slow the loop down rather than hammering it.

A bare-terminal version of the loop, to confirm the wiring before handing it to the agent:

# Field rules for the section you're about to edit (targeted, cheap)
curl https://unofficial.voyage/api/sections/npcs.md

# Validate the whole world after editing
curl -X POST https://unofficial.voyage/api/validate \
  -H 'Content-Type: application/json' \
  --data-binary @worlds/my-world/world.json

Work offline (mirror the wiki)

Some agents — notably ChatGPT and Codex in long-running threads — intermittently fail to fetch live URLs they should be able to reach. Mirroring the wiki to local disk once sidesteps that entirely and cuts repeat fetches (which saves tokens). The wiki ships a copy-paste script for it: see Mirror the wiki for an offline agent on the API page (bash and PowerShell versions; the section loop is driven from the live manifest, so each run always covers every current section).

Once mirrored, point your instruction file or skills at the local files instead of URLs — for example, tell the agent to read ./voyage-wiki/sections/<section>.md rather than fetching the endpoint. A small offline skill is just a SKILL.md that says where the mirror lives and to read section docs from there. Validation still goes to POST /api/validate (or a locally run validator, if you set one up).

The mirror is a point-in-time snapshot, not a permanent copy: the wiki changes (schema bumps, corrected field rules, new or removed sections), so re-run the script every so often to refresh it. Validating against the live /api/validate still catches schema drift even when your local docs have fallen behind.

Building on an existing IP

If your world is based on an existing setting (an anime, game, or book series), the agent will happily invent "canon" from its training data — and get it subtly wrong. Give it an authoritative source instead. Most fan wikis run on MediaWiki and expose an API at https://<wiki>.fandom.com/api.php (action=parse to pull a page, action=query to search), so the agent can look up characters, locations, and events and verify facts rather than recall them.

Think of it as two reference layers: this wiki's API tells the agent how V33 works (fields, limits, validation); the source's wiki tells it what is true in the setting. Put both in your instructions — for example, "for any canon fact, query https://<wiki>.fandom.com/api.php and use what it returns; never state lore from memory" — and you get a world that is both structurally valid and lore-accurate.

Example prompts

Concrete prompts to drive the loop. Adapt the bracketed parts to your world.

Kick off a session, after opening the working folder:

You're helping me build a Voyage V33 world in worlds/my-world/world.json. Rules: before editing
any section, fetch its field rules from
https://unofficial.voyage/api/sections/<section>.md and use only the fields shown
there — never invent fields. Each keyed-map entry's outer key must be identical to
its inner "name". After every change, validate by POSTing the whole worlds/my-world/world.json to
https://unofficial.voyage/api/validate and fix all errors before continuing.
Start by fetching /api/sections.json and listing the sections we'll need.

Design before building, a good moment to use plan mode:

Before writing any JSON, interview me about this world: premise, tone, the main
factions and their conflict, and the player's role. Then propose a build order
for the sections. Don't edit files yet.

Author one section:

Let's do the NPCs section. Fetch /api/sections/npcs.md first. Then draft 5 NPCs
that fit [premise], using only documented fields, key = name, with real
hiddenInfo and personality. Validate worlds/my-world/world.json and fix everything before showing
me the result.

Validate and fix:

Validate worlds/my-world/world.json against https://unofficial.voyage/api/validate. Fix every
error, then list the warnings with a suggested fix for each so I can decide.

Pitfalls

  • Hallucinated fields. Agents confidently invent fields that do not exist. The cure is the per-section doc — make the agent read it and treat the schema fragment as the whitelist.
  • Drift over long sessions. The agent forgets rules as context fills. Keep the rules in CLAUDE.md/AGENTS.md so they reload every session, rather than relying on memory.
  • Validator as a quality check. It verifies structure and references, not whether the writing is good. Read the content yourself.
  • Whole-wiki fetches. The quickest path to a surprise bill. Fetch single sections.
  • Rate limits. 429 means back off, not retry instantly.

Where to go next

  • When you're done, paste worlds/my-world/world.json back into the editor's JSON toggle — where you copied it from — to play or publish.
  • Full endpoint reference: API.
  • Check a world in the browser: Validator.
  • Section field rules: browse World, Mechanics, AI, and Other, or fetch /api/sections/<section>.md.
  • Ready-made toolkit: World-Puppeteer.