Create a local game project, generate Codex-ready role prompts, hand focused work to a studio role, then validate the project artifacts before you trust them. The state lives in your repository under .codex/; generated games live under projects/<slug>/; normal execution goes through codex exec.

./codex-game-studio init --name "Signal Cartographer" --engine godot --mode prototype --non-interactive \
  --concept "A compact puzzle game about routing trains through haunted switchyards"

./codex-game-studio run producer --project projects/signal-cartographer \
  "Create the initial market overview."

./codex-game-studio validate --project projects/signal-cartographer

Why developers use it

Codex Game Studio gives game teams a repeatable way to work with Codex across design, production, engineering, art, QA, and release tasks.

Local-first project state. No hosted planner, hidden queue, or opaque database.
Codex-native instructions in generated AGENTS.md and .codex/prompts/<role>.md files.
Role-specific context packets instead of dumping every template into every task.
Hard-failing validation for generated prompts, workflows, package assets, and project contracts.
Inspection paths with --dry-run and --print-prompt before Codex touches the workspace.
Engine scaffolding for Godot, Unity, and Unreal projects.

This is not a game engine and it is not a replacement for human creative direction. It is a workflow layer: a small, inspectable CLI that turns studio roles and production documents into bounded Codex work.

The studio loop

flowchart LR
  A[init project] --> B[projects/slug]
  B --> C[.codex studio state]
  C --> D[generated role prompts]
  D --> E[run role with Codex]
  E --> F[review, fix, verify]
  F --> G[validate project]
  G --> D

A generated project contains the working contract Codex needs: project summary, engine context, role prompts, workflow prompts, starter production docs, and validation metadata. Role runs prepare a bounded prompt packet under .codex/runs/ and invoke codex exec from the project root.

Requirements

Node.js 24 or newer.
Codex CLI available on PATH for normal run <role> execution and full validation.

Use from source checkout

Codex Game Studio uses the normal source-checkout path: clone the repo, install dependencies, build TypeScript, then run the local CLI wrapper. The repository does not commit generated bundled CLI artifacts.

git clone git@github.com:merlinhu1/codex-game-studio.git
cd codex-game-studio
npm install
npm run build
./codex-game-studio --help
./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive

For package use after publishing, installing, or linking the package:

npm exec codex-game-studio -- --help
npm exec codex-game-studio -- templates list

For contributor development on Codex Game Studio itself, use npm scripts. They install developer dependencies, rebuild TypeScript output, and run validation:

npm install
npm run build
npm run typecheck
npm test
npm run validate

Quick start

1. Create a project

./codex-game-studio init --name "My Game" --engine godot --mode prototype --non-interactive \
  --concept "A compact puzzle game about routing trains"

Codex Game Studio creates projects/my-game/ with engine markers, starter docs, .codex/studio.json, generated role prompts, generated workflow prompts, and a project-level AGENTS.md.

2. Inspect the project

./codex-game-studio status --project projects/my-game
./codex-game-studio resume --project projects/my-game

status and resume are read-only. freeze is the explicit command that changes project status.

3. Choose a template or workflow

./codex-game-studio templates list
./codex-game-studio templates show gdd
./codex-game-studio market --project projects/my-game
./codex-game-studio ship-check --project projects/my-game

Workflow shortcuts render prompts only. They do not launch Codex.

4. Run a studio role through Codex

./codex-game-studio run producer --project projects/my-game \
  "Create the initial market overview."

Want to see exactly what Codex will receive first?

./codex-game-studio run producer --project projects/my-game \
  "Create the initial market overview." --dry-run

./codex-game-studio run producer --project projects/my-game \
  "Create the initial market overview." --print-prompt

run <role> inlines the generated project role prompt from .codex/prompts/<role>.md and only the package templates selected for that role and task. --allow-broad-context adds bounded discovery for existing project artifacts such as the GDD, production timeline, market overview, AGENTS.md, and .codex/studio.json; it does not recursively load the whole project.

5. Validate before relying on output

./codex-game-studio validate
./codex-game-studio validate --project projects/my-game

Validation exits nonzero on failure. It checks package contracts, template availability, forbidden future surfaces, build output, project state, generated-surface freshness metadata, rendered-body hashes, and stale or tampered generated prompt/workflow files.

Commands

