High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Pinchtab npm
Browser control API for AI agents — Node.js SDK + CLI wrapper.
Installation
npm install pinchtab
or globally:
npm install -g pinchtab
On install, the postinstall script automatically:
- Detects your OS and CPU architecture (darwin/linux/windows, amd64/arm64)
- Downloads the precompiled Pinchtab binary from GitHub Releases
- Example:
pinchtab-darwin-amd64,pinchtab-windows-arm64.exe(Windows)
- Example:
- Verifies integrity (SHA256 checksum from
checksums.txt) - Stores it inside the installed package at
.managed-bin/<version>/(version-specific to avoid conflicts) - Makes it executable
The binary lives inside the package directory rather than under $HOME, so a
global install resolves the same binary no matter which user runs the CLI —
including sudo npm install -g pinchtab, where postinstall runs as root but the
CLI later runs as you. (Binaries placed by older versions under ~/.pinchtab/bin
are still honored.)
Requirements:
- Internet connection on first install (to download binary from GitHub Releases)
- Node.js 16+
- macOS, Linux, or Windows
Local Development With A Local Binary
If you are testing the npm package from a local checkout, build the canonical repo-local binary first:
bash scripts/npm-dev-binary.sh
cd npm
npm install
node bin/pinchtab --version
In a source checkout, the npm package now expects the local binary at
../pinchtab-dev and will fail clearly if it is missing. It does not download a
release binary in that mode.
Restricted Networks and Mirrors
npm install --https-proxy https://proxy.company.com:8080 pinchtab (or the
HTTPS_PROXY environment variable) routes npm's own registry fetches through a
proxy. The postinstall binary download from GitHub Releases goes direct, however,
and does not read HTTP(S)_PROXY.
For proxied, mirrored, or air-gapped installs, point the binary download at a host
you control with PINCHTAB_DOWNLOAD_BASE_URL. It must mirror the GitHub Releases
layout — <base>/v<version>/<asset> — serving each platform binary alongside
checksums.txt:
export PINCHTAB_DOWNLOAD_BASE_URL=https://mirror.example.com/pinchtab
npm install -g pinchtab
Quick Start
Start the server
pinchtab serve --port 9867
Use the SDK
import Pinchtab from 'pinchtab';
const pinch = new Pinchtab({ port: 9867 });
// Start the server
await pinch.start();
// Take a snapshot
const snapshot = await pinch.snapshot({ refs: 'role' });
console.log(snapshot.html);
// Click on an element
await pinch.click({ ref: 'e42' });
// Lock a tab
await pinch.lock({ tabId: 'tab1', timeoutMs: 5000 });
// Stop the server
await pinch.stop();
API
new Pinchtab(options)
Create a Pinchtab client.
Options:
baseUrl(string): API base URL. Default:http://localhost:9867timeout(number): Request timeout in ms. Default:30000port(number): Port to run on. Default:9867
start(binaryPath?)
Start the Pinchtab server process.
stop()
Stop the Pinchtab server process.
snapshot(params?)
Take a snapshot of the current tab.
Params:
refs('role' | 'aria'): Reference systemselector(string): CSS selector filtermaxTokens(number): Token limitformat('full' | 'compact'): Response format
click(params)
Click on an element.
Params:
ref(string): Element referencetargetId(string): Optional target tab ID
lock(params) / unlock(params)
Lock/unlock a tab.
createTab(params)
Create a new tab.
Params:
url(string): Tab URLstealth('light' | 'full'): Stealth level
CLI
pinchtab serve [--port PORT]
pinchtab --version
pinchtab --help
Agent skill
The package bundles the pinchtab agent skill, stamped with the release version and a content hash, and syncs it into detected agent homes on install and upgrade, printing what it wrote. pinchtab skill status reports each copy against the bundled one (exit 1 if any is stale) and pinchtab skill update refreshes them; a copy you edited is kept unless you pass --force.
Shell Completion
After installing the CLI globally, you can generate shell completions:
# Generate and install zsh completions
pinchtab completion zsh > "${fpath[1]}/_pinchtab"
# Generate bash completions
pinchtab completion bash > /etc/bash_completion.d/pinchtab
# Generate fish completions
pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
Using a Custom Binary
For development or custom integrations, pass the path explicitly in code:
const pinch = new Pinchtab();
const binaryPath = '/custom/path/to/pinchtab';
await pinch.start(binaryPath);
Troubleshooting
Binary not found or "file not found" error:
Check if the release has binaries:
# Should show pinchtab-darwin-arm64, pinchtab-linux-x64, etc.
curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/latest | jq '.assets[].name'
If no binaries (only Docker images), rebuild with a newer release:
npm rebuild pinchtab
Restricted network or mirror:
The binary download does not use HTTP(S)_PROXY. Point it at a reachable mirror
(GitHub Releases layout) and rebuild:
export PINCHTAB_DOWNLOAD_BASE_URL=https://mirror.example.com/pinchtab
npm rebuild pinchtab
Future: OptionalDependencies Pattern (v1.0)
In a future major version, we plan to migrate to the modern optionalDependencies pattern used by esbuild, Biome, Turbo, etc. This will split platform-specific binaries into separate npm packages (@pinchtab/cli-darwin-arm64, etc.) for zero postinstall network overhead and perfect offline support.
License
MIT