Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: brew and testing skill flags

Luigi Agostif36b8e38bca0
diff --git a/.github/workflows/publish-skill.yml b/.github/workflows/publish-skill.yml
index 9d7550b5..fd44814c 100644
--- a/.github/workflows/publish-skill.yml
+++ b/.github/workflows/publish-skill.yml
@@ -1,8 +1,14 @@
name: Publish Skill
on:
- push:
- tags: ['v*']
+ workflow_call:
+ inputs:
+ version:
+ required: true
+ type: string
+ secrets:
+ CLAWHUB_TOKEN:
+ required: true
workflow_dispatch:
inputs:
version:
@@ -36,11 +42,14 @@ jobs:
- name: Publish skill
run: |
- if [ -n "${{ github.event.inputs.version }}" ]; then
+ if [ -n "${{ inputs.version }}" ]; then
+ VERSION="${{ inputs.version }}"
+ elif [ -n "${{ github.event.inputs.version }}" ]; then
VERSION="${{ github.event.inputs.version }}"
else
VERSION=${GITHUB_REF_NAME#v}
fi
+ VERSION=${VERSION#v}
clawhub publish skills/pinchtab \
--slug pinchtab \
--name "Pinchtab" \
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 04e2a95b..f7679ea9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -224,3 +224,15 @@ jobs:
pinchtab/pinchtab:latest
pinchtab/pinchtab:${{ steps.meta.outputs.tag }}
pinchtab/pinchtab:${{ steps.meta.outputs.version }}
+
+ skill:
+ name: Publish Skill
+ needs:
+ - npm
+ - docker
+ if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
+ uses: ./.github/workflows/publish-skill.yml
+ with:
+ version: ${{ github.event.inputs.tag || github.ref_name }}
+ secrets:
+ CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
diff --git a/.goreleaser.yml b/.goreleaser.yml
index 9a6ec714..8df1bd1e 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -45,7 +45,7 @@ brews:
test: |
system "#{bin}/pinchtab version"
install: |
- bin.install "pinchtab"
+ bin.install Dir["pinchtab*"].first => "pinchtab"
changelog:
sort: asc
diff --git a/RELEASE.md b/RELEASE.md
index 11b88b36..1ab2368a 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -165,6 +165,11 @@ Depends on: `release` job (waits for goreleaser to finish)
GitHub Actions builds the release image directly from the tagged source with `docker buildx`.
The workflow pushes the same multi-arch build to both GHCR and Docker Hub, so Docker no longer depends on GoReleaser's temporary build context.
+### 4. ClawHub skill
+
+The main `Release` workflow publishes the Pinchtab skill to ClawHub only after both npm and Docker complete successfully.
+The standalone `Publish Skill` workflow is manual-only and is intended for retries or one-off recovery publishes.
+
## Troubleshooting
### npm publish fails (403)
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 5c6c46a4..92aa3860 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -13,6 +13,15 @@ Preferred tool surface:
- Use `curl` for profile-management routes or non-shell/API fallback flows.
- Use `jq` only when you need structured parsing from JSON responses.
+## Safety Defaults
+
+- Default to `http://localhost` targets. Only use a remote PinchTab server when the user explicitly provides it and, if needed, a token.
+- Prefer read-only operations first: `text`, `snap -i -c`, `snap -d`, `find`, `click`, `fill`, `type`, `press`, `select`, `hover`, `scroll`.
+- Do not evaluate arbitrary JavaScript unless a simpler PinchTab command cannot answer the question.
+- Do not upload local files unless the user explicitly names the file to upload and the destination flow requires it.
+- Do not save screenshots, PDFs, or downloads to arbitrary paths. Use a user-specified path or a safe temporary/workspace path.
+- Never use PinchTab to inspect unrelated local files, browser secrets, stored credentials, or system configuration outside the task.
+
## Core Workflow
Every PinchTab automation follows this pattern:
@@ -206,16 +215,29 @@ Rules:
```bash
pinchtab screenshot
-pinchtab screenshot -o page.jpg
+pinchtab screenshot -o /tmp/pinchtab-page.jpg
pinchtab screenshot -q 60
pinchtab pdf
-pinchtab pdf -o report.pdf
+pinchtab pdf -o /tmp/pinchtab-report.pdf
pinchtab pdf --landscape
-pinchtab eval <expression>
-pinchtab download <url> -o out.bin
-pinchtab upload <file> -s <css>
```
+### Advanced operations: explicit opt-in only
+
+Use these only when the task explicitly requires them and safer commands are insufficient.
+
+```bash
+pinchtab eval "document.title"
+pinchtab download <url> -o /tmp/pinchtab-download.bin
+pinchtab upload /absolute/path/provided-by-user.ext -s <css>
+```
+
+Rules:
+
+- `eval` is for narrow, read-only DOM inspection unless the user explicitly asks for a page mutation.
+- `download` should prefer a safe temporary or workspace path over an arbitrary filesystem location.
+- `upload` requires a file path the user explicitly provided or clearly approved for the task.
+
### HTTP API fallback
```bash
@@ -299,7 +321,7 @@ Then point each command stream at its own `PINCHTAB_URL`.
- Use a dedicated automation profile, not a daily browsing profile.
- If PinchTab is reachable off-machine, require a token and bind conservatively.
-- Prefer `text`, `snap -i -c`, and `snap -d` before screenshots.
+- Prefer `text`, `snap -i -c`, and `snap -d` before screenshots, PDFs, eval, downloads, or uploads.
- Use `--block-images` for read-heavy tasks that do not need visual assets.
- Stop or isolate instances when switching between unrelated accounts or environments.
diff --git a/skills/pinchtab/TRUST.md b/skills/pinchtab/TRUST.md
index 8a5933e5..aa0dfd87 100644
--- a/skills/pinchtab/TRUST.md
+++ b/skills/pinchtab/TRUST.md
@@ -9,6 +9,8 @@
- Extracts the page's accessibility tree (for AI agents)
- Runs screenshots, PDFs, and JavaScript evaluation
+High-risk operations such as JavaScript evaluation, local-file upload, and direct file writes should be treated as explicit opt-in actions for the current task, not the default workflow.
+
**All of this stays local.** No telemetry. No external API calls (except to sites you navigate to).
## What Pinchtab Does NOT Do
diff --git a/skills/pinchtab/references/api.md b/skills/pinchtab/references/api.md
index d7b1d56a..37ed434b 100644
--- a/skills/pinchtab/references/api.md
+++ b/skills/pinchtab/references/api.md
@@ -137,6 +137,9 @@ Returns `{url, title, text}`. Cheapest option (~1K tokens for most pages).
## PDF export
+Prefer returning base64 or raw bytes unless the user explicitly wants a file written to disk.
+When writing to disk, use a safe temporary or workspace path.
+
```bash
# CLI: pinchtab pdf --tab TAB_ID [-o file.pdf] [--landscape] [--scale 0.8]
# Returns base64 JSON
@@ -145,8 +148,8 @@ curl "/tabs/TAB_ID/pdf"
# Raw PDF bytes
curl "/tabs/TAB_ID/pdf?raw=true" -o page.pdf
-# Save to disk
-curl "/tabs/TAB_ID/pdf?output=file&path=/tmp/page.pdf"
+# Save to disk in a safe temp location
+curl "/tabs/TAB_ID/pdf?output=file&path=/tmp/pinchtab-page.pdf"
# Landscape with custom scale
curl "/tabs/TAB_ID/pdf?landscape=true&scale=0.8&raw=true" -o page.pdf
@@ -187,13 +190,15 @@ curl "/tabs/TAB_ID/pdf?preferCSSPageSize=true&raw=true" -o css-sized.pdf
| `generateTaggedPDF` | bool | false | Generate accessible/tagged PDF |
| `generateDocumentOutline` | bool | false | Embed document outline |
| `output` | string | JSON | `file` to save to disk, default returns base64 |
-| `path` | string | auto | Custom file path (with `output=file`) |
+| `path` | string | auto | Destination path (prefer temp or workspace paths with `output=file`) |
| `raw` | bool | false | Return raw PDF bytes instead of JSON |
Wraps `Page.printToPDF`. Prints background graphics by default.
## Download files
+Prefer raw bytes or base64 responses unless the user explicitly asks for a saved file.
+
```bash
# Returns base64 JSON by default (uses browser session/cookies/stealth)
curl "/download?url=https://site.com/report.pdf"
@@ -201,16 +206,18 @@ curl "/download?url=https://site.com/report.pdf"
# Raw bytes (pipe to file)
curl "/download?url=https://site.com/image.jpg&raw=true" -o image.jpg
-# Save directly to disk
-curl "/download?url=https://site.com/export.csv&output=file&path=/tmp/export.csv"
+# Save directly to disk in a safe temp location
+curl "/download?url=https://site.com/export.csv&output=file&path=/tmp/pinchtab-export.csv"
```
## Upload files
+Only upload local files the user explicitly provided or approved for the task.
+
```bash
# Upload a local file to a file input
curl -X POST "/upload?tabId=TAB_ID" -H "Content-Type: application/json" \
- -d '{"selector": "input[type=file]", "paths": ["/tmp/photo.jpg"]}'
+ -d '{"selector": "input[type=file]", "paths": ["/tmp/user-approved-photo.jpg"]}'
# Upload base64-encoded data
curl -X POST /upload -H "Content-Type: application/json" \
@@ -229,6 +236,9 @@ curl "/screenshot?raw=true&quality=50" -o screenshot.jpg
## Evaluate JavaScript
+Use this sparingly. Prefer `text`, `snapshot`, and normal actions first.
+Default to read-only DOM inspection and avoid reading cookies, localStorage, or unrelated page secrets unless the user explicitly asks for that behavior.
+
```bash
# CLI: pinchtab eval "document.title"
curl -X POST /evaluate -H 'Content-Type: application/json' \