SideCar

SideCar is a local-first macOS companion for Codex Desktop. It is designed as a floating native panel that observes active Codex threads, explains long-running work, and stages safe thread-level actions with explicit confirmation.

Two-Hour MVP Status

This repository is a two-hour MVP scaffold, not a finished Codex automation product. It is ready for public review as a small Swift package that demonstrates the shape of a local-first SideCar app:

• Native AppKit + SwiftUI floating panel.
• SwiftPM modules for app contracts, Codex integration, fixture-backed thread storage, Realtime voice token brokering, and UI.
• Fixture/demo mode that runs without private Codex state.
• Safe action-gating contracts for queued messages, /side tangents, steer, fork, interrupt, review, compact, and approvals.
• Live Codex app-server snapshot loading through initialize, thread/list, and thread/read.
• App-server notification stream reader/reducer contracts for thread, turn, item, command-output, and approval-request events.
• Confirmed safe actions can be sent to the live Codex app-server for the MVP-supported methods.
• Approval cards are visible and scoped; app-server approval request ids and response payloads are modeled, but live approval fulfillment remains disabled until the same-connection response path is wired.
• Realtime readiness, Option-Shift-Space voice hotkey entry, and screen-preview controls are available in Talk mode without sending visual context to a model.
• Documentation for architecture, privacy, compatibility, and design direction.

Current limitations are intentional: wiring the independent stream reader into app state, live approval response execution, signed/notarized distribution, full voice audio loop wiring, and production-grade ScreenCaptureKit UX are roadmap items.

Roadmap

1. Wire the app-server stream reader into the app session lifecycle and live UI state.
2. Promote fixture snapshots into sanitized regression fixtures.
3. Add signed/notarized macOS packaging.
4. Expand visual context consent UX before enabling richer screen-aware features.
5. Harden global hotkeys beyond the current AppKit monitor scaffold.

Requirements

• macOS 14 or newer.
• Xcode 16 or the Swift 6 toolchain.
• Optional: Codex Desktop for live integration work.
• Optional: OPENAI_API_KEY for Realtime voice experiments.

Setup

Clone the repository, then run the Swift package checks:

swift test
swift build
make audit-share

Run fixture mode:

swift run SideCar

The app opens as a menu bar accessory with a floating SideCar panel. It tries live Codex app-server loading first and falls back to fixture mode if Codex is unavailable.

Hotkeys:

• Option-Space toggles the SideCar panel.
• Option-Shift-Space opens Talk mode and checks Realtime readiness.

The /side button stages a guarded side conversation from the current thread context. Until Codex exposes a dedicated app-server /side method, SideCar sends this as a non-persistent thread/fork with instructions that treat the parent history as read-only reference context.

Build and open a local debug .app bundle:

make app
open -n dist/SideCar.app

The debug bundle is unsigned and intended for local review only. Release builds still need signing and notarization.

OpenAI API Key

Fixture mode does not require an OpenAI key.

For local voice development, provide OPENAI_API_KEY through your shell or a local uncommitted .env file:

export OPENAI_API_KEY="sk-..."
swift run SideCar

Copy .env.example only as a template. Do not commit real API keys. Normal app usage should store long-lived keys in Keychain and mint only ephemeral Realtime credentials for clients.

Test And CI

swift test

GitHub Actions runs swift test on macOS for pushes and pull requests. See .github/workflows/swift-test.yml.

Security Boundaries

MVP intentionally excludes direct shell execution, filesystem writes, config writes, plugin installation, worktree creation, and non-loopback app-server WebSocket access. Any future capability in those areas must be added through explicit action-gate contracts, tests, and documentation.

See docs/architecture.md, docs/privacy.md, docs/security.md, and docs/compatibility.md.

For a tight review walkthrough, use docs/demo-script.md.

Contributing

Start with docs/contributing.md. Please include tests for contract changes and avoid committing private Codex rollouts, sqlite databases, screenshots, API keys, or .env files.