Snap-O Tweaks

Inspect live values and app-owned actions exposed by a debug-enabled Android app. Discovery, reads, and streams are read-only; change or reset values, or invoke an action, only when explicitly requested. Reset everything only when explicitly requested.

Choose the interaction surface

• Agents, shells, automation, or CI: Default to the snapo-tweaks CLI; it requires only Python 3 and Android Platform Tools on macOS or Linux.
• Direct integration: Use REST and server-sent events. See references/protocol.md for ADB forwarding, endpoints, typed values, batched updates, and streaming.
• Desktop inspection: Use Snap-O's macOS Tweaks tool.
• In-app controls: Integrate SnapOTweakOverlay.
• Custom interfaces: Build a browser, native, or Compose UI; browsers require a same-origin proxy.

Read references/interaction-surfaces.md for desktop, overlay, release/no-op, and custom-interface integration.

Resolve the Tweaks CLI

Use the executable bundled with this skill:

scripts/snapo-tweaks

Resolve this path relative to the directory containing this SKILL.md, not the current working directory. Call the resolved path $SNAPO_BIN; if it is absent, the skill installation is incomplete.

ADB resolves from PATH, ANDROID_SDK_ROOT, or ANDROID_HOME. Use --adb <path> or SNAPO_ADB to override it; pass --adb-host <host> and --adb-port <port> together for a remote ADB server.

Listings use ADB process and package information without contacting the app. JSON rows contain pid, processName, and packageName; unresolved identity fields are null. Friendly app labels and icons are not loaded.

Discover and inspect

1. Discover running tweak-enabled apps:

   "$SNAPO_BIN" apps --json
   

2. Select the device and, when multiple app sockets exist, the app socket:

   "$SNAPO_BIN" list -s <serial> -n <socket> --json
   "$SNAPO_BIN" get 'Typography/Font size' -s <serial> -n <socket> --json
   

   Select devices with -s <serial>, -d (USB), or -e (emulator). Use -n <socket> for every subcommand except apps when selection is ambiguous.

3. Include ordinary or app-owned tweaks the user has adjusted, even when their declarations are not currently in composition:

   "$SNAPO_BIN" list --all -s <serial> -n <socket> --json
   "$SNAPO_BIN" get 'Typography/Font size' --all -s <serial> -n <socket> --json
   

   The expanded list combines current tweaks and actions with retained snapshots of previously adjusted ordinary or app-owned tweaks. App-owned history preserves the effective value and modification status, not the source, callbacks, or observers. Use "modified": true to identify outstanding changes; a missing field always means false, even when value differs from default. Actions never include modified. Separate screens can reuse tweak names with different declarations; preserve every descriptor from list --all instead of deduplicating by name. get NAME --all reports an error when multiple declarations match; use list --all --json to inspect them. Historical tweaks can be inspected while inactive, but can only be changed or reset when their declaration is active. Actions are active-only.

4. Observe live complete snapshots:

   "$SNAPO_BIN" watch -s <serial> -n <socket> --json
   "$SNAPO_BIN" watch -s <serial> -n <socket> --once --json
   

   --once exits after the first complete snapshot. --json emits newline-delimited JSON; list and watch emit complete tweak and action snapshots. Event streams contain only currently active declarations; use list --all for historical value adjustments.

Change values only when requested

Inspect the descriptor first: the CLI parses int, float, boolean, color, string, enum, and bezier according to their declared types. Enum descriptors include an ordered list of enum names in options; use an exact option name when setting one. Quote names containing spaces or /, string values containing spaces, and hex colors.

"$SNAPO_BIN" set 'Typography/Font size' 42 -s <serial> -n <socket>
"$SNAPO_BIN" set 'Motion/Show' false -s <serial> -n <socket>
"$SNAPO_BIN" set 'Colors/Accent' '#3B82F6' -s <serial> -n <socket>
"$SNAPO_BIN" set 'Appearance/Theme' Dark -s <serial> -n <socket>

Successful updates and resets produce no output.

Reset only the explicitly requested value, or use --all only when the user explicitly requests resetting every modified tweak:

"$SNAPO_BIN" reset 'Typography/Font size' -s <serial> -n <socket>
"$SNAPO_BIN" reset --all -s <serial> -n <socket>

Invoke actions only when requested

Apps declare actions with the TweakAction(name) { ... } composable, imported from com.openai.snapo.tweaks.TweakAction. The declaration returns Unit, registers its callback only while the owner remains in composition, and does not execute the callback during composition. Actions have "type":"action", no value, and no default. Invoke an action only when the user explicitly requests its app-defined behavior:

"$SNAPO_BIN" action 'Preview/Refresh visible content' -s <serial> -n <socket>

The action command sends the registered name exactly as provided and does not accept arguments or execute arbitrary code. A descriptor marked "conflicted":true has multiple live owners and cannot be invoked; report the server's conflict and ask the app owner to register the shared action once or choose explicit, stable, unique names. Do not deduplicate callbacks or invent numeric suffixes. Reset-all ignores actions.

Availability and failures

Tweaks use app-local snapo_tweaks_<pid> sockets and normally exist only in debug-enabled apps. If no socket appears, check device authorization and selection, whether the app is running, its live Tweaks dependency/integration, debug/runtime policy, and server startup. If a socket exists but /tweaks is empty, the current Compose UI has no active tweak declarations; list --all can still return retained adjustments. Adjustment history lasts only for the current Android app process. Do not enable release servers or modify apps or dependencies without an explicit request. Preserve validation errors; the CLI cleans up its own temporary ADB forwards.