codexbridge for Unity

codexbridge brings Codex into the Unity Editor through your local codex app-server. You get an in-editor chat workflow, Unity-aware tools, image attachments, local project context, resumable saved chats, and chat export without building a separate backend.

This package is designed for teams who want Codex inside Unity, but want the runtime to stay close to the project: local CLI auth, local project files, local Unity state.

Why codexbridge

• In-editor Codex chat window for Unity 6+
• Uses your local Codex CLI login flow
• Unity-aware tools instead of generic shell-first behavior
• Context presets for selection, scene, file tree, packages, settings, git history, and console
• Assistant modes for building, inspection, debugging, and refactoring
• Attach images from disk or paste them from the clipboard into the prompt
• Local chat history saved per project
• Reopen saved chats and continue them on the original Codex thread
• One-click export to Markdown, plain text, or JSON
• Optional web search, skills, and Meta XR tool exposure

Good Fits

• Scene setup and iteration
• Script scaffolding and targeted refactors
• Gameplay prototyping
• Inspector and hierarchy explanation
• Package inspection
• Unity console triage
• Asset and prefab workflows

Requirements

• Unity 6000.0+
• Codex CLI installed locally
• ChatGPT/Codex login available through the local CLI

Install Codex CLI:

npm install -g @openai/codex
codex --version

The package starts codex app-server for you. No manual server boot required.

Install

Unity Package Manager

1. Download or clone this package.
2. In Unity open Window -> Package Manager.
3. Click +.
4. Choose Add package from disk....
5. Select this package's package.json.

Open The Window

Menu: Tools -> codexbridge

Shortcut: Cmd/Ctrl + G

First-Time Setup

1. Open Tools -> codexbridge.
2. Click Connect.
3. If required, click Login.
4. Complete the ChatGPT login flow in your browser.
5. Return to Unity and start chatting.

What Codex Can Do In Unity

codexbridge exposes Unity-native dynamic tools so Codex can work with project state directly.

It now exposes two layers:

• existing low-level unity_* tools for stable editor-native operations

• semantic underscore tools such as unity_get_editor_context, scene_*, prefab_*, asset_*, render_*, shadergraph_*, vfxgraph_*, physics_*, animation_*, ui_*, audio_*, build_*, tests_*, and diagnostics_*

• Read and write project text files in Unity-relevant areas

• Create scripts when code is actually needed

• Inspect selection and active scene hierarchy

• Search project assets and scene objects

• Open and save scenes

• Instantiate prefabs

• Create prefabs from a hierarchy path or the current selection

• Create materials and GameObjects

• Add components

• Duplicate, delete, and transform objects

• Inspect packages and package files

• Inspect active build configuration and mutate common build flags

• Build the project and summarize build output

• Discover and run Unity tests

• Inspect importer settings and asset dependency graphs

• Inspect and edit Addressables when the package is installed

• Use semantic editor-context, selection, scene, prefab, asset, render, physics, animation, UI, audio, build, and diagnostics tool families

• Use serialized-asset workflows for Shader Graph, VFX Graph, Timeline, Cinemachine, AudioMixer, and related advanced Unity assets

• Inspect Input System assets, localization assets, animator controllers, render-pipeline state, and scene UI

• Inspect audio mixer groups, snapshots, and exposed parameter hints

• Read recent Unity console logs

• Discover Meta XR packages, assets, and types

• Validate Meta XR project setup, Quest build readiness, rigs, interaction setup, scene stack, passthrough, and spatial anchors

• Inspect Meta XR Building Blocks and simulator package state

• Check Meta XR scene setup and open Building Blocks

• Enable Meta XR passthrough on an OVRCameraRig without generating a bootstrap script

Composer Features

• Attach image files directly from disk
• Paste image file paths or clipboard images into the composer
• Show attached image chips before sending
• Choose reasoning effort for supported GPT-5 / Codex and Claude models
• Collapse tool-call payloads by default and expand them only when you want the details
• Surface waiting / compacting thread status instead of only showing a generic thinking state
• Surface approval / user-input requests inside the window so the active turn can continue without losing plan state
• Restore saved model, context mode, and assistant mode when reopening a saved chat
• Restore pinned provider, active skill, persistent tool profiles, and recovery state when reopening a saved chat

Prompt Context Modes

The composer can attach extra Unity context before each turn.

• None
• Selection
• Active Scene
• File Tree
• Project Settings
• Git History
• Packages
• Console
• Build Configuration
• Addressables
• Input Actions
• Test Results
• Meta XR Diagnostics

Assistant Modes

• Builder: make concrete project changes
• Inspector: analyze first, explain before editing
• Debugger: prioritize root cause and console state
• Refactor: improve existing implementation carefully

Chat History And Export

codexbridge now saves chat transcripts locally per project in:

UserSettings/CodexBridge/Chats

What you get:

• automatic local chat history
• reopen recent chats from the toolbar menu
• continue a reopened chat on its original Codex thread when the thread id is available
• export current chat as Markdown, Text, or JSON
• history retention control from Preferences

This keeps transcripts out of source-controlled package folders by default.

Preferences

Open Edit -> Preferences -> codexbridge.

Key settings:

• Codex executable path
• app-server args
• auto-start server
• preferred model
• preferred reasoning effort
• prefer Unity dynamic tools
• enable web search
• enable skills
• inject skill catalog
• enable Meta XR tools
• auto-approve or auto-decline Codex approvals
• save chat history
• max saved chats

Safety Model

• Codex is instructed to prefer Unity-native tools over generic shell workflows
• Codex is instructed to prefer existing components, prefabs, SDK assets, and editor workflows before creating new scripts
• Package-owned and vendor SDK script roots are blocked for writes; Codex must create project-side scripts under Assets/ instead
• Web search can be toggled on or off
• Meta XR helpers are opt-in
• Local history is project-scoped
• Approval behavior is configurable in Preferences

Known Limitations

• IMGUI UI; intentionally lightweight
• Tool surface still focused on editor workflows, not full runtime automation
• Context compaction state is surfaced in the UI, and the bridge now fails fast on transport stalls instead of staying stuck on thinking forever
• Meta XR coverage is improved, but the package still benefits from more native helpers for common no-code editor workflows

Roadmap

• richer Unity tool coverage
• deeper native implementations behind the new semantic dotted-tool surface
• scene and prefab diff workflows
• deeper Meta XR validation and interaction inspection
• play mode and runtime diagnostics
• deterministic skill support for Unity-specialized workflows

Skill research + roadmap:

Documentation~/AgentSkillsRoadmap.md

Troubleshooting

If connection fails:

• confirm codex --version works in a terminal
• set an explicit Codex executable in Preferences if PATH lookup fails
• verify your local Codex login is valid

If streaming stalls:

• confirm codex app-server can run locally
• check the codexbridge logs panel
• codexbridge now clears stalled turns locally and surfaces Connection stalled / Connection lost so you can reconnect instead of force-closing Unity

If Codex pauses after showing a plan:

• look for the Action Required panel in the window
• approve file changes / command execution there, or submit a JSON response for user-input requests
• the same turn continues after you answer, so the visible plan stays in context

On Windows:

• codexbridge wraps codex.cmd through cmd.exe for redirected stdio stability
• if PATH lookup is flaky, set the Codex executable explicitly in Preferences
• file/package reads are capped for bridge stability; if a read is truncated, narrow the target path or use the search tools first

License

Clean-room Unity editor integration inspired by modern AI-in-editor workflows.