| name | cua-dev |
| description | Guide for developing Puffer's computer-use integration and vendored CUA driver. Use when Codex works on vendor/cua-driver, scripts/build-cua-driver.sh, scripts/cua-computer-sandbox.sh, docker/cua-driver-native, CUA MCP manifests, screenshots/image tool-result handling, or specs/puffer-core/118.md. |
CUA Dev
Use this skill for Puffer computer-use work. Puffer's model loop is the agent;
CUA provides desktop tools over MCP or the vendored cua-driver binary.
Read The Right Source First
Choose the reference before editing:
specs/puffer-core/118.md: integration topology, image tool-result contract,
native container path, desktop path, and known quirks.vendor/cua-driver/PUFFER_NOTICE.md: vendoring boundary and license rules.vendor/cua-driver/Skills/cua-driver/SKILL.md: runtime tool behavior and
operating invariants for driving GUI apps.vendor/cua-driver/Skills/cua-driver/MACOS.md,
WINDOWS.md, or LINUX.md: platform-specific behavior.vendor/cua-driver/PARITY.md: parity expectations against upstream CUA
surfaces and known divergences.
Choose The Integration Path
Match the task to one of the existing paths:
- Sandbox bridge:
scripts/cua-computer-sandbox.sh runs CUA's Python
computer-server in an XFCE Docker sandbox and exposes streamable HTTP MCP
at http://localhost:8000/mcp/.
- Native container:
docker/cua-driver-native/ builds a Linux container
with the Rust cua-driver mcp server. Use stdio via docker exec -i.
Pass --no-overlay under Xvfb unless a compositor is known to alpha-blend the
overlay correctly.
- Desktop vendored driver:
vendor/cua-driver/ builds separately from the
Puffer workspace. scripts/build-cua-driver.sh installs it to
$PUFFER_HOME/bin/cua-driver and writes a user-scoped MCP manifest. Do not
commit generated manifests under $PUFFER_HOME.
Do not replace Puffer's model loop with CUA's own agent loop unless the user
explicitly asks for an experiment and the licensing/runtime implications are
spelled out.
Editing Rules
- Treat
vendor/cua-driver as vendored third-party MIT source. Preserve
LICENSE and PUFFER_NOTICE.md.
- Do not vendor CUA
som, cua-agent[omni], or other AGPL-3.0 components.
- Keep Puffer-facing manifests, scripts, and specs outside the vendored
workspace unless the change belongs to the driver itself.
- The root
Cargo.toml excludes vendor/cua-driver; run vendor cargo commands
from vendor/cua-driver.
- Do not wire telemetry, analytics, or feedback reporting into Puffer. If
touching upstream telemetry-shaped code inside the vendor tree, keep it
isolated from Puffer defaults.
- Preserve Puffer repo constraints for new Rust code: docstrings for public
functions, ASCII unless existing context requires otherwise, small modules,
and no new Rust source file over 1000 lines.
Load-Bearing Contracts
Computer-use only works when screenshots reach the model as image content.
When changing MCP, runner, or tool-result code, protect this contract:
- Screenshot-like MCP results must preserve image parts, not flatten them into
text-only summaries.
- Puffer should surface image tool results to the provider path that supports
image inputs.
- A multi-tool-call turn should be able to loop through screenshot, reason,
click/type, and screenshot again.
For Linux native containers, remember the current quirks documented in
specs/puffer-core/118.md: overlay can make screenshots black under Xvfb, and
type_text has synthetic input limitations. Prefer fixing the backend
deterministically over adding model prompt workarounds.
For macOS desktop work, preserve CUA's background-driving principle. Avoid
changes that steal focus, move the real cursor unnecessarily, or require
manual app foregrounding except where platform permissions demand it.
Validation
Pick the narrowest validation that proves the change:
cargo fmt --check
cargo test --workspace -- --test-threads=1
Use the root workspace tests for Puffer-facing changes. For vendored driver
changes, run from the vendor workspace:
cd vendor/cua-driver
cargo fmt --check
cargo test -p cua-driver
For sandbox bridge changes:
./scripts/cua-computer-sandbox.sh status
./scripts/cua-computer-sandbox.sh shot /tmp/cua-shot.png
For desktop driver install or manifest changes:
./scripts/build-cua-driver.sh
puffer mcp list
For platform-specific CUA behavior, run or update the relevant integration or
parity tests under vendor/cua-driver/tests/integration/ when the host OS can
support them. If a test is OS-specific and cannot run locally, state that
clearly and include the exact command that should be run on that platform.
Spec Updates
When changing CUA behavior or integration contracts, add the next numbered spec
under the component you touched. Use specs/puffer-core/ for model-loop, MCP,
script, or manifest integration changes, and keep specs/puffer-core/118.md as
the overview only when the overview itself needs correction.
