Build from Source

Build PinchTab from source code using Go

Build PinchTab from source for development, custom modifications, or platforms without prebuilt binaries.

Prerequisites

System Requirements

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

Recommended Setup

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

Installation Steps

1. Install Go

   macOS

   brew install go
   go version  # Verify: go1.25.0 or higher
   

   Ubuntu/Debian

   sudo apt update
   sudo apt install -y golang-go git build-essential
   go version
   

   RHEL/CentOS

   sudo yum install -y golang git
   go version
   
2. Install Chrome/Chromium

   macOS

   brew install chromium
   

   Ubuntu/Debian

   sudo apt install -y chromium-browser
   

   RHEL/CentOS

   sudo yum install -y chromium
   
3. Clone the repository

   git clone https://github.com/pinchtab/pinchtab.git
   cd pinchtab
   
4. Download dependencies

   go mod download
   go mod verify  # Verify checksums
   
5. Build the binary

   go build -o pinchtab ./cmd/pinchtab
   

   This creates the pinchtab binary in the current directory.

6. Verify the build

   ./pinchtab --version
   

Build Process

Simple Build

The basic build command:

go build -o pinchtab ./cmd/pinchtab

What it does:

• Compiles all Go source code
• Links dependencies from go.mod
• Produces executable binary: ./pinchtab
• Takes approximately 30-60 seconds

Optimized Build (Smaller Binary)

For production or distribution, build with optimization flags:

go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab

Flags:

• -s: Omit symbol table
• -w: Omit DWARF debugging information
• Result: Smaller binary size (~12MB)

Cross-Compilation

Build for different platforms:

macOS (Apple Silicon)

GOOS=darwin GOARCH=arm64 go build -o pinchtab-darwin-arm64 ./cmd/pinchtab

Dependencies

From go.mod:

module github.com/pinchtab/pinchtab

go 1.25.0

require (
    github.com/chromedp/cdproto v0.0.0-20250803210736-d308e07a266d
    github.com/chromedp/chromedp v0.14.2
    github.com/gobwas/ws v1.4.0
    gopkg.in/yaml.v3 v3.0.1
)

Key libraries:

• chromedp: Chrome DevTools Protocol implementation
• cdproto: CDP protocol definitions
• gobwas/ws: WebSocket client
• yaml.v3: YAML configuration parsing

Running the Server

Start in Headless Mode

./pinchtab

Expected output:

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

Start in Headed Mode

See the browser window:

BRIDGE_HEADLESS=false ./pinchtab

Run in Background

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

Test the Server

curl http://localhost:9867/health

Installing as System Binary

Install to Go’s bin directory for global access:

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

Ensure ~/go/bin is in your PATH:

export PATH=$PATH:~/go/bin
# Add to ~/.bashrc or ~/.zshrc to persist

Now use pinchtab from anywhere:

pinchtab --version
pinchtab serve

Development Workflow

Setup Pre-commit Hooks

PinchTab uses pre-commit hooks for code quality:

# Install pre-commit (one-time)
pip install pre-commit
# or: brew install pre-commit

# Setup hooks in this repo
pre-commit install

# Optional: Run on all files to verify
pre-commit run --all-files

Code Formatting

Format code before committing:

# Format all Go code
gofmt -w .

# Or use the script
./scripts/format.sh

Running Tests

All Tests

go test ./...

Code Quality Checks

# Run linter
golangci-lint run ./...

# Run all pre-commit checks manually
pre-commit run --all-files

# Check dependencies
go mod verify
go list -m all

Git Workflow for Contributors

1. Create feature branch

   git checkout -b feature/your-feature
   
2. Make changes

   Edit source files in your preferred editor.

3. Format and test

   ./scripts/format.sh
   go test ./...
   
4. Commit changes

   git add .
   git commit -m "feat: description"
   # Pre-commit hooks run automatically
   
5. Push to GitHub

   git push origin feature/your-feature
   
6. Create Pull Request

   Open a PR on GitHub from your branch.

Continuous Integration

GitHub Actions automatically runs on every push:

• Format checks: gofmt
• Vet checks: go vet
• Build verification: Ensures code compiles
• Test suite: Full test coverage
• Linting: golangci-lint

See .github/workflows/ for CI configuration.

Troubleshooting

”go: command not found”

Solution: Install Go or add it to PATH:

export PATH=$PATH:/usr/local/go/bin
# Add to ~/.bashrc or ~/.zshrc

“Chrome not found” at runtime

Solution: Install Chromium or specify custom path:

CHROME_BIN=/path/to/chrome ./pinchtab

Build errors with dependencies

Solution: Clean and re-download modules:

go clean -modcache
go mod download
go mod verify

“gofmt: command not found”

Solution: gofmt comes with Go. Ensure Go is properly installed:

go version
which gofmt

Tests failing

Solution: Run tests with verbose output to see details:

go test -v ./...

Check that Chrome is installed and accessible.

Port 9867 already in use

Solution: Change the port:

BRIDGE_PORT=9868 ./pinchtab

Or find and kill the process using 9867:

lsof -i :9867
kill -9 <PID>

Useful Commands

# List all Go dependencies
go list -m all

# Update dependencies
go get -u ./...

# Clean build artifacts
go clean

# View build cache
go clean -cache -n

# List test functions
go test -list .

# Check for outdated modules
go list -u -m all

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

Next Steps

Development Guide

Learn about PinchTab’s architecture

Contributing

Contribute to the project

Quick Start

Test your build with examples

API Reference

Explore the HTTP API