# Publish to the Moonspell app

> Local developer mode, step by step - build a Moonspell game on your own computer with your own coding agent, then publish it to the Moonspell app on iPhone and Android and to the web with the built crescent CLI.

Local developer mode lets you build a game on your own computer with the coding agent you already use (Claude Code, Codex, Cursor or another), on your own subscription, and publish it to the Moonspell app. Moonspell runs no model for this and charges nothing. When the game plays, one command publishes it to the Moonspell app on iPhone and Android and to the web, and gives you a link and a QR code to play it on your phone.

Use this path when you want your game in the Moonspell app. To use the engine on its own, with no account, follow [Quickstart](https://docs.moonspell.app/start/quickstart.md) instead. [What is open and what is private](https://docs.moonspell.app/start/open-source.md) explains how the two paths relate.

## What you need

- Node.js 20 or newer, npm and git.
- A Moonspell account with Google. You sign in on moonspell.app; the CLI opens the page for you.
- A coding agent that can run commands in a folder. MCP support helps but is not required.

## Start a new game

```bash
npx https://moonspell.app/api/dev/cli/latest.tgz init my-game
cd my-game
```

`init` downloads the starter, installs its packages and makes the folder a git repo. The starter is the open-source game template (the engine, the examples, the skills) plus agent instructions and settings for this mode. The `crescent` CLI comes with it as a dev dependency, in built form; its source is private.

Open the folder with your agent and say what game you want: "a one-thumb endless runner on rooftops at night", "chess against a cheeky computer", "a racing game with five rivals in the rain".

The agent reads `AGENTS.md` (Claude Code reads the identical `CLAUDE.md`) and from there:

1. Signs you in. It gives you a link and a code: open the link, sign in with Google and approve the code.
2. Registers the game on your account and connects the folder to the game's private repo on Moonspell.
3. Builds the game, and saves every change to that repo. A save is private: nobody else sees it.
4. When the game plays from start to finish, tells you that publishing makes it public and asks you to go ahead.
5. Publishes: builds it for iPhone, Android and the web, and answers with the share link `https://moonspell.app/g/<buildId>`, a QR code, and the game's page for developers, `https://moonspell.app/dev/<gameId>`.

Scan the QR code with your phone: the link opens the game in the Moonspell app, or in its App Clip on an iPhone without the app. The game also shows in your own games in the app.

While you work, `npm run web` shows the game in your browser, as in the [Quickstart](https://docs.moonspell.app/start/quickstart.md#3-run-it-in-the-browser).

> **Warning: Every published version is public at once**
>
> It is in the Moonspell feed for every player, anyone with its link can play it, and other players can build on it in the app ([community builds](https://docs.moonspell.app/moonspell/community-builds.md)), like any game made in the app. There is no private or unlisted version. Your repo stays private.

## Continue a game you made in the app

On the web, each of your games has a **Continue building on your PC** button. It gives you a prompt to paste into your agent, which runs `npx <cli url> continue <gameId>`: that downloads the game's source into a new folder and adds the files listed below. The game already has players, so every version you publish from there is an update they all get.

For a game made in the app, `continue` adds the files the game lacks. `AGENTS.md` and `CLAUDE.md` replace the game's copies while those are still the template's; a copy the builder changed is kept as `AGENTS.game.md` or `CLAUDE.game.md`, and the agent reads both. `.claude/settings.json` keeps the game's own settings and gains the permissions and the save hook. This works for any game of yours, wherever it was made, and for a game you were invited to build.

## Start from the Moonspell MCP server

If your agent is connected to the [Moonspell MCP server](https://docs.moonspell.app/ai/mcp.md), its `moonspell_start` tool gives you the command for your case, with a one-time sign-in code (it works once, for 5 minutes), so you do not sign in again in the browser:

| Case | Command |
| --- | --- |
| A new game | `npx <cli url> init <dir> --code <code>`, optionally with `--title "<title>"`. It signs in, unpacks, installs and registers the game. |
| A game with a repo | `npx <cli url> continue <gameId> [dir] --code <code>` |
| A game registered on your account that has no repo yet | `npx <cli url> init <dir> --code <code> --no-create`, then in the folder `npx crescent link <gameId>` and `npx crescent save` |

## What is in the folder

| Path | What it is |
| --- | --- |
| `AGENTS.md`, `CLAUDE.md` | The rules and the work loop for your agent (the same text). |
| `.claude/skills/*/SKILL.md` | How to build each kind of game, the engine's pieces, sound, UI, saves. Plain Markdown: any agent can read them. See [Skills](https://docs.moonspell.app/ai/skills.md). |
| `.claude/skills/moonspell-dev/` | Signing in, saving, publishing, links, invites, updates, and what is not available on your computer yet. Its `assets.cjs` makes placeholder models, images and sounds. |
| `.mcp.json` | Registers the Moonspell MCP server as `moonspell` (`https://mcp.moonspell.app/mcp`, signed in with Google). |
| `.claude/settings.json` | For Claude Code: permissions for the `crescent` commands and the MCP tools, and a Stop hook that saves at the end of each turn. |
| `.claude/hooks/moonspell-save.cjs` | That hook. It runs `crescent save --auto` in the background when something is left unsaved, is quiet otherwise, and never blocks the turn. |
| `.moonspell/game.json` | Which Moonspell game this folder is. Written when the game is created or linked; committed. |
| `.moonspell/overlay.json` | The list of files this mode adds, for `crescent continue` and `crescent sync`. |
| `src/game/`, `src/engine/`, `assets/`, `docs/`, `examples/` | The game, the engine, its assets, docs and example games. See [Project structure](https://docs.moonspell.app/start/project-structure.md). |
| `GDD.md` | The game's design document, which the agent writes and keeps up to date. See [GDD.md and playtest.json](https://docs.moonspell.app/ai/game-design-doc.md). |

## The `crescent` commands

`crescent` is the folder's own CLI (the `crescent-cli` dev dependency). It does everything that touches the folder's files and signs in on its own once (`npx crescent login`). Run it as `npx crescent <command>`; run `npm install` first if `node_modules/` is missing, so `npx` finds it in the folder. `npx --no-install crescent mcp` starts a local MCP server with the same tools, for agents that cannot use the remote server.

| Command | MCP tool | What it does |
| --- | --- | --- |
| `npx crescent login`, `logout`, `whoami` | `moonspell_login`, `moonspell_status` | Sign in with Google, sign out, show who you are and which game this folder is |
| `npx crescent create --title "<title>"` | `moonspell_create_game` | Register this folder as a new game |
| `npx crescent link <gameId>` | `moonspell_link_game` | Work on a game you collaborate on, or on a second computer |
| `npx crescent continue <gameId>` | `moonspell_continue` | Bring a game made in the app into a new folder |
| `npx crescent save -m "<message>"` | `moonspell_save` | Commit and push to the game's private repo |
| `npx crescent publish -m "<notes>"` | `moonspell_publish` | Save (bringing in what collaborators pushed), then publish that commit as a public version: three builds, a link, a QR code, the developer page |
| `npx crescent links` | `moonspell_links` | The latest version's link, QR code and developer page |
| `npx crescent invite play`, `invite build` | `moonspell_invite` | A link to play, or to become a collaborator |
| `npx crescent sync` | `moonspell_sync_engine` | Bring the engine, skills and docs up to date, keeping files you changed |
| `npx crescent skills [name]` | `moonspell_skills`, `moonspell_skill` | The engine's skills from this folder: the list, or one skill's text |

`publish` needs an iOS build to succeed. The Android and web builds are best effort: a platform that fails to build is left out of that version, and the command says why.

## Your agent

- **Claude Code**: open the folder (`claude`). It asks once to trust the folder and to use the `moonspell` MCP server; say yes, and sign in with Google when it opens the browser. The Stop hook saves at the end of every turn as a safety net.
- **Codex, Cursor and others**: they read `AGENTS.md`, which tells them to load the engine's skills through the MCP server (`moonspell_skills`, then `moonspell_skill`) or with `npx crescent skills <name>`. Add the remote server `https://mcp.moonspell.app/mcp` ([setup](https://docs.moonspell.app/ai/mcp.md)). An agent that cannot use a remote server runs the CLI's local one instead, configured in the folder as below (on Windows an MCP client may need `cmd /c npx ...`). Without MCP, the agent uses the commands.

```json
{
  "mcpServers": {
    "moonspell-local": {
      "command": "npx",
      "args": ["--no-install", "crescent", "mcp"]
    }
  }
}
```

## Not available on your own computer yet

- Generated 3D models, 2D art and sounds. The agent uses placeholders and the engine's fallbacks, and lists what the game wants in `.moonspell/models.json`, `sprites.json` and `sounds.json`. Files you make or own can go at the same paths.
- The game's own online backend (live leaderboards, "N playing now", online rooms, synced saves). Scores and progress stay on the phone for now, through the same engine API.
- Feed videos. Moonspell makes them from the game's `playtest.json`.

## How it works on the server

The routes, sign-in and uploads behind this mode are on [Local developer mode](https://docs.moonspell.app/moonspell/local-dev-mode.md), in "How Moonspell works".