@react-grab/cli 0.1.40 → 0.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-grab/cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "bin": {
     "react-grab": "./bin/cli.js"
   },

package/skills/react-grab/SKILL.md

@@ -10,60 +10,29 @@ description: >-
 
 # React Grab
 
-The user selects UI elements in their browser and copies them with React Grab. A
-background daemon captures each grab to `./.react-grab/history.jsonl`; you pull
-them with `grab read`. Nothing blocks the agent: the daemon runs detached and
-`read` returns promptly, so the loop survives shell-command timeouts.
-
-## Start the daemon (once)
-
-```bash
-npx grab@latest watch
-```
-
-This launches a detached daemon that watches the clipboard. It is idempotent per
-dir — re-running it while a daemon is already watching this project is a no-op —
-so it is safe to run at the start of every session. `--dir <path>` relocates the
-capture dir; `--text-only` skips the native clipboard reader.
+The user selects UI elements in their browser and copies them with React Grab.
+`npx grab pull` waits for new grabs and prints each as one line of JSON (usually
+one, sometimes a few if several were copied), starting the background watcher
+automatically the first time. Run it in a loop.
 
 ## The loop
 
 Repeat until the user says stop:
 
-1. Pull the next grabs (blocks up to 20s for one to arrive, then returns):
+1. Wait for the next grab:
 
 ```bash
-npx grab read --wait 20000
+npx grab pull
 ```
 
-Each line of stdout is one grab as JSON. Empty output means nothing new yet —
-just run it again.
+It blocks until the user grabs something, then prints the new grab(s) — one JSON
+object per line. Act on every line. If your shell cancels the command before a
+grab arrives, just run it again — nothing is lost; the watcher keeps capturing in
+the background and `pull` resumes where it left off.
 
-2. Act on each grab (below).
+2. Act on the grab (below).
 3. Go back to step 1.
 
-`read` advances a cursor (`./.react-grab/cursor.txt`), so each grab is delivered
-exactly once across calls. Add `--all` to replay the whole history from the start.
-
-## Gotchas
-
-- **Empty `read` output is not an error** — it just means no grab landed yet.
-  Re-run it; never treat empty output as the daemon being dead or the loop being
-  done. Only the user saying "stop" ends the loop.
-- **The daemon reads the clipboard on the machine it runs on.** Over SSH, in a
-  container, or on a cloud host while the browser is on the user's laptop, grabs
-  never arrive. The daemon must run on the same machine as the browser.
-- **Run one `read` at a time.** Concurrent reads share `cursor.txt` and can
-  double-deliver or skip grabs — keep the loop sequential.
-- **`read --all` replays the whole history without consuming it** — it does not
-  advance the cursor, so use it only to inspect history; the loop's plain `read`
-  is what delivers each grab exactly once.
-- **If grabs never arrive even though the user is grabbing**, the daemon may not
-  be staying up. A healthy daemon makes `npx grab@latest watch` report
-  `already watching`; if it keeps reporting `started`, the daemon is dying on
-  startup — usually no clipboard reader. Try `npx grab watch --text-only`, or run
-  `npx grab watch --foreground` once to see the startup error directly.
-
 ## Acting on a grab
 
 Each grab JSON has `content` (the element's source references) and, in prompt
@@ -76,15 +45,17 @@ mode, `prompt` (the user's typed instruction):
   loop, or, if there is none, triage it (summarize component + `file:line`) and
   wait for direction.
 
-A standing instruction is optional; prompt mode lets the user steer each grab
-inline.
-
 ## Stopping
 
-When the user says stop, stop the daemon and do not read again:
+When the user says stop, run this and don't pull again:
 
 ```bash
-npx grab@latest watch --stop
+npx grab stop
 ```
 
-Confirm the loop has stopped.
+## Notes
+
+- The watcher reads the clipboard on the machine it runs on — run it on the same
+  machine as the browser, not over SSH or in a remote container.
+- Grabs older than ~5 minutes are skipped as stale; use `npx grab pull --max-age 0`
+  to deliver every grab regardless of age.