{"id":45628283,"url":"https://github.com/bikz/codex-chat","last_synced_at":"2026-03-04T22:03:12.088Z","repository":{"id":339303494,"uuid":"1161347911","full_name":"Bikz/codex-chat","owner":"Bikz","description":"Open-source macOS SwiftUI Codex client with local Markdown chat history, reusable context, Skills + Mods, and explicit local safety controls.","archived":false,"fork":false,"pushed_at":"2026-02-23T23:01:20.000Z","size":18441,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T03:01:43.447Z","etag":null,"topics":["ai-agent","automation","codex","desktop-app","developer-tools","extensible","keychain","llm","local-first","macos","markdown","plugin-system","productivity","sqlite","swift","swiftui","xcode"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bikz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-19T02:14:34.000Z","updated_at":"2026-02-23T21:07:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Bikz/codex-chat","commit_stats":null,"previous_names":["bikz/codex-chat"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Bikz/codex-chat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikz%2Fcodex-chat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikz%2Fcodex-chat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikz%2Fcodex-chat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikz%2Fcodex-chat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bikz","download_url":"https://codeload.github.com/Bikz/codex-chat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bikz%2Fcodex-chat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29961924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","automation","codex","desktop-app","developer-tools","extensible","keychain","llm","local-first","macos","markdown","plugin-system","productivity","sqlite","swift","swiftui","xcode"],"created_at":"2026-02-23T22:28:22.319Z","updated_at":"2026-03-04T22:03:12.077Z","avatar_url":"https://github.com/Bikz.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodexChat\n\nCodexChat is an open-source, local-first, macOS-native Codex client built with SwiftUI.\nIt integrates with the local `codex app-server` runtime and is designed for safe, reviewable agent workflows against real project folders.\n\nCore differentiators:\n\n- Native SwiftUI macOS app (not a cross-platform web shell).\n- Conversations are persisted as local Markdown files you own.\n- Skills and Mods support workflow automation and deep UI customization.\n- Safety controls are explicit and legible (approvals, diff review, guardrails).\n- Contributor tooling is built in (`CodexChatCLI`) for reproducible diagnostics and smoke tests.\n\n## Features\n\n- Native SwiftUI macOS experience for the Codex runtime with a chat-first flow.\n- Local Markdown memory: conversations and project context are stored on disk as editable `.md` files.\n- Theme customization with tunable palette, surface, text, and accent colors.\n- Mods and Mods Bar support UI/workflow customization and side helpers while chatting.\n- Built-in terminal workspace with multi-shell support for command-first and agent-assisted execution.\n- Skill workflows: install from skills.sh or create and save your own, then trigger with `$` shortcuts.\n- Native macOS actions (calendar, messages, desktop cleanup) with preview-first confirmations and safety controls.\n- Project safety controls for sandbox mode, approval policy, network access, and web search.\n- Chat archive persistence with searchable local metadata.\n- Keychain-backed secret handling for API keys.\n- Deterministic contributor workflows via CLI diagnostics and fixtures.\n\n## Screenshots\n\n### Codex Chat (Default)\n![Codex Chat default interface](docs-public/screenshots/codex-chat.png)\n\n### Local Conversation Memory\n![Conversation memory stored locally](docs-public/screenshots/conversation-memory.png)\n\n### Theme Switching\n![Theme customization and switching](docs-public/screenshots/cc-themes.png)\n\n### Mods + Prompt Bar\n![Mods and prompt bar customization](docs-public/screenshots/cc-mod-promptbar.png)\n\n### Terminal Workspace\n![Integrated terminal workspace](docs-public/screenshots/cc-terminal.png)\n\n## Repository Layout\n\n- `apps/CodexChatHost`: canonical GUI app target (`com.codexchat.app`) and release source.\n- `apps/CodexChatApp`: shared app/runtime module (`CodexChatShared`) and `CodexChatCLI`.\n- `apps/RemoteControlRelay`: outbound-only websocket relay scaffold for remote mobile control.\n- `apps/RemoteControlPWA`: installable mobile/web companion UI scaffold.\n- `packages/*`: modular Swift packages (`Core`, `Infra`, `UI`, `CodexKit`, `Skills`, `Memory`, `Mods`, `Extensions`).\n- `skills/first-party`: tracked first-party skill templates (including personal-action playbooks for macOS workflows).\n- `tests/fixtures`: shared fake runtime fixtures used by smoke/integration paths.\n\n## Requirements\n\n- macOS 14+\n- Xcode 16+ (Swift tools `6.0`)\n- Node 22+\n- Homebrew\n- SwiftFormat, SwiftLint, gitleaks\n\n## Quick Start\n\n```sh\nbash scripts/bootstrap.sh\n```\n\nRun the canonical GUI:\n\n```sh\nopen apps/CodexChatHost/CodexChatHost.xcodeproj\n```\n\nUse scheme `CodexChatHost`.\n\n## Contributor Commands\n\n### Fast validation\n\n```sh\nmake quick\n```\n\nRuns metadata/parity checks, format check, lint, and fast tests.\nThis is the only check we keep in hosted GitHub Actions.\n\n### OSS smoke checks\n\n```sh\nmake oss-smoke\n```\n\nRuns deterministic contributor smoke checks using `CodexChatCLI`.\n\n### Team A local reliability harness\n\n```sh\nmake reliability-local\n```\n\nRuns deterministic runtime/data reliability suites (recovery, mapping, approvals, durability).\nAlso includes a `ledger backfill` CLI smoke check against a temporary project artifact root.\n\nGenerate a reliability scorecard artifact:\n\n```sh\nmake reliability-scorecard\n```\n\nWrites markdown + JSON scorecard outputs under `.artifacts/reliability/`.\nIncludes deterministic repro fixtures for `basic-turn`, runtime-termination recovery, and stale-thread remap.\n\nCreate a one-command reliability diagnostics bundle:\n\n```sh\nmake reliability-bundle\n```\n\nWrites bundle directory + `.tgz` archive under `.artifacts/reliability/bundles/`.\nSet `RELIABILITY_BUNDLE_SKIP_SCORECARD=1` to skip rerunning scorecard generation.\n\n### Local pre-push gate\n\n```sh\nmake prepush-local\n```\n\nRuns `quick`, targeted smoke, and Team A reliability harness before push.\nThis is the canonical local CI gate for contributors.\n\nInstall an optional local `pre-push` hook:\n\n```sh\nmake install-local-hooks\n```\n\n### Full build + test validation\n\n```sh\npnpm -s run check\n```\n\nBuilds and runs full Swift test suites.\n\n### CI-equivalent local flow\n\n```sh\nmake ci\n```\n\nRuns the full local CI gate sequence.\n\n### Headless diagnostics and reproducible fixtures\n\n```sh\ncd apps/CodexChatApp\nswift run CodexChatCLI doctor\nswift run CodexChatCLI smoke\nswift run CodexChatCLI repro --fixture basic-turn\nswift run CodexChatCLI repro --fixture runtime-termination-recovery\nswift run CodexChatCLI repro --fixture stale-thread-remap\nswift run CodexChatCLI replay --project-path \u003cproject-path\u003e --thread-id \u003cthread-uuid\u003e --json\nswift run CodexChatCLI ledger export --project-path \u003cproject-path\u003e --thread-id \u003cthread-uuid\u003e\nswift run CodexChatCLI ledger backfill --project-path \u003cproject-path\u003e --json\nswift run CodexChatCLI policy validate --file ../../config/runtime-policy/default-policy.json\n```\n\n`ledger backfill` defaults to full-history export per thread and only skips threads with valid markers pointing to existing ledger files.\n\n### Release packaging\n\n```sh\nmake release-dmg\n```\n\nBuilds signed/notarized DMG artifacts when signing credentials are configured.\n\n### Production release publish (local-first CD)\n\n```sh\nmake release-prod\n```\n\nBuilds/signs/notarizes locally and publishes GitHub release assets from your machine.\nSet `USE_GITHUB_RELEASE_WORKFLOW=1` to opt into the manual GitHub-hosted release workflow path.\n\n## Test Layout\n\n- App-level tests: `apps/CodexChatApp/Tests/CodexChatAppTests`\n- Package-level tests: `packages/*/Tests`\n- Root `tests/`: shared fixtures and cross-package integration assets (not the primary home of unit tests)\n\n## Design Constraints\n\n- Conversation-first UI with a stable two-pane layout.\n- No persistent third pane in current releases.\n- Accessibility and explicit safety controls are mandatory.\n\n## Documentation\n\n- `CONTRIBUTING.md`\n- `docs-public/README.md`\n- `docs-public/INSTALL.md`\n- `docs-public/ARCHITECTURE_CONTRACT.md`\n- `docs-public/SECURITY_MODEL.md`\n- `docs-public/REMOTE_CONTROL.md`\n- `docs-public/MODS.md`\n- `docs-public/MODS_SHARING.md`\n- `docs-public/PERSONAL_ACTIONS.md`\n- `docs-public/DEVELOPER_AGENT_WORKFLOWS.md`\n- `docs-public/RELEASE.md`\n\n## Validation Reference\n\n```sh\nmake quick\nmake oss-smoke\nmake reliability-local\nmake reliability-scorecard\nmake reliability-bundle\npnpm -s run check\n```\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbikz%2Fcodex-chat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbikz%2Fcodex-chat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbikz%2Fcodex-chat/lists"}