Studio Setup

Set up a studio

A Homie studio is ONE folder the person can see and open: AGENTS.md (+ CLAUDE.md importing it), games/, music/, videos/, posts/, and a site: a Cloudflare Worker with a D1 database and the Table/Lobby Durable Objects that serve the studio's pages and its public game rooms from the studio's own Cloudflare account, on Cloudflare's free Workers plan. The code comes from @homie-rocks/studio, pinned in the studio's package.json. The person never types a command: you run everything, and they approve what matters (Cloudflare, once, in their browser). Homie for studios is in beta.

The new-studio checklist

Every new studio goes through this list, in this order. Show it in your first reply and again, ticked, whenever a step finishes, so the person always knows where they are:

New studio: Night Owls
  ✓ 0. Setup status: ready to make and check games; Cloudflare when we go online
  ✓ 1. The studio: ./night-owls
  → 2. See a working game (a live one on Homie Arcade; a copy in your studio only if you ask)
    3. One small change, from one sentence of yours
    4. Plan your game together: its Game Codex
    5. Build it (one agent, or several in parallel), with progress you can watch
    6. Playtest it, then put it online

Never jump ahead. Each step ends with the person seeing something (a checklist, a game that plays, their change, the codex page), and the next starts when they say so. Keep it natural, not a form: a short message per step, one question at a time (the plan's interview asks two or three), always with a default they can take by saying "yes".

Asked for everything at once ("set up a game studio called X and make a multiplayer game", "just make it", or a prompt with nobody to answer): show the list, then do not stop to ask. Make your own choices for steps 2 to 4 (say each in one line: step 2 is the demo's link, since their own game is what goes into the studio), write the codex from them with what you chose listed under Open questions, and go on through step 6. Offer the plan interview at the end, as the way to change the game.

A Play link first. Build the game to the point where it plays, run the two-browser check, and the moment it passes tell the person, with the link they can open now (http://127.0.0.1:8787/<id>/play, two tabs for two players): a first run should have someone playing in minutes, not after an hour of polish. Only then go on to sound, art, the playtest's fixes and the landing page, saying in a line what you are doing next.

0. Setup status, first

Before anything is made, and whenever the person asks what they need, whether they are set up, or is waiting (a usage limit resetting is a good time), run the setup status. It only reads, takes a few seconds, and never prints a key:

1. With the Homie connector (the Homie MCP tool studio_scaffold is in your tool list), call it with the studio's name (if they have not named it yet, use "My Studio" for now; it only reads). It returns the exact pinned command, like npx -y @homie-rocks/studio@<version> new "<folder>" --name "<Name>" --homie https://homie.rocks, and a numbered list of next steps: this checklist decides the order, not that list. Without the connector, go on ("Without the connector" below): the toolkit is @homie-rocks/studio on npm, and @latest is its version here.

2. Run that same package with setup status instead of new ...: npx -y @homie-rocks/studio@<version> setup status --connector yes --json (inside a studio: npx --no-install homie-studio setup status --connector yes --json). If it does not know setup status (a toolkit older than 0.11.0 calls it unknown, or asks for a studio first), run npx -y @homie-rocks/studio@latest setup status --connector yes --json for the status only (it only reads). --connector yes because the Homie tools are in your tool list; if studio_scaffold is not there, say --connector no and run it from @latest. In Codex add --client codex, in Grok Build --client grok: the status then says whether Homie's holds are on (item 6), and when another MCP server has taken the connector's name.

3. Show it as one short checklist, a line per row: ✓ ready, → do this now, ○ optional, ... later. Each line says what the row unlocks (its unlocks) and, when it is not ready, the exact fix (fix.run: a command you run; fix.open: a page the person taps; fix.say: the words):

   Setup status
     ✓ Node.js, Chrome, ffmpeg: you can make, check and sound games here
     ✓ Homie connector: the directory, and the cards where your app draws them
     ... Cloudflare: needed to go online (step 6). No account yet? Make a free one now:
       https://dash.cloudflare.com/sign-up (no payment method), and click the email it sends.
     ○ GitHub (optional): a private backup and publishing by pull request
     ○ ElevenLabs (optional): songs and game scores, on your own plan
     ○ fal (optional): painted art and generated video, on your own account, under a budget
     ○ Clef on this computer (optional, inside a studio): AI guides and game decisions under dev, free

4. Never block on an optional row. Say what it unlocks and that it can wait until that feature is wanted; the skill that needs it (music, art, video) offers it then. A "do this now" row you can do (fix.run, like npx wrangler login or brew install ffmpeg): offer it, and run it when they agree. A row the person does on their own (fix.open) can be done any time, even while they wait for something else: give them the link. The "Clef on this computer" row is the person's download: say its size first (ollama pull clef-flash, about 11 GB) and run it only after their yes.

5. Run it again whenever they say they did something, and tick the row.

6. Homie's holds (Codex, Grok Build). With --client the status has a holds row: whether Homie's hooks ran just now in this app ("on": true). When it is off, say so in one sentence in this first reply, with the row's fix. In Codex: "Homie's holds are off in this session: open /hooks and trust Homie's three hooks. Until then I'll ask you before a deploy, a Cloudflare change, a paid call or a model download." In Grok Build they are off as of 1.0.41, which runs no plugin's hooks: "Nothing holds a deploy in Grok yet, so I'll ask you before a deploy, a Cloudflare change, a paid call or a model download." Then do ask, every time, also when the app approves commands for you. When it is on, say nothing about it and change nothing: the hooks hold what they hold. A status with no holds row in Codex or Grok (a toolkit before 0.30.2) cannot tell: say the sentence anyway.

Without the connector, with a shell: go on. A studio is made, checked, put online and listed with the studio's own commands; the connector is not needed for any of it. When the Homie tools are not in your tool list and you can run commands:

• Say it once, in one line: "The Homie connector is not connected in this app, so I'm making the studio with its own commands. Connected, it adds the homie.rocks directory search (remixing a game from it), the cards where an app draws them, and notes to Homie."
• The status is npx -y @homie-rocks/studio@latest setup status --connector no --json. Its connector row says why when it can tell: another MCP server named homie is set up in this app and has taken the name the plugin's connector uses. Its fix.run adds Homie's connector under its own name: offer it, run it only with the person's yes, and never wait for it.
• The studio is npx -y @homie-rocks/studio@latest new <folder> --name "<Name>" (step 1), and from then on npx --no-install homie-studio … inside it.
• Where a step names a Homie MCP tool, run the command the same step names beside it (game new, deploy, publish, stats). Tell Homie is the connector's homie_feedback (in Claude Code also /feedback): where neither is here, make no offer.

Stop only when there is neither the Homie tools nor a way to run a command. Then say exactly how to add the connector in that app, and stop: Claude Code, /plugin, install or enable "homie" (marketplace homie-rocks/homie), and /mcp shows it connected; Codex, codex plugin marketplace add homie-rocks/homie then codex plugin add homie@homie and a new session; Grok Build, grok plugin install homie-rocks/homie#plugins/homie and a new session; the Claude app, Grok chat or another app with connectors, a custom connector at https://homie.rocks/mcp.

Each provider's own tools, lazily. Homie works through each provider's own CLI, plugin or MCP server (Wrangler for Cloudflare, the GitHub CLI, ElevenLabs' CLI, fal's MCP server), never a copy of their code: the plugin's providers.json lists them, with what stays Homie's (budgets and receipts, the kids rules, the owner's one-tap asks, secrets never in the chat, the rights notes). Offer one only when the person wants what it unlocks, in the skill that needs it; they approve every install and sign in on the provider's own page.

The status line (Claude Code only). The moment the studio exists (end of step 1), add one line to your reply offering it: "Want the build's progress as a line under the prompt? Say yes and I'll turn it on." On a yes: npx --no-install homie-studio statusline --install (--remove takes it away). Claude Code reads the setting from the folder it was started in: if that is the folder above the studio (you made the studio as a subfolder), add --project <that folder>. It never replaces a status line they already have; if it says so, leave theirs. Never turn it on unasked. In Claude Code 2.1.287 or later the Homie mod (part of this plugin) already draws the studio's band above the prompt and the Studio pane (/studio), so offer the status line only to someone who wants the line under the prompt as well.

Homie's holds in Codex. In Codex, Homie's hooks hold what the mod holds in Claude Code: an edit to a file studio.json "protect" lists, a production deploy, a change to the studio's Cloudflare account outside its deploy, a paid call past the budget or whose cost cannot be read first, and a Clef model download; they refuse what the mod refuses, and take secrets out of what you read. Codex runs a plugin's hooks only after the person trusts them once: after installing Homie, tell them to open /hooks and trust Homie's three (until then nothing is held, so ask before each of those yourself). Never assume they are on: the setup status says which it is (item 6 above). A held call comes back refused with a code, and the person sees what it holds: say in a sentence what it would do and ask. They answer in their own message, proceed <code> (that exact call goes through once) or cancel <code>; then run exactly the same call again, or not at all. Never write that answer yourself, in a command or a file: only the person's own message counts. node <this plugin's folder>/hooks/codex.mjs check -- <command> (the folder above skills/) says what Homie would do with a command, and runs nothing.

Homie's holds in Grok: off, so you ask. Homie ships the same hooks for Grok Build (hooks/grok.json, deciding with the module the mod and the Codex hooks ask, hooks/lib/holds.mjs), but Grok Build 1.0.41 runs no plugin's hooks: in its headless and agent sessions none are registered, from any plugin (checked 2026-10-04), and a deploy went through unasked. So in Grok, Build or chat, nothing is held and nothing is taken out of what you read: before a production deploy, a Cloudflare change outside that deploy, a paid call, a model download or an edit to a file studio.json "protect" lists, say what it would do in one sentence and wait for the person's yes, also when Grok approves commands by itself; and never repeat a key or a token you read. The setup status with --client grok says "Homie's holds: off" (item 6 above). If a later Grok runs the hooks, that row turns on by itself: then a held call comes back denied with a code, and the person answers proceed <code> or cancel <code> in their own message, as in Codex. node <this plugin's folder>/hooks/grok.mjs check -- <command> says what Homie would hold, and runs nothing: use it to know what to ask about.

Grok and Grok Bot

In Grok Build the Homie plugin brings the connector (its tools read homie__studio_scaffold and the like); its hooks do not run there yet (above). Say --client grok to the setup status. In Grok chat the connector is https://homie.rocks/mcp, once the person has added it. Use the one that is here; with neither, and a shell, go on without it (step 0). Do not send the person to Claude's GitHub app, to claude.ai/code, or to a button that only says "Connect to Claude". The studio's first-run band says Connect this chat.

• Cloudflare stays one tap on Cloudflare's own page. Grok has no Cloudflare connector and must never ask for a token. On a phone, the setup card's "Make the studio on Cloudflare" is that tap. On a computer, npx wrangler login opens the same approval.
• This computer is a Grok Bot, or Grok Build with a folder. Run the checklist here. When the chat has a setup id hs_…, check in once from the studio's own repository: npx --no-install homie-studio setup attach <hs_…> --client grok. That tells the directory Grok works in this repository. It does not need Claude's GitHub app. GitHub, when this chat already has it, is enough to push the branch and open the pull request.
• A build the chat opened (hb_…): npx --no-install homie-studio handoff <hb_…> --client grok. The session fetches the brief itself. There is no Claude Code window to open, and no second session to start.

1. The studio

Ask for a name if there is none ("What should the studio be called? It's the name on your site."). Then say in two or three lines what will happen, and go on: you make the studio folder here (no game in it yet: its home page says "First game coming soon" until the first one is made); later, when it goes online, Cloudflare opens in their browser once to approve (a free account, no payment method); on their account you will create one Worker, one D1 database and two Durable Objects, all free on the Workers Free plan; the homie.rocks directory lists the games (only the site's address, the studio's name, each game's name, blurb and Play link).

1. Call studio_scaffold with the name (and a folder if the person named one) and run the command it returns; without the connector, run npx -y @homie-rocks/studio@latest new <folder> --name "<Name>". Either lists every file it writes and installs the pinned toolkit and wrangler (about 20 s).
2. Folder: the one the person named; otherwise a NEW folder named after the studio's slug inside the current directory (e.g. ./night-owls). Never in a folder that already holds other files, never in the home folder, never outside the current directory. Other studios in the same folder (a folder beside this one with its own studio.json) are other people's work: never read them or copy from them, not even as a model for this studio or its game, unless the person asks. An earlier attempt: if a folder of this name already exists and is not a studio (notes, a plan, a charter from before), say so and ASK whether to fold its premise in: with a yes, copy its notes into the studio's notes/earlier/<folder>/ and use them in the plan; remove the old folder only with a second yes (to the Trash, so it can come back). Never delete or overwrite it unasked.
3. From here on run the studio's own copy: npm run <script> or npx --no-install homie-studio <command> (--no-install never fetches a package by that bare name).
4. In Claude Code, offer the status line in one line (above), then ask about step 2.

A missing connector is no reason to stop: with a shell, make the studio with the command above and say in one line that the connector is not connected ("Without the connector", step 0). Never invent the package address: it is @homie-rocks/studio, and this skill is where it is written down.

2. See a working game

Show a live one; copy nothing. A new studio has no game, and it gets none it did not ask for. npx --no-install homie-studio demo names a live multiplayer game on Homie Arcade (made with this same toolkit) with its Play link: give them the link and say to open it in two browser tabs, or on a phone and a computer, and they are two players in the same public room, with bots in the empty seats. Then ask: "Want a copy of a working starter in your own studio to change, or shall we go straight to planning your game?"

It always names one. Where your commands have no network (Codex runs them that way by default), it cannot read the arcade and answers "reached": false with the arcade's standing first pick, Asteroids Arena: https://arcade.homie.rocks/asteroids-arena/play. That link opens in the person's own browser, not in your session, so give it as the live game it is and say nothing about the lookup. The same address serves when the command cannot be run at all.

Only when they ask for a copy (now, or in their first message): the Gem Rush starter (grab gems, knock rivals away; bots fill the empty seats), or Ember Vale (--from ember-vale: a hero who lasts for days, with cloud saves) when they want a persistent game. To copy one of another studio's games instead, use the game skill's remix.

npx --no-install homie-studio game new <id> --from gem-rush --name "<Name>"
npm run dev                                             # in the background: http://127.0.0.1:8787/<id>/play
npx --no-install homie-studio check <id> --url http://127.0.0.1:8787 --shots ./.checks

check proves it first: two fresh browsers press Play, share a room and see a round finish (about 70 s). Show one of its pictures. Start npm run dev as a background task your app keeps alive (Claude Code: the Bash tool's run_in_background); stop it with npx --no-install homie-studio dev --stop, which stops exactly this studio's dev server and nothing else. Never pkill, killall or lsof ... | xargs kill: other projects on this machine may run their own wrangler dev. Without a game, npm run dev shows the studio's own home page ("First game coming soon") at http://127.0.0.1:8787/.

3. One small change

"Now tell me one thing to change, in your own words." With a copied starter, it is the game: a colour, the speed, what you collect, the name (in games/<id>/). Without one, it is the studio's own home page: its colours (site/theme.json), a tagline (studio.json "tagline"), or a first post ("we're making our first game"; posts/README.md). Make exactly that, npm run build, and tell them to reload. If they say "you pick", make one visible change (the colours, or the name and its colours) and say what it was. This is the whole loop in a minute: they say it, they see it. Keep the change small; the big ideas go into the plan.