NOTE FROM JOSH: This is entirely vibe coded, i haven't read the code or the contents of this readme... Enjoy

Codex Radial Wheel

An unofficial native macOS menu-bar utility for opening bookmarked Codex desktop tasks with a radial gesture—and a small reusable kit for building other radial launchers.

Hold the shortcut, point at a wedge, and release. Custom slots can hold individual tasks or five-task Groups. The bottom wedge always creates a new task, and the bottom-right wedge fans out the five most recently finished tasks.

Important

This project is not affiliated with or endorsed by OpenAI. Its Codex adapter uses experimental methods from the desktop app's bundled codex app-server; those methods are not a supported public desktop API and can change without notice. See Integration notes.

Will it connect to my Codex automatically?

Usually, yes. No API key or separate login is required.

At launch the adapter looks for the codex executable inside the installed Codex or ChatGPT desktop app, then falls back to codex on PATH. It starts that executable locally and uses the Codex account already signed in on the machine. Selecting a wedge opens the desktop app through a codex:// deep link.

This is automatic discovery, not an OAuth connection or official extension system. If the desktop app changes its executable location, app-server protocol, or deep-link routes, the adapter may require an update. The menu-bar diagnostics show which executable was found. Advanced users can set CODEX_RADIAL_WHEEL_EXECUTABLE to an explicit path.

Requirements

• macOS 14 or newer. Personally tested on macOS 14.6 (23G80) on Apple silicon; the package does not intentionally depend on Apple-silicon-only APIs.
• Codex desktop installed and signed in.
• Xcode Command Line Tools with Swift 5.10 or newer to build from source.
• No special permission for the default Command + \`` shortcut. Input Monitoring is needed only if a custom shortcut contains Fn`.

The built-in shortcut is Command + \``. Hold it, point at a wedge, and release it to open the selected task. It uses the standard macOS hotkey API and requires no Input Monitoring or Accessibility permission. It replaces Command + Fn + Rfrom earlier versions; existing installations using that former default migrate automatically. Only a custom shortcut containing the physicalFn` modifier needs Input Monitoring.

Install from source

git clone https://github.com/ILikeAI/codex-radial-wheel.git
cd codex-radial-wheel
./scripts/build-app.sh
open "dist/Codex Radial Wheel.app"

The build script has no package dependencies and creates an ad-hoc-signed release app in dist/. Move that app to /Applications or the Desktop if desired.

On first launch:

1. Confirm that the menu-bar wheel icon appears and its connection row reports the discovered Codex executable.
2. Hold `Command + ``, point at a wedge, and release.
3. While holding the shortcut, right-click a custom wedge to assign it, turn it into a Group, or add and remove wedges. Choose Change Shortcut… from the menu-bar icon to record another global shortcut.

Ad-hoc signatures can cause Input Monitoring permission to become stale after rebuilding. Contributors can use a trusted, stable Apple Development or local Code Signing certificate by copying .radial-wheel.local.env.example to .radial-wheel.local.env and filling in their identity. That file is ignored by Git. The app explains Input Monitoring once per selected Fn shortcut; if macOS later invalidates an existing permission, use Repair / Enable… from the menu-bar icon.

Features

• Three to eight persistent custom slots, initially seeded from pinned and recent Codex tasks.
• Task Groups that fan out to as many as five tasks with the same point-and-release gesture.
• Fixed New Task and Recently Finished wedges.
• Five-wedge recently finished fan with completed, failed, and interrupted states.
• Wheel-owned unread dots and an animated running indicator.
• In-place right-click assignment, Group management, and wedge add/remove actions.
• A menu-bar shortcut recorder with automatic rollback when a shortcut is unavailable.
• Optional AI focus summaries generated through the existing Codex session.

AI summaries are disabled by default. Enabling them explains that clipped text from the two newest turns of assigned tasks is processed through Codex and may count toward normal usage. Common token-like strings are redacted on a best-effort basis, cached summaries can be cleared from the menu, and nothing is appended to the source task.

Repurposing the wheel

The Swift package has three layers:

