visionOS Codex Kit

This repository packages four related pieces of work for Apple Vision Pro development:

• skill/visionos-3d-development: the installable reference skill bundle
• skill/visionos-app-bootstrap: the installable bootstrap skill bundle
• blueprints/templates: ready-to-copy visionOS starter apps
• build-tools: the optional pipeline used to rebuild and update the skill

Install

Run:

./install.sh

To print the repo version without installing:

./install.sh --version

To print the version currently installed into your Codex home:

./install.sh --print-installed-version

By default this installs into ${CODEX_HOME:-~/.codex}. To target a different Codex home:

./install.sh --codex-home /abs/path/to/.codex

The installer places:

• visionos-3d-development in ~/.codex/skills/visionos-3d-development
• visionos-app-bootstrap in ~/.codex/skills/visionos-app-bootstrap
• the blueprint payload in ~/.codex/vendor/visionos-codex-kit/blueprints
• an install manifest in ~/.codex/vendor/visionos-codex-kit/install.json

This split is intentional: Codex discovers the skills from skills/, while the bootstrap skill reads its larger template payload from vendor/.

The installer does not copy build-tools/ into ~/.codex. Those scripts stay in the repo because they are maintenance tooling, not runtime assets.

First-run Codex setup is supported. If ~/.codex does not exist yet, the installer creates it and stages the skills there anyway. That means a user can run ./install.sh before they have actually launched Codex. Once Codex starts using that same CODEX_HOME, the skills are already in place.

After Install

The bootstrap workflow is:

1. Ask Codex to use visionos-app-bootstrap when starting a new app.
2. Let it copy a blueprint from the installed vendor payload into your new workspace.
3. Rename and adapt the copied template.
4. Validate with the included tools/ scripts.

Typical prompt:

Use $visionos-app-bootstrap to create a new visionOS app from the installed mixed blueprint. Do not start from scratch.

Do not edit the installed templates directly inside ~/.codex/vendor/.... They are the source blueprints the skill copies from. The working project should be a separate copied workspace.

Versioning And Updates

This repo uses a single coordinated version for:

• both installed skills
• the installed blueprint payload
• the installer contract and manifest shape

The current repo version lives in VERSION. Git tags are expected to use the matching vX.Y.Z form.

Recommended user update flow:

git pull --ff-only
./install.sh

If users prefer a pinned release:

git fetch --tags
git checkout v0.2.0
./install.sh

install.sh records the installed repo version, commit, and exact tag match in ~/.codex/vendor/visionos-codex-kit/install.json.

Important boundary: rerunning ./install.sh updates the installed skills and future blueprint copies. It does not modify app projects that were already copied from a blueprint earlier.

Repository Layout

Skill

skill/visionos-3d-development/ is the canonical source for the main reference skill.

skill/visionos-app-bootstrap/ is the canonical source for the project bootstrap skill. That skill resolves the installed blueprint payload from the vendor area in ~/.codex.

For normal use, prefer ./install.sh over manual copying.

Blueprints

blueprints/templates/window-app-blueprint/ is the window starter.

blueprints/templates/mixed-room-blueprint/ is the immersive mixed-reality starter with room mesh visualization and reachable test content.

Each template is self-contained. After copying one to a new workspace, the usual flow is:

1. Rename the app, scheme, bundle identifier, and displayed strings.
2. Run ./tools/build_app_icon.sh if you changed the icon layers.
3. Run ./tools/regenerate_project.sh.
4. Run ./tools/deploy_to_active_device.sh.

The lower-level helper scripts also live in blueprints/shared-tools/. If you change those canonical copies, run blueprints/scripts/sync_shared_tools_into_templates.sh to refresh the vendored copies inside each template.

After installation, the bootstrap skill resolves these templates from:

• ~/.codex/vendor/visionos-codex-kit/blueprints/templates/window-app-blueprint
• ~/.codex/vendor/visionos-codex-kit/blueprints/templates/mixed-room-blueprint

Build Tools

build-tools/ contains the scripts and source manifests used to curate and rebuild the skill from local SDK data and official Apple sources.

Committed snapshots live in build-tools/snapshots/. Heavy generated output is excluded from git and is recreated locally under build-tools/generated/ or build-tools/tmp/ when you rerun the pipeline.