Build a World with an AI Agent | Unofficial Voyage Wiki

Overview

In a hurry? One line does the setup. Paste this into your agent:
Read https://api.unofficial.voyage/agent-setup.md and follow it.
It creates the working folder, writes the agent's instruction file, optionally sets up a Voyage API key the safe way, and hands back. Everything below explains what that page does and why.

A Voyage world is a large structured JSON document, and this wiki publishes the Voyage schema in a machine-readable form: per-section docs, the raw codec, and a validator endpoint. That combination makes a coding agent — Claude, Codex, Gemini, or another capable tool — 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 as worked examples. See Choose an agent for the popular options and their own setup docs.

New to all this? Jump to the Quickstart for the shortest path, then come back for the detail. Or, if you would rather not wire it up by hand, see Fastest start: World-Puppeteer.

Voyage has its own API too. Every account can create an API key in Voyage Studio under Settings → API keys, and Voyage documents the endpoints at beta.voyage.io/studio/api-docs. New to API keys? Push with a Voyage API key starts with what one is and who needs one. With a key, an agent can pull a world and push the finished JSON directly instead of the copy-and-paste round trip through the JSON toggle described below. This guide does not cover that API, since it is Voyage's and can change; follow their docs for it. The wiki's endpoints stay the schema reference and the validator either way, and the loop is the same: read the section rules here, write, validate here, then push through Voyage.

Quickstart

New here? Do these six steps in order — the sections below just go deeper on each. Or let the agent do steps 2 to 4 itself: paste Read https://api.unofficial.voyage/agent-setup.md and follow it. and answer its questions.

Pick and install one agent from Choose an agent — Claude, Codex, or Gemini — following that vendor's own install guide.
Make a working folder anywhere on your computer, with an empty worlds/ folder inside it.
Get a starting world. In Voyage Studio, create a new world, toggle JSON (top-right), and paste the whole document into worlds/my-world/world.json.
Add one instruction file at the folder root so the agent reloads the rules every session — CLAUDE.md for Claude, AGENTS.md for Codex, GEMINI.md for Gemini. Paste the skeleton from Set up the project structure.
Open that folder in your agent and paste the kickoff prompt from Example prompts.
Let it loop, and steer. For each section the agent fetches the field rules, writes JSON, validates, and fixes errors; you review and guide it. When you are happy, paste world.json back into Studio's JSON toggle to play or publish, or let the agent push it through Voyage's API with a key from Settings → API keys.

That is the whole workflow. Everything below is detail: what it costs, running a model locally, working offline, and exactly what to put in the instruction file.

Choose an agent

The loop in this guide is tool-agnostic — any capable coding agent can drive it, and each vendor documents its own setup. Pick one and follow its docs for how to run it and connect it to tools:

Anthropic Claude — Claude Code (CLI and IDE), or the Claude desktop app.
OpenAI Codex — Codex (CLI, IDE, and cloud).
Google Gemini — Gemini CLI.
Cursor and other IDE agents — Cursor docs.

Each reaches this wiki's API over plain HTTP, so nothing special is needed to start. Several also speak the Model Context Protocol — the open standard for giving an agent tools and data sources — if you would rather wire the API in as a first-class tool than fetch URLs by hand.

The rest of this guide uses Claude and Codex as worked examples, but every step maps to any agent: swap the instruction-file name (CLAUDE.md, AGENTS.md, GEMINI.md, ...) and the run commands for your tool's equivalents.

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 https://api.unofficial.voyage/sections/<section>.md (for example https://api.unofficial.voyage/sections/npcs.md). That is a few KB.
Don't: pull the whole reference every turn. https://api.unofficial.voyage/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 https://api.unofficial.voyage/sections/<section>.md and https://api.unofficial.voyage/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 Studio, 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. An agent holding a Voyage API key can fetch the same document itself; see Voyage's API docs.
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:

markdown

# Voyage worlds

This project builds and edits Voyage 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.

If the agent will push through Voyage's API, append the block from Push with a Voyage API key as well.

Workflow (per section)

Fetch only that section's rules first: GET https://api.unofficial.voyage/sections/<section>.md. Read just that section, never https://api.unofficial.voyage/wiki.md or the HTML pages.
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.
Validate: POST https://api.unofficial.voyage/validate with the whole world.json as the body. Fix every error; review every warning.
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 https://api.unofficial.voyage/sections.json — once, to discover the section keys (npcs, locations, traits, aiInstructions, and so on).
GET https://api.unofficial.voyage/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 https://api.unofficial.voyage/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:

bash

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

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

Push with a Voyage API key

