Snap O Tweaks

Snap-O Tweaks

Inspect live values exposed by a debug-enabled Android app. Discovery, reads,

and streams are read-only; change or reset values only when explicitly

requested. Reset everything only when explicitly requested.

Choose the interaction surface

• Agents, shells, automation, or CI: Default to the shared snapo 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, atomic updates, and streaming.

• Desktop inspection: Use Snap-O's macOS Tweaks inspector.
• 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 shared CLI

Use the executable shared by the installed Snap-O plugin:

../../scripts/snapo

Resolve this plugin-root path relative to this SKILL.md, not the current

working directory. Call the resolved path $SNAPO_BIN; if it is absent, the

Snap-O plugin 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.

Discover and inspect

• Discover running tweak-enabled apps:

   "$SNAPO_BIN" tweaks apps --json

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

   "$SNAPO_BIN" tweaks list -s <serial> -n <socket> --json
   "$SNAPO_BIN" tweaks 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.

• Include every tweak the user has adjusted, even when its declaration is not

currently in composition:

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

The expanded list combines current tweaks with retained, previously adjusted

tweaks. Compare each descriptor's value with its default when the user

asks to apply all changes they made. 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.

• Observe live complete snapshots:

   "$SNAPO_BIN" tweaks watch -s <serial> -n <socket> --json
   "$SNAPO_BIN" tweaks 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 snapshots.

Event streams contain only currently active tweaks; use list --all for

historical adjustments.

Change values only when requested

Inspect the descriptor first: the CLI parses int, float, boolean,

color, and string according to their declared types. Quote names containing

spaces or /, string values containing spaces, and hex colors.

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

Successful updates and resets produce no output.

Reset only the explicitly requested value, or use --all only for an explicit

reset-everything request:

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

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.