CodexChat

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.

Release Status

• 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

Features

• 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.

Hosted Remote Bridge Status

The hosted remote-control bridge has been retired now that the Codex app
supports native remote access.

Local development and self-hosting references are kept for historical context,
but the hosted bridge environment is no longer maintained.

Install From Release

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.

Screenshots

Codex Chat (Default)

Local Conversation Memory

Theme Switching

Mods + Prompt Bar

Terminal Workspace

Repository Layout

• apps/CodexChatHost: canonical GUI app target (com.codexchat.app) and release source.
• apps/CodexChatApp: shared app/runtime module (CodexChatShared) and CodexChatCLI.
• apps/RemoteControlRelay: historical outbound-only websocket relay scaffold for remote mobile control.
• apps/RemoteControlPWA: historical 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.

Source Build Requirements

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

Source Build Quick Start

bash scripts/bootstrap.sh

Run the canonical GUI:

open apps/CodexChatHost/CodexChatHost.xcodeproj

Use scheme CodexChatHost.

Contributor Commands

Fast validation

make quick

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

OSS smoke checks

make oss-smoke

Runs deterministic contributor smoke checks using CodexChatCLI.

Team A local reliability harness

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.

Local pre-push gate

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

Full build + test validation

pnpm -s run check

Builds and runs full Swift test suites.

CI-equivalent local flow

make ci

Runs the full local CI gate sequence.

Headless diagnostics and reproducible fixtures

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.

Release packaging

make release-dmg

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

Production release publish (local-first CD)

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.

Test Layout

• 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)

Design Constraints

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

Documentation

• 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

Validation Reference

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

License

MIT. See LICENSE.