RadialWheelKit       source-neutral models, protocols, persistence, geometry,
                     hotkeys, and AppKit wheel rendering
CodexIntegration     executable discovery, app-server transport, task decoding,
                     state inference, summaries, rename, and deep links
CodexRadialWheel     the macOS app shell that wires the two together

An integration supplies two small boundaries:

protocol WheelItemProviding {
    func fetchItems(
        itemIDsForDetailedStatus: [String],
        recentStatusCandidateLimit: Int,
        completion: @escaping (Result<[WheelItem], Error>) -> Void
    )
}

protocol WheelDestinationRouting {
    func url(for destination: WheelDestination) -> URL?
}

Renaming and AI summaries are optional capabilities. Examples/StaticURLWheel shows a non-Codex source backed by ordinary URLs. Forks can change wedge count, system-wedge positions, labels, recent-item limits, and core colours through WheelLayoutConfiguration, WheelLabels, and WheelTheme without editing geometry code.

Development

./scripts/check.sh

Or run individual steps:

swift test --disable-sandbox
swift build --disable-sandbox
./scripts/build-app.sh

Regenerate the checked-in app icon with:

CLANG_MODULE_CACHE_PATH=.build/module-cache \
  swift scripts/generate-app-icon.swift AppResources/AppIcon.icns

The test suite covers generic wheel behavior, legacy preference decoding, Codex state inference, sanitized app-server fixtures, transcript redaction, executable discovery, and deep links. CI performs the same tests and an ad-hoc app-bundle build on macOS.

Status limitations

• Running is inferred. A separate app-server process cannot read the desktop renderer's authoritative in-memory state. Recent transcript activity can temporarily override a persisted interrupted state.
• Unread dots belong to the wheel. Opening a task directly in Codex does not clear them.
• Titles follow Codex. Rename a task in Codex and the wheel adopts the new title during its next automatic metadata refresh; direct task renaming from the wheel is intentionally not exposed.
• Summaries are optional model calls. They may use account quota and best-effort redaction cannot guarantee removal of every sensitive value.

Metadata refreshes every 15 seconds. The detailed rationale and current app-server methods are in Integration notes.

Managing the wheel

Hold the shortcut and right-click any custom wedge. Each wedge can be empty, contain one task, or contain a Group. Turning a task wedge into a Group keeps that task as its first member. A wedge menu renames Groups, adds or removes Group tasks, changes the assigned task, and removes that wedge. Right-click a Group's expanded task to remove it from that Group, or right-click the wheel center to add a wedge. Removing or clearing a wedge only removes wheel shortcuts; it never deletes Codex tasks.

Groups and Recently Finished expand as soon as the pointer enters their wedge. Continue outward to a child wedge and release the shortcut to open it. Groups are intentionally limited to five tasks so the fan remains readable.

After a right-click edit, the wheel redraws immediately and remains visible while the shortcut is still held. Releasing the shortcut while a menu or naming prompt is open waits for that interaction to finish before dismissing the wheel.

Troubleshooting

No tasks appear

Confirm that Codex desktop is installed and signed in. The app refreshes automatically at launch, every 15 seconds, and when the wheel opens after being idle. The disabled connection row in the menu shows the selected executable. To override discovery:

CODEX_RADIAL_WHEEL_EXECUTABLE=/absolute/path/to/codex \
  "dist/Codex Radial Wheel.app/Contents/MacOS/CodexRadialWheel"

A custom Fn shortcut is enabled but does nothing

Choose Change Shortcut… → Restore Default to return to the permission-free `Command + `` shortcut. To keep using Fn, remove any stale Codex Radial Wheel entry from Input Monitoring, reopen the app, and grant it again. Use a stable signing identity during repeated development.

Reset local state

defaults delete io.github.ilikeai.codex-radial-wheel.settings

Existing installations migrate bookmarks and cached summaries once from the earlier com.josh.codex-radial-wheel.settings suite.

Design references

• Recently Finished and navigation concept
• Wheel visual restyle lab

Released under the MIT License.