System purpose
VibeGame is a game development framework in which an agent team develops and accepts the game. Users provide requirements, and team members work within their roles.
| Component | Purpose |
|---|---|
| Claude Code and Codex | Run development agents |
| Python CLI | Initialize projects and manage the development environment |
| Phaser 3 | Run web games |
The main output is a game project directory containing:
project.json.Scene and object JSON.
JavaScript.
Asset manifests.
Work records.
It suits 2D web game prototypes and projects that need ongoing changes to gameplay and assets.
Requirements and coordination
- User
- orchestrator
- designer
- PRD and GDD
Task execution
- architect
- programmer
- auditor
- artist
Runtime and acceptance
- Phaser engine
- player
- reviewer
- State and screenshot evidence
Static checks, actual play, and final review are separate steps.
These capabilities remain unfinished roadmap items in the README:
Godot.
Unity.
End-to-end 3D production.
The instructions here cover the current public Phaser implementation.
Installation and checks
- Not completed:
Python 3.12 or later.
- Not completed:
uvandtmuxinstalled. - Not completed:
Claude Code or Codex installed, signed in, and usable.
- Not completed:
Each selected role's CLI and model available to the current account.
- Not completed:
Image generation and VLM APIs configured for the complete art and visual verification workflow.
The standard installation needs neither Node.js nor npm. Keep the source checkout: installation uses editable mode, and the CLI reads these resources from that directory:
Engine.
Templates.
Dashboard.
git clone https://github.com/tettethu/VibeGame
cd VibeGame
./setup.shCreate a game directory beside the source checkout, then start the team:
cd ..
mkdir my-game
cd my-game
vibegame init
vibegame startBy default, init initializes or uses Git and creates a framework baseline commit. If the directory already contains work, use vibegame init --no-commit to inspect the changes, then create the baseline needed for worktrees yourself.
Codex hooks
If any role uses Codex, run this after installation:
vibegame setup codex-hooksThen open Codex, enter /hooks, and trust the added VibeGame hooks. The command writes to the user's ~/.codex/hooks.json. Without both installation and trust, agents may fail to register in the Dashboard and startup may keep waiting.
Before the first managed Claude Code session in skip-permissions mode, complete the consent screen in a normal terminal as the README instructs. Review the permission limits below; do not treat a managed session as an isolated environment.
Provider and role configuration
| Location | Purpose | Operating limit |
|---|---|---|
src/.vibegame/settings.json | Role CLIs, models, and optional effort for new projects | Preserve hooks when changing agents |
src/.vibegame/team/models.json | CLI model lists, argument mappings, and permission defaults | Names must match both the framework list and the actual provider |
src/.vibegame/defaults.json | Default language for new projects | The reviewed revision defaults to en |
.env at the checkout root | Image, VLM, and optional third-party services | Keep it out of Git and frontend code |
The game's .vibegame/settings.json | Role configuration for an initialized project | Check it separately from the source template |
The supplied role settings mix Claude Code and Codex. If you install only one tool, first move roles that require a CLI to an available harness and model instead of retaining every default.
| Service | Required settings | Optional settings |
|---|---|---|
| Image generation | IMAGE_PROVIDER, IMAGE_API_KEY, IMAGE_MODEL | IMAGE_BASE_URL |
| VLM | VLM_BASE_URL, VLM_API_KEY, VLM_MODEL | None |
The VLM base URL ends at /v1 and does not include /chat/completions.
VLM has no built-in default model ID. Confirm the model name and visual-input capabilities with the provider before filling it in. An API-compatible format alone does not establish that a model can check game screenshots.
Core capabilities
Initialization
vibegame init
Create a game project
Copy the framework, roles, and engine, and create scene, input, and asset directories. Includes a Git commit by default.
Team startup
vibegame start
Dashboard and agent session
Start the coordination and collaboration environment. Use --project to specify the game directory alongside an initial message.
Goal execution
/vibegame-build
End-to-end game production
Submit the game goal in the agent conversation. This is a skill command, not a program to run directly in the shell.
Static checks
vibegame check
Validate project data
Check project, scene, asset, script, and input settings. Passing does not mean the actual gameplay has been accepted.
Runtime and inspection
vibegame run --port auto
A controllable game runtime
Start the game server and controlled browser, then query state and capture screenshots through the play interface.
Runtime shutdown
vibegame close
Close a game runtime
Close tracked runtimes. The Dashboard and agent team are separate processes.
When continuing from another directory, pass the project path to start with --project. Its positional argument is a message for the orchestrator:
vibegame start --project ./my-game "Continue polishing the boss fight"The Dashboard has these tabs:
Chat.
Assets.
Objects.
Play.
The static Play preview differs from the controlled runtime started by run. Use the latter for state inspection or repeatable input tests.
The source skills directory contains these workflows, separate from shell CLI subcommands:
| Skill | Purpose | Startup boundary |
|---|---|---|
vibegame-start | Inspect the team and load working context | For an already-started team |
vibegame-build | Plan, execute, and accept a game goal | Confirm the goal and task plan through its workflow |
vibegame-edit | Change an existing game's style, genre, or rules | Establish a baseline before entering the build workflow |
self-evolve | Promote reusable project resources | User explicitly requests it and approves candidates |
artist-self-evolve | Distill reusable art production methods | Dispatched by the lead; does not start itself in the background |
Agent roles and task handoff
| Role | Main responsibility | Deliverable or limit |
|---|---|---|
orchestrator | Clarify requirements, maintain PRDs, divide tasks, and accept results | Decide task boundaries and completion criteria |
designer | Game design and GDD | Does not implement code |
architect | Research code and specifications, then write the technical plan | Produce plan.md and task context |
programmer | Implement the plan | Check code before handoff |
auditor | Static review of code against specifications | Does not run the game; can make fixes allowed by the specifications |
player | Verify real input, behavior, and screenshots | Needs the ability to process visual information |
artist | Generate, process, and register art assets | Update the manifest after finishing assets |
reviewer | Functionality, visual, and playability checks after the goal is complete | Separate from a single task's auditor |
Roles start according to the task; they do not all need to run simultaneously each time. A typical handoff follows this order:
PRD.
Technical plan.
Implementation.
Static review.
Runtime verification.
Orchestrator acceptance.
Task data lives under .vibegame/tasks/<name>/, commonly in:
prd.md.plan.md.context.json.Append-only
log.md.
Record separate acceptance criteria for:
File validity.
Visual readability.
Conformance to interaction requirements.
The reviewer can reject delivery. Review requires real input and evidence; role names alone do not guarantee correctness.
Engine data and art assets
| Path | Contents | Editing guidance |
|---|---|---|
project.json | Canvas, physics, start scene, manifests, and input settings | Preserve the engine boot entry and required fields |
scenes/*.scene.json | Initial node tree | Declare visuals, colliders, scripts, and children |
entities/*.node.json | Reusable object definitions | Shared character or obstacle definitions |
scripts/*.js | Game behavior and ordinary JavaScript logic | Use a Node when lifecycle behavior is needed |
assets/**/manifest.json | Asset keys, files, and atlas frames | Include in project.json.manifests for loading |
config/input-map.json | Keyboard-to-game-action mappings | Separate input rules from implementation |
Decide character and collider dimensions in game-world units before adjusting art display scale. Set these data separately:
Image resolution.
Display size.
Collider dimensions.
Recheck collision after changing appearance. Use placeholder_image or placeholder_atlas to verify gameplay before replacing them with registered assets.
After image generation, check:
Cropping.
Pivot.
Atlas frames.
Animation.
The artist's standard sprite workflow is:
Generate one image containing all frames of a single action.
Remove the background.
Cut.
Concatenate.
Register the manifest.
This workflow does not require generating a video for every action. Asset packs specified by the user are inspected and processed before registration.
The engine's original index.html loads Phaser 3.80.1 through a CDN. Standard development has no frontend bundling step, but deployment and offline use still require checking that this external resource can load.
Operating rules
Accept the smallest gameplay loop first
Define one scene, its controls, failure, and restart conditions. Verify behavior with placeholder assets before arranging the art swap.
Separate static checks from play evidence
check validates project data. player verifies gameplay through real input, state, and screenshots. Neither replaces the other.
Control generation and testing costs
Normal project check does not call paid APIs. --api adds VLM and image generation smoke checks. Inspect local data before deciding whether to run paid tests.
Keep the source checkout
The CLI depends on the source directory. After updating it, check framework and engine versions within existing games as well.
Image generation sends prompts and images to external services. Some image-processing agent workflows also use VLM, including:
Background removal.
Cutting.
Normalization.
Before starting, set separate quotas and stopping conditions for:
CLI inference.
Image generation.
VLM evaluation.
Optional video generation.
Image generation records live in .vibegame/logs/imagegen.jsonl and include:
Full prompts.
Reference-image paths.
Models.
Output locations.
Errors.
When reporting a problem, provide the source version and necessary error messages. Remove private data before sharing logs.
Worked example
After starting the orchestrator in the earlier my-game project, submit this proposed acceptance specification. This review did not generate or play-test the example.
/vibegame-build Build a single-screen 2D dodge game. Use arrow keys to move, avoid falling hazards, and survive for 30 seconds to win. A hit ends the round. Add a visible timer, clear win and lose states, and a restart button. Use placeholder assets first. Verify movement, collisions, the timer, and restart before replacing art. Keep API keys out of runtime files.Divide the work into these tasks, each with observable outcomes:
Input and movement.
Hazards and collision.
Timing and end states.
Restart.
Asset replacement.
Do not use "the game is playable" as the only completion criterion.
After team delivery, run these commands in the game directory:
vibegame check
vibegame run --port autoSave the decisive state and screenshot evidence, then run vibegame close. Move to art replacement and regression checks after these checks pass:
Win/loss behavior.
Interface readability.
Restart state.
Limits and failure handling
| Symptom or limit | Check and correction |
|---|---|
| Codex starts, but the Dashboard is empty or waiting for a session | Complete vibegame setup codex-hooks and Codex's /hooks trust step |
| Only one CLI is installed and some roles fail to start | Check each role's cli and model; replace settings that require the other tool |
| An existing project has staged work | init rebuilds staging and commits by default; save the work first, then inspect manually with --no-commit |
| Updated runtime reports missing clock support | Save custom engine changes, then update the framework and engine within the game; updating only the CLI checkout is insufficient |
check passes, but gameplay or visuals remain broken | Add the player's runtime tests; Dashboard Play is not equivalent to controlled runtime verification |
| Image or visual tests fail | Check provider, base URL, model capabilities, credentials, and quota; check --api calls paid services |
| Moving to Godot, Unity, or 3D | These remain roadmap items in the current README; do not infer support from the Phaser manual |
When using Claude roles, start handles project trust settings in the user's ~/.claude.json. Global hooks, trust registration, and project settings are separate. Inspect changes to user-level files before adoption.
The package uses Apache-2.0. The README's commercial-deployment notice is an author request that explicitly:
Requires no approval.
Charges no license fee.
Does not change Apache-2.0 rights.
Check terms separately for:
Image models.
External services.
Assets used.
Next steps
Updating an existing game
After pulling updates in the VibeGame source checkout, run vibegame init --no-commit in the game directory. Inspect the diff before deciding whether to choose Replace entire engine. Replacing the whole engine removes game-local engine changes and requires separate confirmation.
Releasing a game
vibegame release --dry-run
vibegame releaseBy default, release creates or updates the local release branch without automatically pushing or deploying. If the game uses entities/, modules/, or other extra runtime directories, list them explicitly in project.json.releaseExtraRoots. Manifests still select assets.
Verify on the release branch:
Actual HTTP paths.
All scenes.
Dynamically created objects.
A game with a custom backend also needs that service deployed with the correct API address injected. The tool's local runtime does not provide a production model backend for the game.
Promoting shared resources
vibegame evolve copies completed, user-approved shared resources back to the installed CLI's source checkout. It can promote:
Skeletons.
Modules.
Contracts.
Inspect the copy plan with --dry-run first. If the destination exists, it stops without overwriting or merging; it also does not automatically:
Edit indexes.
Commit.
Push.
This manual reviews revision fc9cbbe1f82c217b6d1946c00f51d309e584d826, package version 0.1.0. Interfaces and limits follow official sources at this revision; see the reference links for individual sources.
This review did not run:
Paid image generation.
VLM calls.
Complete agent-led game production.