Using AI assistants with Modoki

Modoki is built to be driven by an AI coding assistant as well as by hand — game logic runs on an injectable clock, seeded RNG, and a tick-stamped event journal, so an agent can verify behavior headlessly and deterministically, by data rather than screenshots. That works with more than one assistant: every Modoki project ships instructions that Claude Code, Cursor, Codex CLI, and Antigravity CLI all pick up automatically. Live MCP (Model Context Protocol) tool access to the running editor — scene inspection, mutation, screenshots — is a separate story; see the per-tool notes below for what's automatic today and what you still wire up by hand.

Claude Desktop now has three tabs, and they're not equally capable here. Its Code tab is Claude Code — same CLAUDE.md, same .mcp.json connect flow, full modoki_* tool access — just with a GUI (chat/diff/terminal/file panes) instead of a terminal, so if you have Claude Desktop there's no need to open one. Cowork (its project-folder feature) also reads a project's CLAUDE.md automatically, but can't reach the live editor's MCP tools. Plain Chat reads neither and needs the MCP server wired up by hand for tool access. See Claude Desktop below for all three.

What ships with a project, and what doesn't

File	Read by	When you get it
CLAUDE.md	Claude Code	Scaffolded with every new project
AGENTS.md	Cursor, Codex CLI, Antigravity CLI	Scaffolded with every new project
.mcp.json	Claude Code	Written into the project by AI → Connect Claude Code in the editor — not scaffolded upfront
.cursor/mcp.json	Cursor	No auto-connect yet — write it yourself (see below)
.codex/config.toml	Codex CLI	No auto-connect yet — write it yourself (see below)
mcp_config.json	Antigravity CLI	No auto-connect yet — write it yourself (see below)
.mcp.json / CLAUDE.md	Claude Desktop's Code tab	Same as Claude Code (it is Claude Code) — see above
CLAUDE.md	Claude Desktop's Cowork tab	Read automatically once you point a Cowork project at the folder — nothing to write
claude_desktop_config.json	Claude Desktop's Chat tab	No auto-connect, and it's a global file, not per-project — write it yourself (see below)

CLAUDE.md and AGENTS.md carry the same project instructions and are the one thing every tool gets automatically — a fresh File → New Project already has both. MCP tool access (scene inspection, mutation, screenshots) is a separate story: only Claude Code has a one-click "Connect" flow today (AI → Connect Claude Code in the editor's AI panel), which writes a correct, machine-specific .mcp.json into the open project. Cursor, Codex CLI, and Antigravity CLI have no equivalent yet — you can still use them for everything code-and-instructions related (Antigravity built a working 3D game from AGENTS.md alone with zero MCP config), but if you want their MCP tool access too, you currently have to wire it up by hand.

Claude Code

Open the project folder in Claude Code, then run AI → Connect Claude Code in the editor's AI panel — it writes .mcp.json for you. It reads CLAUDE.md automatically either way.

If you have Claude Desktop installed, this is also its Code tab — no terminal required. Open your project folder there instead of running claude in a shell; everything else on this page (Connect Claude Code, CLAUDE.md, the modoki_* tools) works identically, since the Code tab is Claude Code with a GUI wrapped around it.

Cursor

Open the project folder in Cursor. It reads AGENTS.md automatically for project instructions. For MCP tools, hand-write .cursor/mcp.json — after connecting Claude Code once (above), copy its .mcp.json content into .cursor/mcp.json (same mcpServers JSON shape); Cursor also accepts a global ~/.cursor/mcp.json if you'd rather configure it once for every project.

Codex CLI

Run codex from the project root. It reads AGENTS.md for instructions automatically. For MCP tools, hand-write a project-scoped .codex/config.toml — mirror .mcp.json's command/args/ env under a [mcp_servers.modoki] table (Codex also supports a global ~/.codex/config.toml).

Codex silently skips untrusted projects

The first time Codex CLI sees a project-scoped .codex/config.toml, it needs to trust that directory before it will activate any MCP servers defined there — until you confirm that prompt, the tools just don't load, with no error. If Codex "can't see" the MCP tools, this is the first thing to check.

Antigravity CLI

Antigravity CLI (Google's successor to Gemini CLI) reads AGENTS.md for project instructions automatically, same as Cursor and Codex. Its MCP server configuration format (mcp_config.json) is newer and still settling, so there's no auto-connect and no template to copy yet — point it at the same servers Claude Code uses by hand, using .mcp.json's server definitions as a reference (command, arguments, and environment variables per server).

Claude Desktop

Claude Desktop has three tabs, and which one you use changes what you get. If you have Claude Desktop at all, use the Code tab — it's the easiest way into the full loop with no terminal.

Code (recommended)

The Code tab is Claude Code, running with a GUI (chat/diff/terminal/file panes) instead of a shell. Nothing here is different from the Claude Code section above — open your project folder in the Code tab, run AI → Connect Claude Code in the editor once, and you get automatic CLAUDE.md, a written .mcp.json, and full modoki_* tool access (scene inspection, mutation, screenshots) against the live editor. This is the recommended path for anyone who has Claude Desktop and would rather not open a terminal.

Cowork

Cowork is Claude Desktop's project-folder feature for longer, broader agentic tasks. Create a Cowork project and choose Use an existing folder, pointing it at your Modoki project — Cowork reads that folder's CLAUDE.md automatically before it starts work, the same file Modoki already scaffolds, so there's nothing extra to write. The gap: Cowork can't reach the live editor. It only supports remote connectors brokered through your Claude account, not local MCP servers, so the modoki_* tools (scene state, mutation, screenshots) aren't available there — it can read and edit project files (game code, scene JSON, configs), but can't verify against the running editor the way Claude Code / the Code tab can.

Chat

Plain chat has no project folder — it never reads CLAUDE.md/AGENTS.md and can't edit files on disk. What it can do is talk to the same modoki MCP server the other tools use, for a chat-only way to inspect and drive a running editor:

1. Open the project in Modoki, then run AI → Connect Claude Code once — that writes a correct, machine-specific .mcp.json into the project (editor port, and on some setups a token), which you'll copy from.
2. Open Claude Desktop's config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Copy the mcpServers.modoki entry from the project's .mcp.json into Claude Desktop's config, under its own mcpServers key (this is a global file — every project you connect this way shares it, so the last one you copied wins).
4. Restart Claude Desktop. It picks up the modoki_* tools; the Modoki editor must stay open and running for the connection to work.

Global, not per-project

Unlike .mcp.json in a project folder, claude_desktop_config.json is one file for your whole machine. Re-copying the block from a different project's .mcp.json repoints Chat at that project's editor instead.

If you edit the instructions yourself

AGENTS.md is generated from CLAUDE.md — don't hand-edit AGENTS.md, since the next regeneration would overwrite your change. Edit CLAUDE.md instead.