Contributing

Guide to build PinchTab from source and contribute to the project.

System Requirements

Minimum Requirements

Requirement	Version	Purpose
Go	1.25+	Build language
Chrome/Chromium	Latest	Browser automation
macOS, Linux, or WSL2	Current	OS support

Recommended Setup

macOS: Homebrew for package management
Linux: apt (Debian/Ubuntu) or yum (RHEL/CentOS)
WSL2: Full Linux environment (not WSL1)

Part 1: Prerequisites

Install Go

macOS (Homebrew):

bash terminal

brew install gogo version  # Verify: go version go1.25.0

Linux (Ubuntu/Debian):

bash terminal

sudo apt updatesudo apt install -y golang-go git build-essentialgo version

Linux (RHEL/CentOS):

bash terminal

sudo yum install -y golang gitgo version

Install Chrome/Chromium

macOS (Homebrew):

bash terminal

brew install chromium

Linux (Ubuntu/Debian):

bash terminal

sudo apt install -y chromium-browser

Linux (RHEL/CentOS):

bash terminal

sudo yum install -y chromium

Verify Installations

bash terminal

go version       # go version go1.25.0 darwin/arm64git --version    # git version 2.39.0chromium --version  # Chromium 120.0.6099.xx

Install Dependencies

Clone the repository and download Go modules:

bash terminal

git clone https://github.com/pinchtab/pinchtab.gitcd pinchtabgo mod download

Verify:

bash terminal

go mod verify    # Verifies all checksumsgo list -m all   # List all dependencies

Part 2: Build the Project

Simple Build

bash terminal

go build -o pinchtab ./cmd/pinchtab

What it does:

Compiles Go source code
Produces binary: ./pinchtab
Takes ~30-60 seconds

Verify:

bash terminal

ls -la pinchtab./pinchtab --version

Part 3: Run the Server

Start (Headless)

bash terminal

./pinchtab

Expected output:

🦀 PINCH! PINCH! port=9867
auth disabled (set BRIDGE_TOKEN to enable)

Start (Headed Mode)

bash terminal

BRIDGE_HEADLESS=false ./pinchtab

Opens Chrome in the foreground.

Background

bash terminal

nohup ./pinchtab > pinchtab.log 2>&1 &tail -f pinchtab.log  # Watch logs

Part 4: Quick Test

Health Check

bash terminal

curl http://localhost:9867/health

Try CLI

bash terminal

./pinchtab quick https://example.com./pinchtab nav https://github.com./pinchtab snap

Development

Run Tests

bash terminal

go test ./... -vgo test ./... -v -coverprofile=coverage.outgo tool cover -html=coverage.out  # View coverage

Code Quality

bash terminal

gofmt -w .              # Format codegolangci-lint run ./... # Lint (install if needed)./scripts/check.sh      # Run all checks

Pre-Commit Hook

bash terminal

./scripts/setup-hooks.sh

Automatically runs checks before committing.

Development Workflow

bash terminal

# 1. Create feature branchgit checkout -b feat/my-feature# 2. Make changes# ... edit files ...# 3. Testgo test ./... -v# 4. Format & lintgofmt -w .golangci-lint run ./...# 5. Commitgit add .git commit -m "feat: description"# 6. Pushgit push origin feat/my-feature# 7. Create PR on GitHub

Continuous Integration

GitHub Actions automatically runs on push:

Format checks (gofmt)
Vet checks (go vet)
Build verification
Full test suite with coverage
Linting (golangci-lint)

See .github/workflows/ for details.

Installation as CLI

From Source

bash terminal

go build -o ~/go/bin/pinchtab ./cmd/pinchtab

Then use anywhere:

bash terminal

pinchtab helppinchtab --version

Via npm (released builds)

bash terminal

npm install -g pinchtabpinchtab --version

Resources

GitHub Repository: https://github.com/pinchtab/pinchtab
Go Documentation: https://golang.org/doc/
Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/
Chromedp Library: https://github.com/chromedp/chromedp

Support

Issues? Check:

All dependencies installed?
Go and Chrome versions correct?
Port 9867 available?
Check logs: tail -f pinchtab.log

See docs/ for guides and examples.