Shuttle
Shuttle connects product managers, designers, and engineers through the Codex conversations behind their work. Attach a shared conversation link to a PRD so teammates' agents can read the decisions behind the requirements, send changes to each other's shared tasks, and review local work through an authorized preview. Everyone keeps working in their own local Codex workspace.
Download for macOS · Documentation · Open Shuttle
Requires an Apple Silicon Mac running macOS 15 or later.
[!IMPORTANT]
Shuttle is an early release for macOS. Its Codex Desktop integration is version-sensitive, so keep Shuttle and Codex Desktop up to date and review the privacy boundaries before using it with sensitive work.
From product decisions to a working preview
A PRD and prototype describe what to build. The conversation that produced them also explains why: constraints, alternatives, edge cases, and decisions. When each teammate starts their own agent workflow with only the documents, that context has to be reconstructed. Later changes mean another round of messages and handoffs.
Shuttle keeps that context available across roles:
- Product shares the background. The product manager shares the Codex task used to develop the requirements and adds its invitation link and collaboration prompt to the PRD alongside the prototype. Authorized designers and engineers can ask their own agents to read the complete persisted conversation history.
- Design and engineering continue locally. Each teammate uses the shared context in their existing Codex task, alongside their own files and tools. They can share their tasks back with message permission for two-way collaboration.
- Changes reach the task doing the work. After updating a requirement, the product manager asks their agent to send the change and the source task link to the designer's and engineer's shared tasks. Recipients can read the updated source conversation for the reasoning. Updates are sent explicitly; Shuttle does not automatically watch or synchronize conversations.
- Product reviews the running result. The engineer attaches a specific localhost service to their shared task and grants preview access. Product and design can open it remotely in a browser and send feedback to the engineering task from their own Codex tasks, without setting up the development environment.
The PRD contains a link to an authorized conversation, not an embedded copy of it. Access covers the whole shared task, so choose a task whose history is appropriate for those collaborators. Each destination task must be shared back with message permission to receive changes. The relevant owner's Companion must be online for reads, messages, and previews.
What Shuttle does
- Shares only the Codex tasks an owner explicitly approves.
- Lets authorized collaborators read a shared task's persisted history or submit feedback to its Codex queue.
- Keeps each participant in their own Codex task instead of sharing control of one desktop UI.
- Can relay an explicitly selected localhost service, including HTTP, SSE, WebSocket, and common HMR traffic.
- Stores accounts, invitations, permissions, devices, and preview configuration in the Relay, but not Codex task content or collaboration messages.
- Supports the hosted Relay at
https://shuttle.makesth.fun and self-hosted Relay deployments.
The owner's Companion must be online for task reads, message submission, and local previews. Shuttle does not maintain an offline task cache or message queue. A successful send means Codex's local queue accepted the message, not that it has been processed. Codex Desktop must load the task to process queued messages; a busy task finishes its current turn first, and interrupted tasks may need the owner's intervention.
How it works
Owner's Codex task
│
▼
Shuttle macOS app + local Companion
│ authenticated live connection
▼
Shuttle Relay ───────────────► Web app
│
▼
Collaborator's Shuttle Plugin in Codex
The macOS app manages Relay sign-in, authorization prompts, the local Companion, Plugin setup, and Sparkle updates. The Relay authenticates users and devices, enforces task permissions, and routes live requests. The Codex Plugin exposes the collaboration tools and safety guidance inside each participant's own task.
Read the product guide for the sharing model and the architecture for component and data boundaries.
Get started
- Download the latest ZIP from GitHub Releases, move
Shuttle.app to Applications, and open it.
- In the setup window, install the Codex Plugin and sign in to the default hosted Relay. These actions are independent; choose Relay only when using a self-hosted deployment.
- After installing the Plugin, open a new Codex task so it is loaded. You can reopen Set Up Shuttle… from the menu bar at any time to check the Plugin, change Relay, or sign in again.
If automatic Plugin setup cannot find the Codex CLI, install it manually:
codex plugin marketplace add yeliex/shuttle --ref master
codex plugin add shuttle@shuttle
Keep Shuttle running and signed in while using its tools. The Plugin connects to the Companion over local HTTP; it does not launch the app. If tools are unavailable, open Shuttle and check Set Up Shuttle… before retrying. App updates restart the Companion at the same local address and do not normally require restarting Codex. Installing or changing the Plugin configuration may require a new task.
Ask Codex to share the current task through Shuttle, then choose the collaborator, permission, expiration, and optional local previews in the native authorization window.
Share one link with anyone or restrict it to multiple email addresses. Email recipients get access without an acceptance step after verified sign-in. Link sharing can optionally be single-use. Access lasts 1, 7, or 30 days, or indefinitely; expiry blocks existing recipients from the task and its previews.
You can also invoke the Share Thread Skill directly with /share-thread.
Collaborators receive a prompt containing a precise resource link such as shuttle://shared/<id>. The Share Thread Skill uses that link to read the task or send a message without searching for unrelated tasks.
First launch on macOS
Shuttle is currently distributed without Apple notarization. On first launch, macOS may require you to open System Settings → Privacy & Security and choose Open Anyway. Only do this for a build downloaded from this repository's Releases page.
Subsequent in-app updates are verified with Sparkle Ed25519 signatures. Shuttle checks for updates automatically and displays the release notes before installation.
Self-host a Relay
Cloudflare Workers with D1, Durable Objects, and Static Assets is the primary deployment target. A single-instance Docker image with SQLite is published to ghcr.io/yeliex/shuttle-relay for private deployments.
The public deployment guide covers both runtimes and all supported environment variables. Start from apps/relay/.env.example; keep credentials in the deployment environment rather than committing them.
Development
Requirements:
- Node.js 24
- pnpm 11
- Swift 6.1 or later
- macOS 15 or later for the native client
- Codex Desktop for end-to-end collaboration
Install dependencies and run the local services:
pnpm install
pnpm start
Common checks:
pnpm lint
pnpm test:type
pnpm build
Build the native client separately:
cd apps/client
swift build
To preview the native sharing dialog without signing in or creating an invitation:
pnpm build:macos --authorization-preview
Open artifacts/authorization-preview/Shuttle Preview.app. This separate app uses example data and does not start the Companion, read account credentials, or check for updates. The title area and empty background can be dragged like the setup window.
Both sharing actions show an in-place submitting state, then a simulated completion screen. Copying uses a nonfunctional example link; no real share or invitation email is created. Close the window with the top-right close icon.
Repository layout
apps/client: native Swift menu bar app.apps/companion: local Node Companion and Codex host adapter.apps/relay: Hono Relay for Cloudflare Workers and Node.apps/web: authenticated account, invitation, task, device, and administration UI.apps/site: statically generated website and documentation.packages/contracts: shared protocol schemas.packages/ui: shared frontend components and styles.plugins/shuttle: packaged Codex Plugin, HTTP MCP configuration, and collaboration Skill.
Security and privacy
Shuttle is designed to fail closed:
- Unshared tasks and local ports are not listed or discovered by the Relay.
- Every task read, message, and preview request is checked against the current authorization.
- Task content and message bodies pass through live connections and are not persisted by Shuttle.
- Revoking a grant, leaving a share, or disconnecting a device removes the corresponding access.
- Content read from another task is treated as untrusted context by the Share Thread Skill.
See the privacy notice for stored data and operator responsibilities.
License
MIT
