CodexChat is an open-source, local-first, macOS-native Codex client built with SwiftUI. It integrates with the local codex app-server runtime and is designed for safe, reviewable agent workflows against real project folders.

Core differentiators:

• Native SwiftUI macOS app (not a cross-platform web shell).
• Conversations are persisted as local Markdown files you own.
• Skills and Mods support workflow automation and deep UI customization.
• Safety controls are explicit and legible (approvals, diff review, guardrails).
• Contributor tooling is built in (CodexChatCLI) for reproducible diagnostics and smoke tests.

• Current direct-download release target: macOS 14+ on Apple Silicon (arm64)
• Requires a local codex CLI install with codex app-server available on PATH
• Runtime compatibility window:
  • Validated: codex 0.114.x
  • Grace: codex 0.113.x
  • Outside that window: CodexChat starts in degraded mode and surfaces compatibility warnings in Settings and Diagnostics
• Download the latest signed DMG from GitHub Releases
• For install help, bug-report guidance, and support channels, see SUPPORT.md

• Native SwiftUI macOS experience for the Codex runtime with a chat-first flow.
• Local Markdown memory: conversations and project context are stored on disk as editable .md files.
• Theme customization with tunable palette, surface, text, and accent colors.
• Mods and Mods Bar support UI/workflow customization and side helpers while chatting.
• Built-in terminal workspace with multi-shell support for command-first and agent-assisted execution.
• Skill workflows: install from skills.sh or create and save your own, then trigger with $ shortcuts.
• Native macOS actions (calendar, messages, desktop cleanup) with preview-first confirmations and safety controls.
• Project safety controls for sandbox mode, approval policy, network access, and web search.
• Chat archive persistence with searchable local metadata.
• Keychain-backed secret handling for API keys.
• Deterministic contributor workflows via CLI diagnostics and fixtures.

1. Download the latest DMG from GitHub Releases.
2. Install or update the local codex CLI so codex app-server is available on PATH.
3. Launch CodexChat and confirm the detected runtime support level in Settings or Diagnostics.

CodexChat uses the shared Codex homes that other Codex clients use:

• Active Codex home: CODEX_HOME from the environment when set, otherwise ~/.codex
• Active agents home: ~/.agents
• ~/CodexChat remains app-owned storage for projects, metadata, diagnostics, and project-scoped .agents/skills

On first launch after connecting to a signed-in runtime, CodexChat can offer a one-time import of existing Codex conversations. Imported history is copied into a separate local project named Imported from Codex; new CodexChat conversations remain app-owned and separate from the live Codex runtime store.

Legacy ~/CodexChat/global/codex-home and ~/CodexChat/global/agents-home directories are migration inputs only and can be archived from Settings after handoff completes.

If you prefer to build from source, use the contributor path below.

• apps/CodexChatHost: canonical GUI app target (com.codexchat.app) and release source.
• apps/CodexChatApp: shared app/runtime module (CodexChatShared) and CodexChatCLI.
• apps/RemoteControlRelay: outbound-only websocket relay scaffold for remote mobile control.
• apps/RemoteControlPWA: installable mobile/web companion UI scaffold.
• packages/*: modular Swift packages (Core, Infra, UI, CodexKit, Skills, Memory, Mods, Extensions).
• skills/first-party: tracked first-party skill templates (including personal-action playbooks for macOS workflows).
• tests/fixtures: shared fake runtime fixtures used by smoke/integration paths.

• macOS 14+
• Xcode 16+ (Swift tools 6.0)
• Node 22+
• Homebrew
• SwiftFormat, SwiftLint, gitleaks

bash scripts/bootstrap.sh

Run the canonical GUI:

open apps/CodexChatHost/CodexChatHost.xcodeproj

Use scheme CodexChatHost.

make quick

Runs metadata/parity checks, format check, lint, and fast tests. This is the only check we keep in hosted GitHub Actions.

make oss-smoke

Runs deterministic contributor smoke checks using CodexChatCLI.

make reliability-local

Runs deterministic runtime/data reliability suites (recovery, mapping, approvals, durability). Also includes a ledger backfill CLI smoke check against a temporary project artifact root.

Generate a reliability scorecard artifact:

make reliability-scorecard

Writes markdown + JSON scorecard outputs under .artifacts/reliability/. Includes deterministic repro fixtures for basic-turn, runtime-termination recovery, and stale-thread remap.

Create a one-command reliability diagnostics bundle:

make reliability-bundle

Writes bundle directory + .tgz archive under .artifacts/reliability/bundles/. Set RELIABILITY_BUNDLE_SKIP_SCORECARD=1 to skip rerunning scorecard generation.

make prepush-local

Runs quick, targeted smoke, and Team A reliability harness before push. This is the canonical local CI gate for contributors.

Install an optional local pre-push hook:

make install-local-hooks

pnpm -s run check

Builds and runs full Swift test suites.

make ci

Runs the full local CI gate sequence.

cd apps/CodexChatApp
swift run CodexChatCLI doctor
swift run CodexChatCLI smoke
swift run CodexChatCLI repro --fixture basic-turn
swift run CodexChatCLI repro --fixture runtime-termination-recovery
swift run CodexChatCLI repro --fixture stale-thread-remap
swift run CodexChatCLI replay --project-path <project-path> --thread-id <thread-uuid> --json
swift run CodexChatCLI ledger export --project-path <project-path> --thread-id <thread-uuid>
swift run CodexChatCLI ledger backfill --project-path <project-path> --json
swift run CodexChatCLI policy validate --file ../../config/runtime-policy/default-policy.json

ledger backfill defaults to full-history export per thread and only skips threads with valid markers pointing to existing ledger files.

make release-dmg

Builds signed/notarized DMG artifacts when signing credentials are configured.

make release-prod

Builds/signs/notarizes locally and publishes GitHub release assets from your machine. Set USE_GITHUB_RELEASE_WORKFLOW=1 to opt into the manual GitHub-hosted release workflow path. When a release includes remote-control changes, also run make remote-control-prod-e2e, make remote-control-deploy-verify, and make remote-control-post-deploy-monitor.

• App-level tests: apps/CodexChatApp/Tests/CodexChatAppTests
• Package-level tests: packages/*/Tests
• Root tests/: shared fixtures and cross-package integration assets (not the primary home of unit tests)

• Conversation-first UI with a stable two-pane layout.
• No persistent third pane in current releases.
• Accessibility and explicit safety controls are mandatory.

• SUPPORT.md
• SECURITY.md
• CHANGELOG.md
• CONTRIBUTING.md
• docs-public/README.md
• docs-public/INSTALL.md
• docs-public/ARCHITECTURE_CONTRACT.md
• docs-public/SECURITY_MODEL.md
• docs-public/REMOTE_CONTROL.md
• docs-public/MODS.md
• docs-public/MODS_SHARING.md
• docs-public/PERSONAL_ACTIONS.md
• docs-public/DEVELOPER_AGENT_WORKFLOWS.md
• docs-public/RELEASE.md

make quick
make oss-smoke
make reliability-local
make reliability-scorecard
make prepush-local
pnpm -s run check
make reliability-bundle
pnpm -s run check

MIT. See LICENSE.