Skip to content

Dev environment

The dev workflow uses uv for dependency management plus a system GStreamer install (macOS only) for the streaming recorder.

Prerequisites

  • Python 3.13 (any 3.11+ works, 3.13 is the build target).
  • uv. Install via Homebrew on macOS: brew install uv. Or via the standalone installer.
  • macOS only: GStreamer.framework installed system-wide (download from gstreamer.freedesktop.org). Both runtime and development packages.
  • Git — including submodule support.

Clone + submodules

git clone https://github.com/cloneisyou/cue.git
cd cue
git submodule update --init --recursive

The submodules (vendor/ocap-macos, vendor/ocap-windows, vendor/open-world-agents-private) are required for the recorder pipeline. See Submodules & vendoring for what each one provides.

macOS: GStreamer + PKG_CONFIG_PATH

PyGObject (a transitive dep through ocap) needs pkg-config to find GStreamer.framework's headers. Set this before running uv pip install:

export PKG_CONFIG_PATH="/Library/Frameworks/GStreamer.framework/Versions/1.0/lib/pkgconfig"

If you skip this, the pygobject build will fail with a "package gobject-introspection-1.0 was not found" error.

Don't run from a miniforge / conda shell

This is the single most common dev-machine failure mode on macOS.

Miniforge / conda environments inject their own GStreamer / GLib dylibs into DYLD_LIBRARY_PATH. When Cue's process starts inside such a shell, those dylibs load before GStreamer.framework's, and GStreamer pipeline parsing crashes on subtle symbol mismatches.

Workaround: open a fresh terminal window with no miniforge activation, or explicitly conda deactivate until the prompt has no (base) / (env) prefix.

A safe uv venv invocation that pins the interpreter to a non-conda Python:

uv venv --python /opt/homebrew/opt/python@3.13/bin/python3.13

Or just use Homebrew's python3 directly:

brew install python@3.13
uv venv --python python3.13

Install

# macOS
uv pip install -e ".[macos]"

# Windows
uv pip install -e ".[windows]"

Add ,on-device if you want the local digest backend dependencies pre-installed:

uv pip install -e ".[macos,on-device]"

The on-device extra pulls in huggingface_hub for the resumable Gemma 4 weight download. The bundled llama-server binary is downloaded by the build script (scripts/build_nuitka.sh) on first build.

Run

uv run python -m cue

A ◈ icon appears in the menu bar (macOS) or system tray (Windows). On first launch the API key prompt appears; paste an Anthropic key and continue.

Test

uv pip install -e ".[macos,dev]"   # adds pytest
uv run pytest -q

The test suite covers PII recognizers, digest output scrub, frame selection, image preprocessing, llama-server contract, local model manifest, and the settings model. See Eval & smoke for the digest-quality eval harness (separate from unit tests).

Lint + format

uv run ruff check src/ tests/
uv run ruff format src/ tests/

CI runs these on push / PR. Vendor submodules are excluded from ruff.

Common gotchas

  • pygobject install fails — PKG_CONFIG_PATH not set pre-install. Run pkg-config --list-all | grep gstreamer to verify it sees the framework.
  • Streaming recorder dies with rc=-11 (SIGSEGV) on macOS — conda dylib pollution. See "Don't run from a miniforge / conda shell" above.
  • Hotkey doesn't fire — Accessibility permission not granted for your interpreter. See Troubleshooting.

Next