Codex Git

Codex Git is a planned local Git surface for Codex Desktop. This repository contains the initial application scaffold and Host Adapter boundary; Worktree discovery, Git commands, packaging, and other product features are not implemented.

Product and architecture

• Domain language
• macOS MVP product requirements
• MVP technical architecture
• Codex Host Adapter compatibility and trust boundary
• Architecture decisions:
  • Isolate Codex host integration behind a Host Adapter
  • Use the system Git CLI behind a local Repository Engine

Requirements

• macOS
• Node.js 22.12 or newer
• npm 11

Commands

npm ci
npm run dev

The launcher attaches the placeholder Git Surface through the standalone Host Adapter and prints its URL plus the loopback health URL. The surface uses port 5173 by default, and CODEX_GIT_SURFACE_PORT overrides that listener port. The protocol server always uses an operating-system-assigned loopback port.

The server scaffold can also be started separately:

npm run dev:server

Verification commands:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

Workspace layout

apps/launcher                  Standalone runtime composition root
apps/server                    Loopback server scaffold
apps/ui                        Standalone React placeholder surface
packages/protocol              Shared protocol types
packages/repository-engine     Repository session boundary only
packages/host-adapter          Host Adapter boundary
packages/host-adapter/*        Codex CDP/DOM and standalone Host Adapters
tests/                         Contract, integration, end-to-end, and fixture layers

codex-git