trails-cool/trails
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
trails/.agents/skills/cmux-browser/references/snapshot-refs.md
Ullrich Schäfer 19f2275b73 Move skills to .agents/skills for cross-agent compatibility 
Skills now live in .agents/skills/ — the standard convention
aligned with Pi, OpenAI Codex, and the Agent Skills spec.

.claude/skills is a symlink back to .agents/skills/ so Claude
Code still discovers them.

Updated CLAUDE.md to document the setup.
2026-06-09 13:31:20 +02:00

1.8 KiB
Raw Blame History

Snapshot and Refs

Element refs from snapshots make browser automation compact and reliable.

Related: commands.md, SKILL.md

Contents

How Refs Work

Classic flow:

full DOM/HTML -> selector guessing -> action

cmux flow:

snapshot -> refs (e1/e2/...) -> direct action

The Snapshot Command

cmux browser surface:7 snapshot
cmux browser surface:7 snapshot --interactive
cmux browser surface:7 snapshot --interactive --compact --max-depth 3

Using Refs

cmux browser surface:7 click e6
cmux browser surface:7 fill e10 "user@example.com"
cmux browser surface:7 fill e11 "password123"
cmux browser surface:7 click e12

Ref Lifecycle

Refs are invalidated when page structure changes.

cmux browser surface:7 snapshot --interactive
# e1 is "Next"

cmux browser surface:7 click e1

# page changed, take a fresh snapshot
cmux browser surface:7 snapshot --interactive

Best Practices

  1. Snapshot before interacting.
  2. Re-snapshot after navigation/modal/open-close flows.
  3. Use --snapshot-after on mutating actions.
  4. Scope snapshots with --selector for very large pages.

Troubleshooting

not_found / stale ref

cmux browser surface:7 snapshot --interactive

Element missing due visibility/timing

cmux browser surface:7 wait --selector "#target" --timeout-ms 10000
cmux browser surface:7 scroll --dy 400
cmux browser surface:7 snapshot --interactive

Too many elements

cmux browser surface:7 snapshot --selector "form#checkout" --interactive