CoFleet

Inspiration

I use Codex across several projects and machines. The moment I walked away from my Mac, the useful context split apart: which project was active, whether Codex was waiting for approval, what the latest response said, and which machine owned the task.

I wanted Codex to feel less like a collection of tabs I had to chase and more like a fleet I could glance at and steer. That became CoFleet.

What it does

CoFleet pairs directly with every Mac or Linux host that runs Codex and brings the canonical Codex task state into native Apple apps. It works beside Codex as a project-control layer: CoFleet keeps goals, current work, and the freshest conversation visible across the fleet, while Codex remains the place for focused development.

Progress shows each project's freshest real Codex exchange, current action, connectivity, source-control state, and a fast composer. From Mac or iPhone, Codex Companion mode can tell the project’s owning Mac to open that exact thread in Codex Desktop.
Dashboard combines host health, active turns, approvals, recent sessions, and account limits.
Agent Bay resumes real Codex tasks with Markdown, reasoning and tool activity, attachments, questions, approvals, model controls, and five-at-a-time session history.
Active keeps a selected project and its live conversation together in a responsive Mac/iPhone workspace.
Battle turns project todos and pets into a playful native SceneKit progress view.
Apple Watch, widgets, and complications keep focused status and latest replies visible when the main app is suspended.

Each host is paired independently through private Tailscale HTTPS. Codex remains responsible for ChatGPT authentication, task history, turns, and transcripts. CoFleet never reads or copies ~/.codex/auth.json.

How I built it

The Apple side is Swift 6 using SwiftUI, SceneKit, WidgetKit, WatchConnectivity, and native platform navigation. A small Python service, cofleet-host, runs beside the official Codex app-server on each machine. It translates app-server JSONL into a stable authenticated REST/SSE surface for the Apple clients.

Pairing uses one-use, ten-minute codes and per-device tokens. Host data is scoped in SQLite. Live turn changes arrive through event streams with replay and reconnect support instead of aggressive polling. Tailscale Serve publishes the loopback-only host over private HTTPS; public Funnel exposure is rejected.

The app keeps Codex task and turn IDs host-scoped, so a task from one machine cannot accidentally resolve against another. Notes, todos, pet imports, snapshots, idempotency keys, and source-control summaries are stored separately from Codex's own authoritative task history.

How I used Codex and GPT-5.6

Codex was the primary environment used to build CoFleet, and GPT-5.6 was involved across the full development loop—not just for a one-off code generation step.

It helped separate a private multi-provider prototype into a clean, Codex-only public architecture.
It implemented and reviewed Swift, Python, REST/SSE, SceneKit, Watch, widget, and session-routing work.
It wrote and strengthened race-condition, paging, transport, interaction, and host-service tests.
It drove real simulator comparison: matching screens were captured, visual drift was found, and the public app was corrected from evidence rather than source inspection alone.
It ran live end-to-end smoke checks against Codex app-server.
Finally, CoFleet dogfooded itself: a GPT-5.6-Sol task was resumed through CoFleet, streamed tool activity, requested a read-only command approval, honored Allow once, and returned its final answer in Agent Bay.

This used the official Codex experience and ChatGPT sign-in; CoFleet does not require an OpenAI API key.

Challenges I ran into

The hardest part was preserving one source of truth across several lifecycles. A Mac window, an iPhone, a suspended Watch app, and a reconnecting network client can all observe the same task at different moments. Treating cached UI state as authoritative caused stale sessions and slow refreshes, so the design moved toward host-scoped canonical IDs, event replay, idempotent turn starts, and explicit reconciliation.

The second challenge was keeping the public extraction honest. The original prototype supported several private harnesses and personal integrations. CoFleet needed to retain the working interaction and visual model while removing private topology, provider-specific assumptions, credentials, and third-party artwork.

The third was visual verification. Passing tests did not catch responsive layout drift or a light/dark appearance regression. Side-by-side simulator captures became part of the proof loop.

Accomplishments that I'm proud of

CoFleet can display and continue canonical Codex tasks instead of creating a parallel chat history.
A project card on either Mac or iPhone can hand the exact task back to Codex Desktop on the machine that owns it, making CoFleet useful as an always-available project-goal tracker rather than another isolated chat client.
A live GPT-5.6 turn, including its command approval, completed through CoFleet itself.
The same project model spans Mac, iPhone, Watch, widgets, complications, and a playful SceneKit view.
Multi-host access stays private and does not copy Codex credentials into the client apps.
The repository is structured as a professional Apple monorepo plus a separately testable Python host package.

What I learned

The most important lesson was that a companion should complement the provider, not impersonate it. Codex remains authoritative; CoFleet focuses on secure transport, presentation, and continuity.

I also learned to prefer pushed state with bounded replay over polling, and to match verification to the bug: protocol tests for protocol behavior, race tests for concurrency, and screenshots for visible UI claims.