Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
79 lines (59 loc) · 1.78 KB

ARCHITECTURE.md

File metadata and controls

79 lines (59 loc) · 1.78 KB

Architecture

Components

The project has two main parts:

  1. Unity package

    • C# editor code that polls .codex-unity-bridge/command.json
    • Dispatches actions to command handlers
    • Writes .codex-unity-bridge/response-{id}.json

  2. Codex package and skill

    • Python CLI: codex-unity-bridge
    • Codex skill docs bundled with the Python package
    • Handles atomic writes, polling, formatting, cleanup, and skill installation

Repository Layout

package/
  Editor/
    CodexBridge.cs
    ProdFact.CodexBridge.asmdef
    Commands/
    Models/
  Tests/

skill/
  pyproject.toml
  src/codex_unity_bridge/
    cli.py
    skill/
      SKILL.md
      references/
  tests/

Request Flow

Codex -> codex-unity-bridge -> .codex-unity-bridge/command.json
Unity Editor -> ProdFact.CodexBridge -> .codex-unity-bridge/response-{id}.json
codex-unity-bridge -> formatted terminal output

Why File-Based

  • no port management
  • no firewall setup
  • easy per-project isolation
  • easy manual inspection when debugging
  • works cleanly alongside the original Claude bridge when both are installed

Unity Side

Key types:

  • ProdFact.CodexBridge.CodexBridge
  • ProdFact.CodexBridge.Commands.ICommand
  • ProdFact.CodexBridge.Models.CommandRequest
  • ProdFact.CodexBridge.Models.CommandResponse

The dispatcher keeps a command registry and only allows safe read-only commands during compilation or editor updates.

Python Side

The CLI is responsible for:

  • UUID generation
  • atomic file writes
  • exponential-backoff polling
  • response validation
  • cleanup of stale files
  • Codex skill installation into ~/.codex/skills/unity-bridge/

Testing

  • Python behavior is covered by skill/tests/test_cli.py
  • Unity command and model behavior is covered by package/Tests/Editor/