CodexCore

open-source native swift sdk for codex with a UI elements, full SDK surface mapping and an almost feature complete app to the official app for users to use the codex as a harness in their mac apps.

Comment

Inspiration

I really love the Codex app and the app-server but I couldn't reuse the components from the app for using codex as a harness for my other apps, where custom tools etc might be needed and harness serves the use much better than a standard agent loop.

I wanted to make the Codex accessible to any swift app therefore by making a first class SDK

What it does

CodexCore is a swift sdk fully wire compliant with codex app-server protocol. Apart from just being a Swift SDK for the app-server APIs, it also provides CodexCore UI which provides Swift components and state management with theming support and a fully featured fully native Swift codex app which can demonstrate the use of the CodexCore UI for other products.

Not only this, CodexCore also support renderer hooks for custom UI for any client that wants to render it's own widget on custom tool calls.

How we built it

I just Codexed it. :) Used a lot of my limits with Sol Ultra. Thanks to Tibo for resets. :D

Challenges we ran into

Honestly, the task for making an SDK seemed easier in the start but I soon realized the sheer complexity of a harness sdk. Codex app-server is still THE BEST harness sdk out there by a long shot, but the official sdks were only TypeScript and Python.

The biggest challenge was making sure the spec compatibilty with the app-server is to be bones. I was even bleeding edge on 0.145 alpha releases for a while to keep up with the new experimental paginated transcript.

Second biggest challenge was ensuring jank free experience of the scroll etc. I have switched stacks for the scroll layout in SDK so many times and made Codex profile, observe and make changes to make sure most surfaces render within 30ms.

Accomplishments that we're proud of

  1. The SDK works.
  2. I have made 2 apps with the SDK yet, and making more.
  3. Swift app is almost feature complete and on parity with the native app.
  4. The Swift app is really really fast and performant with a very low footprint.
  5. Honestly, the custom tool call renderer hooks feature. That was one of my initial goals. That separates a normal SDK from a fully adaptive one with batteries included.

What we learned

A bunch of learnings. I learnt a LOT about the Codex app-server protocol, learnt a LOT of things about the internals of the harness and why certain decisions are made. I plan to do a youtube series to explain the SDK internals to wider public. It was a masterclass for harness engineering for me.

What's next for CodexCore

CodexCore continues as the de-facto open-source swift sdk for Codex. I will continue to maintain it and add features and bring to even more parity with the current app. It also needs a LOT more surface refinement, which I'll focus on next.

Built With

Share this project:

Updates