Skip to content

Submodules & vendoring

This page mirrors implementation notes maintained in CLAUDE.md. Update both when changing this subsystem.

Cue ships with three git submodules under vendor/. They're pinned to specific branches so behavioral guarantees stay reproducible.

What's under vendor

vendor/
├── open-world-agents-private/
│       └── projects/
│           ├── owa-core/                # Runnable / Listener base classes
│           ├── owa-msgs/                # message schemas (KeyboardEvent, ScreenCaptured, ...)
│           ├── owa-env-desktop/         # platform-specific keyboard/mouse/window listeners
│           └── mcap-owa-support/        # MCAP write/read for owa messages
├── ocap-macos/                          # owa.ocap_macos.recorder — GStreamer pipeline + listeners
└── ocap-windows/                        # owa.ocap_windows.recorder

Why each one is vendored

Submodule Why it's pinned
open-world-agents-private Pinned to branch feat/owa-env-desktop-linux because main unconditionally imports ctypes.windll on macOS — the branch guards Windows-only imports with platform.system() checks.
ocap-macos Pyproject pins owa-env-desktop==0.6.5 (matches what's on the open-world-agents branch above). Pinning the submodule keeps that contract stable.
ocap-windows Same shape, Windows side.

Init + update

After cloning Cue:

git submodule update --init --recursive

After pulling main:

git pull
git submodule update --init --recursive

Forgetting the submodule update leaves stale recorder code and typically surfaces as ModuleNotFoundError: owa.ocap_macos on the next uv pip install -e . or as version-mismatch crashes in the recorder.

Cross-platform sync rule

ocap-macos and ocap-windows must stay in sync on the CLI surface because cue.recorder calls them via the same argv shape. If you add a new CLI flag, add it to both submodule repos and bump both submodule pins in this repo in the same PR. See Cross-platform rule.

How updates land

The recommended flow when a submodule needs a change:

  1. Make the change in the submodule repo (e.g. vendor/ocap-macos), commit on its feature branch, push.
  2. In the Cue repo, cd vendor/ocap-macos && git pull (or fetch
  3. checkout the new commit).
  4. Back in the Cue repo root, git add vendor/ocap-macos, commit the bumped submodule SHA on a Cue PR.

The Cue PR is what makes the new submodule SHA visible to other contributors and CI.

Build-time bundling

Frozen builds bundle the vendor .dist-info so importlib.metadata.entry_points() discovery works for the OWA plugin system. scripts/build_nuitka.sh (macOS) and scripts/build_installer.py (Windows) handle this — see Release builds.

llama-cpp prebuilt

vendor/llama-bin/ is not a git submodule. It's downloaded on-demand by the build script from the official ggml-org/llama.cpp release artifacts and verified by checksum. Gitignored. See Release builds for the cross-platform sourcing rules.

See also