Codex Gearshift

A creator-first Godot navigator that turns plain-language tasks into the safest next move, likely blockers, verification checks, and a reusable Codex prompt.

Comment

Inspiration

AI coding tools can generate code quickly, but beginner game creators often get stuck one step earlier: they do not know what kind of problem they are describing.

They may say:

  • “The button does nothing.”
  • “It happens twice.”
  • “The character sometimes passes through walls.”
  • “My coins disappear after changing scenes.”

Those descriptions are meaningful, but they do not directly name Godot concepts such as signal connections, collision masks, scene state, save compatibility, or UI containers.

Codex Gearshift began as a model-routing experiment. During development, we realized that asking creators to choose a model and reasoning level was exposing the machinery instead of solving their problem. We shifted the product into a creator-first navigator that hides the internal routing decision and shows the safest next action.

What it does

Codex Gearshift turns a plain-language Godot 4.x task into:

  • one of three production guidance levels;
  • an explainable game-specific risk profile;
  • up to three relevant Godot blockers;
  • the first action to take;
  • likely pitfalls;
  • verification steps;
  • stop conditions; and
  • a reusable, safety-bounded prompt for Codex.

The three guidance levels are:

  1. Proceed directly for a small and isolated change.
  2. Proceed with checks for a concrete Godot integration risk.
  3. Create a restore point and proceed carefully when shared state, save compatibility, or multi-step behavior could be damaged.

Task analysis runs entirely in the browser. It requires no API key, account, backend, database, or external network request.

How it works

The application uses a deterministic and explainable analysis pipeline:

  1. The task is matched against Godot-related categories and risk signals.
  2. A beginner-language layer translates phrases such as “it happens twice” or “the old data will not open” into creator signals.
  3. The Analyzer determines implementation, game-state, save-compatibility, and regression risks.
  4. The Blocker Guide ranks relevant Godot failure modes and prevents one blocker family from dominating all results.
  5. The interface presents the recommended action, verification plan, stop conditions, and safe Codex prompt.

The Build Week version contains 31 reproducible fixtures, 16 Godot-specific blockers, and 96 automated tests.

How we built it

Codex Gearshift was built with Vite, TypeScript, HTML, and CSS. Vitest provides deterministic regression coverage, while browser checks verify desktop, mobile, copy interaction, and console behavior.

The application is deployed as a static site through GitHub Actions and GitHub Pages.

The production architecture is intentionally small:

  • no backend;
  • no database;
  • no authentication;
  • no runtime AI API;
  • no automatic code editing; and
  • no hidden probabilistic classifier.

This keeps every recommendation reproducible and inspectable.

How Codex was used

Codex accelerated:

  • repository and application scaffolding;
  • the deterministic Analyzer;
  • the Godot Blocker Guide;
  • beginner-language signal implementation;
  • fixture and regression-test creation;
  • responsive UI work;
  • browser smoke testing;
  • GitHub Pages preparation; and
  • reproducible submission documentation.

Codex also ran test, type-check, build, browser, responsive-layout, asset-path, and console validation throughout the project.

How GPT-5.6 Thinking was used

GPT-5.6 Thinking was used for product direction and design review, including:

  • changing the product from a model router into a creator-first navigator;
  • defining beginners and non-engineers as the primary audience;
  • designing Godot-specific risks and stop conditions;
  • reviewing real beginner-language evaluation inputs;
  • identifying over-cautious and under-cautious recommendations;
  • defining the Beginner Language Calibration milestone; and
  • deciding when to freeze features and move into submission mode.

GPT-5.6 was not integrated into the runtime application or called through an API. The live application remains deterministic and local-first.

Challenges

Translating beginner language without building a keyword pile

The hardest problem was connecting natural phrases to technical Godot risks without scattering one-off keywords throughout the codebase. We introduced centralized beginner-language signals with phrase groups, exclusions, risk effects, preferred blockers, and human-readable reasons.

Avoiding both over-warning and under-warning

A display-only label change should not receive the same guidance as a save migration or shared-state change. We calibrated the rules so that isolated presentation changes move faster, while state loss and unreadable save data trigger a restore-point recommendation.

Keeping explanations useful

A technically correct classification is not enough. Each result needed to tell the creator what to inspect first, what commonly goes wrong, how to verify the change, and when to stop.

Preserving deterministic behavior during English UI preparation

The submission UI was translated to English without changing the frozen Analyzer, beginner signals, blocker scoring, or fixture expectations.

Accomplishments

We are proud that the final application:

  • converts vague creator language into actionable Godot guidance;
  • demonstrates three visibly different levels of caution;
  • provides explainable blocker rankings rather than a black-box answer;
  • generates a reusable Codex prompt with explicit safety boundaries;
  • runs without credentials or a backend;
  • works on desktop and a 390px mobile viewport;
  • passes 96 automated tests; and
  • is available as a public, immediately testable web demo.

What we learned

The most important lesson was that model selection should often remain below the surface.

Creators do not necessarily want to choose a model, reasoning level, or agent configuration. They want to know what they should do next, what might break, and how to verify the result.

We also learned that beginner language is not low-quality input. Phrases such as “it happens twice” or “the coins disappeared” contain valuable signals when the product is designed to listen for them.

Finally, deterministic rules were a strength for this MVP. They made every recommendation reproducible, reviewable, and easy to regression-test.

What’s next

Future work may include:

  • broader beginner-language coverage based on real creator feedback;
  • more Godot-specific blocker families;
  • outcome tracking to compare recommendations with actual results;
  • optional project-context import;
  • an experimental Godot Editor integration; and
  • community-contributed fixtures with reproducible expected behavior.

The core principle will remain the same: show creators the safest useful next action while keeping the internal machinery explainable.

Built With

Share this project:

Updates