Command	What it does
`init` / `new`	Create a project under `projects/<slug>/`.
`status`	Print project phase, status, engine, and the next validation command.
`resume`	Print a read-only continuation summary.
`refresh-context`	Regenerate `.codex/context-manifest.json` and its freshness metadata after selected context files change.
`freeze`	Mark a project as frozen.
`validate`	Run hard-failing repository or project validation.
`templates list`	List packaged template IDs.
`templates show <template-id>`	Print a packaged template.
`run <role>`	Prepare one bounded Codex prompt packet and invoke `codex exec` by default.
`task create` / `task run` / `task orchestrate`	Manage file-backed `.codex/tasks.json` tasks and run explicit local bounded orchestration.
`market`, `analytics`, `design-spec`, `feel-review`, `art-direction`, `ui-review`, `milestone`, `handoff`	Render focused workflow prompts.
`review`, `ship-check`	Render baseline review and release-check prompts.
`workflow create-tasks <workflow-id>`	Create explicit file-backed tasks from supported workflow recipes such as `vertical-slice`, `bugfix`, `ui-ux-review`, and `release-checklist`.

Studio roles

Codex Game Studio ships a Codex-native role roster with hyphenated IDs:

Area	Roles
Direction and production	`studio-orchestrator`, `producer`, `release-manager`
Market and analytics	`market-analyst`, `data-scientist`
Design and writing	`creative-director`, `senior-game-designer`, `game-designer`, `narrative-designer`, `game-feel-designer`
Engineering	`gameplay-programmer`, `engine-programmer`, `tools-programmer`
Art and interface	`senior-game-artist`, `technical-artist`, `ui-ux-designer`
Quality	`qa-playtester`

Legacy underscore role IDs are intentionally rejected. narrative-designer is a first-class story and content owner.

What gets generated

Repository assets:

src/: TypeScript CLI implementation.
src/roles.ts: Codex role packages compiled into the CLI.
templates/: reusable design, production, art, QA, release, analytics, and engine templates.
engine_configs/: engine overlays for Godot, Unity, and Unreal.
docs/: migration, validation, truth, and compatibility notes.
tests/: Vitest coverage for project workflow, templates, agents, runner prompts, validation, and engine behavior.

Project artifacts:

projects/<slug>/: generated project root.
AGENTS.md: primary generated Codex project instructions, owned by src/agents.ts.
.codex/studio.json: project metadata, role roster, workflow IDs, and workflow state.
.codex/prompts/: generated role prompts.
.codex/workflows/: generated workflow prompts.
.codex/runs/: prepared prompt packets, per-task orchestration output, and run metadata from non-dry role or orchestration runs.
.codex/locks/: transient file-backed locks for bounded parallel task orchestration.
.codex/tasks.json: file-backed task state when you use task create, task run, workflow task recipes, or task orchestrate.
documentation/: starter game-design and production documents.
source/project-<slug>/: engine project location contract.

Generated role prompts and workflow files carry deterministic freshness metadata and rendered-body hashes. New project validation compares those files against the current renderer and flags stale, malformed, or manually tampered surfaces.

Current boundaries

Codex Game Studio is intentionally narrow right now.

Implemented:

deterministic project scaffolding;
generated Codex role and workflow surfaces;
direct codex exec role execution;
dry-run and prompt-print inspection;
file-backed tasks;
explicit local task orchestration with bounded --max-concurrency and file-backed locks;
workflow task recipes for selected high-value workflows;
curated CCGS adaptation registry for role/skill/workflow translation decisions;
bounded review, verification, and fix-pass options;
hard-failing repository and project validation.

Future-only, not exposed as working features:

planner/next;
telemetry;
changed-file tracking;
hosted/background orchestration;
unbounded parallelism;
hard output-ownership enforcement;
legacy .gamestudio compatibility;
generated CODEX.md or project_orchestrator.md surfaces.

Explicit local task orchestration is now inside the product boundary, but user-facing runtime claims require implementation, tests, and docs.

See docs/known-upstream-differences.md and docs/migration-from-claude.md for the detailed migration contract.

Development

npm run build
npm run typecheck
npm run test
npm run validate

The project uses ESM TypeScript with module and moduleResolution set to NodeNext. Relative TypeScript imports include the emitted .js specifier.

Before opening changes, run the checks in CONTRIBUTING.md. Functional behavior changes should keep README claims, validation behavior, tests, and Truthmark-backed docs in sync.

License

Codex Game Studio is released under the MIT License. See LICENSE.