Note: What is an API key? An API key is a password for programs. A tool or an agent acting on your behalf cannot type your login into a browser, so Voyage gives it a long secret string instead, and the tool sends that string with every request to prove it is you. Whoever holds the key can do to your worlds whatever your account can do, which is why most of this section is about keeping it private.

You do not need one to use Voyage, Studio, this wiki, its builder, or its validator. You only need one if a program should read or write your worlds directly: an agent that pushes a finished world for you, or a script you wrote. If you copy and paste JSON by hand, skip this section.

It is not your Voyage password, and it is not an AI provider key. Claude, Codex and Gemini have their own keys or subscriptions that pay for the model; a Voyage API key only opens the door to your worlds. An agent that pushes directly needs both, and neither replaces the other.

Voyage shows the key once and can rotate or delete it at any time. A tool still holding an old key simply stops working, so rotating is the safe reflex whenever you are unsure whether a key was seen.

Voyage issues API keys in Studio under Settings → API keys: give the key a label (for example, the agent it is for) and press Generate. The panel's API docs button opens Voyage's own reference at beta.voyage.io/studio/api-docs. With a key, the agent can pull the live world and push the finished JSON itself, so the paste round trip through the JSON toggle disappears. The endpoints and payloads are Voyage's to define and change, so this guide only covers two things: keeping the key safe on your machine, and telling the agent how the two APIs fit together.

Keep the key out of everything the agent reads or writes. The key acts as you on your worlds, so treat it like a password:

The secret is shown once, when the key is generated or rotated, so copy it straight into a .env file at the folder root (VOYAGE_API_KEY=...) or into your shell's environment. Nowhere else: not in CLAUDE.md/AGENTS.md, not in a prompt, not in world.json, not in a skill file.
Add .env to .gitignore before the first commit, and keep the folder out of any cloud-synced location that would copy the file elsewhere.
Refer to it by name only. Commands read $VOYAGE_API_KEY; the value itself should never appear in the conversation, because agents echo command output and transcripts are stored.
Use one key per project. If it ever shows up in a log, a transcript, or a pasted screenshot, press Rotate in the same panel (or Delete it) and update .env with the new secret, rather than hoping it was not seen.

Tell the agent the order of operations. Add this block to your instruction file, under the skeleton from Set up the project structure:

markdown

# Voyage API (pull and push)

Voyage's API is documented at https://beta.voyage.io/studio/api-docs. Read that page
before the first call and follow it for endpoints and payloads; never guess them.

The key is in the VOYAGE_API_KEY environment variable, loaded from .env. Never print
it, never write it into any file, and pass it only in the form the docs specify.

For every change, in this order:
1. Fetch the section rules from https://api.unofficial.voyage/sections/<section>.md.
2. Edit worlds/<name>/world.json.
3. Validate at https://api.unofficial.voyage/validate until there are no errors.
4. Only then push through Voyage's API. If Voyage rejects the push, fix what it
   names and validate again; do not retry the same payload.

Pull the live world at the start of a session and compare it with the local file
before editing, so edits made in Studio are never overwritten.

The wiki stays the schema reference and the first validator in that loop; Voyage's own checks run on the push, and anything they flag goes back through the same fix-and-validate cycle.

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 https://api.unofficial.voyage/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 https://api.unofficial.voyage/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 the schema 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 world in worlds/my-world/world.json. Rules: before editing
any section, fetch its field rules from
https://api.unofficial.voyage/sections/<section>.md and use only the fields shown
there — never invent fields. In keyed maps the outer key must be identical to
the inner "name" (quests are the exception). After every change, validate by POSTing the whole worlds/my-world/world.json to
https://api.unofficial.voyage/validate and fix all errors before continuing.
Start by fetching https://api.unofficial.voyage/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 https://api.unofficial.voyage/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://api.unofficial.voyage/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.
Leaked keys. An agent repeats what it sees, and transcripts persist. A Voyage API key belongs in .env and in the environment, never in a prompt or an instruction file.

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. Or skip the paste: create a key in Studio under Settings → API keys and have the agent push through Voyage's API.
Full endpoint reference: API.
Check a world in the browser: Validator.
Section field rules: browse World, Mechanics, AI, and Other, or fetch https://api.unofficial.voyage/sections/<section>.md.
Ready-made toolkit: World-Puppeteer.

#Overview

#Quickstart

#Choose an agent

#What it costs (read this first)

#Running a model locally (optional)

#Fastest start: World-Puppeteer

#Prerequisites

#Set up the project structure

#Workflow (per section)

#Standing rules

#Canon (for worlds based on existing IP)

#Per-world notes

#Wire the agent to the wiki (the API workflow)

#Push with a Voyage API key

#Work offline (mirror the wiki)

#Building on an existing IP

#Example prompts

#Pitfalls

#Where to go next