Godex CLI

 ..|'''.|               '||
.|'     '    ...      .. ||    ....  ... ...
||    .... .|  '|.  .'  '||  .|...||  '|..'
'|.    ||  ||   ||  |.   ||  ||        .|.
 ''|...'|   '|..|'  '|..'||.  '|...' .|  ||.

Godex integrates the OpenAI Codex CLI into the Godot Script Editor for fast inline GDScript snippets and small fixes. Godex is not built for vibe coding whole projects. For larger context work, use Codex CLI next to your project. Godex is meant for the moments where you are already typing in Godot and want a small snippet or focused block fix without changing tools.

Features

• INSERT: generate code where you write a #I ... /# prompt line.
• FIX: rewrite a marked code block with #F and /#.
• Prompt-line progress: reasoning, tool use, and loading status stay on the marker line.
• Editor output metrics: final summary, token counts, elapsed time, and throughput are printed after each run.
• Read-only Codex boundary: Codex is launched with a read-only sandbox and returns structured code; Godex applies the result inside the editor.
• Reasoning escalation: Codex can ask Godex to rerun a request at medium, high, or xhigh reasoning when the current effort is too low.
• Optional Codex Fast tier: pass Codex's higher-credit fast service tier for supported signed-in CLI models.
• Compact nearby context: Godex sends a small local code window and lets Codex inspect files when broader context is actually needed.
• Cross-platform launch path: uses an installed codex executable on Windows, Linux, and macOS.

Requirements

• Godot 4.7+
• OpenAI Codex CLI installed and authenticated
• codex available from the environment Godot runs in, or configured in Editor Settings

Official docs:

• Codex CLI: https://developers.openai.com/codex/cli
• Codex non-interactive mode: https://developers.openai.com/codex/noninteractive
• Godot command line and class docs: https://docs.godotengine.org/

Install

Copy this folder into your Godot project:

res://addons/godex-cli/

Enable it in Project -> Project Settings -> Plugins.

Configure Codex CLI

Install and authenticate Codex CLI using OpenAI's official instructions, then verify:

codex --version

If Godot cannot find codex, set:

Editor Settings -> GodexCLI/codex_executable

Use codex when it is on PATH, or an absolute executable path when your OS/editor launch environment needs it.

On Linux, desktop-launched Godot may not inherit the same PATH as your terminal. Godex checks common Codex locations such as ~/.local/bin/codex, but setting the absolute path is the most reliable fallback.

On Unix-like platforms, Godex redirects Codex stdin from /dev/null so codex exec does not wait for extra piped input from Godot's process pipe.

Configure Godex

Behavior prompts live in:

res://addons/godex-cli/context/

Godex loads the shared behavior file plus the mode-specific behavior file for each request:

• base.md
• gdscript_guardrails.md
• insert.md
• fix.md

Project settings:

• GodexCLI/use_git: disable --skip-git-repo-check when true.
• GodexCLI/use_ephemeral: run Codex without persisted session files.
• GodexCLI/use_output_schema: pass mode-specific JSON schemas to Codex.
• GodexCLI/fast_mode: skip Codex user config and rule files for lower startup cost. Enabled by default.
• GodexCLI/use_codex_fast_tier: request Codex's higher-credit fast service tier with service_tier="fast" and features.fast_mode=true. Enabled by default.
• GodexCLI/auto_model_routing: choose fast/deep profile from request shape.
• GodexCLI/web_search_mode: web search mode for non-minimal runs: cached, live, or disabled. Defaults to cached.
• GodexCLI/fast_model and GodexCLI/deep_model: model dropdowns. Use codex-default to let Codex choose its configured/default model.
• GodexCLI/fast_reasoning_effort and GodexCLI/deep_reasoning_effort: starting reasoning settings. The default fast profile starts at low, the lowest effort supported by the current Codex GPT models.
• GodexCLI/request_timeout_sec: kill a stuck request after this many seconds.

Model dropdown options currently include codex-default, gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, gpt-5.3-codex, and gpt-5.2. Spark availability depends on your Codex CLI/account access. gpt-5.3-codex and gpt-5.2 remain available as legacy dropdown options for existing workflows, but OpenAI's Codex docs mark them deprecated for ChatGPT sign-in.

Codex may return an escalation request instead of code when the current reasoning effort is not enough. Godex validates the requested target and reruns the same request with the deep profile, using GodexCLI/deep_model plus the higher model_reasoning_effort. Supported escalation targets are medium, high, and xhigh.

Manual reasoning markers can force the deep model for one request:

• /#: use normal fast/deep routing.
• /1#: use the deep model with low effort.
• /2#: use the deep model with medium effort.
• /3#: use the deep model with high effort.
• /4#: use the deep model with xhigh effort.

For INSERT, put the marker at the end of the prompt line, such as #I write a helper /2#. For FIX, put it on the closing line, such as /3#.

Fast mode passes --ignore-user-config and --ignore-rules to codex exec. Auth still uses CODEX_HOME, and Godex still passes its explicit sandbox, reasoning, JSONL, and schema settings. Disable fast mode if your Godex requests depend on Codex user config or rule files.

Codex Fast tier is separate from GodexCLI/fast_mode. It may consume credits at a higher rate and only applies where the installed Codex CLI/account/model supports it. Godex sends it as per-run config overrides for codex-default, gpt-5.5, and gpt-5.4, so it still works when GodexCLI/fast_mode skips the user config file. Disable GodexCLI/use_codex_fast_tier to use the standard tier.

Godex disables image generation for inline editor runs. Web search stays configurable: low and higher efforts use GodexCLI/web_search_mode, but Godex forces web search off for minimal attempts because Codex rejects the web search tool at that reasoning effort. If minimal is configured for a GPT-5/Codex model, Godex automatically sends low instead.

Usage

INSERT

Write an INSERT marker where the generated code should appear:

#I create a typed helper that clamps health /#

Godex replaces that prompt line with the returned code.

FIX

Wrap the block you want rewritten:

#F make this typed and safer
func _process(delta):
    position += velocity * delta
    if position.x > max_x:
        position.x = max_x
/#

#F also works without a prompt. In that case, Godex fixes obvious bugs, typing, and readability issues while preserving behavior.

The result is applied directly as one editor operation, so undo should restore the previous block.

Output Behavior

• Live progress updates the prompt line.
• Escalation reruns update the same prompt line with the new reasoning effort.
• The editor output does not receive reasoning/progress spam.
• Godex applies the result as soon as Codex has produced the final message and turn.completed usage, without waiting for the CLI process to fully exit.
• After completion, the editor output prints:
  • short summary
  • cached input tokens
  • input tokens
  • output tokens
  • reasoning output tokens
  • elapsed time
  • output tokens per second and total tokens per second

When a request escalates, the final metrics aggregate token usage and elapsed time across all attempts.

Troubleshooting

Nothing happens

• Make sure the marker ends with /#.
• Make sure the plugin is enabled.
• Check whether another Godex request is already running.

Codex fails to start

• Run codex --version from the same environment if possible.
• Set Editor Settings -> GodexCLI/codex_executable to an absolute path.
• On Linux this is often ~/.local/bin/codex.
• Make sure Codex CLI is authenticated.

Codex returns invalid output

• Keep GodexCLI/use_output_schema enabled.
• Check the context files for conflicting instructions.
• Run Codex directly in a terminal to confirm the installed CLI version still supports the documented flags.

Project Structure

addons/godex-cli/
├── context/
│   ├── base.md
│   ├── gdscript_guardrails.md
│   ├── fix.md
│   ├── fix_schema.json
│   ├── insert.md
│   └── insert_schema.json
├── godex-cli-main.gd
├── godex-cli-main.gd.uid
└── plugin.cfg

Credits

Created by Ben Heirbaut.

License

MIT