SideButton

Local workflow automation for your browser, terminal, and AI.

Website · Documentation · GitHub

Define workflows in YAML and execute them through browser automation, shell commands, and LLM integration.

Who is this for?

• Power users who repeat the same browser tasks daily (data entry, form filling, content publishing)
• Developers who want to automate workflows without writing code
• AI agent builders who need browser automation via MCP
• Teams who want shareable, version-controlled automation

Why SideButton?

Quick Start

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start the server
pnpm start

# Open http://localhost:9876 in your browser

Or run directly with the CLI:

pnpm cli serve      # Start server with dashboard
pnpm cli list       # List available workflows
pnpm cli status     # Check server status

Features

• Config-first workflows - Define actions in YAML files
• Browser automation - Navigate, click, type, scroll, extract via Chrome extension
• Shell execution - Run bash commands with output capture
• Terminal workflows - Execute commands in visible terminal windows (macOS)
• LLM integration - Text classification and generation via OpenAI/Anthropic
• Control flow - Conditionals, retries, and nested workflows
• Recording mode - Capture user actions to generate selectors
• MCP Server - Expose workflows to AI agents
• REST API - JSON endpoints for mobile and external integrations

Creating Workflows

Workflows are defined as YAML files in the workflows/ directory.

Basic Structure

id: hello_world
title: "Hello World"
steps:
  - type: shell.run
    cmd: "echo 'Hello from SideButton!'"

Step Types

Variable Interpolation

Use {{variable}} syntax to reference extracted values or parameters:

steps:
  - type: browser.extract
    selector: ".username"
    as: user

  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     @sidebutton/server                          │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │          Fastify HTTP + WebSocket Server (port 9876)     │  │
│  │                                                          │  │
│  │  GET  /            → Dashboard (Svelte)                  │  │
│  │  GET  /ws          → Chrome Extension WebSocket          │  │
│  │  POST /mcp         → MCP JSON-RPC (AI Agents)            │  │
│  │  GET  /api/*       → REST API                            │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                 @sidebutton/core                           │  │
│  │                                                           │  │
│  │  - Workflow types & parser (YAML)                        │  │
│  │  - Step executors (20 step types)                        │  │
│  │  - Variable interpolation                                │  │
│  │  - Execution context & events                            │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
         ▲                       ▲                       ▲
         │ WebSocket             │ HTTP POST             │ REST
         ▼                       ▼                       ▼
┌─────────────────┐   ┌─────────────────┐   ┌───────────────────┐
│ Chrome Extension│   │   Claude Code   │   │   Mobile App      │
│ (Browser Auto)  │   │   (MCP Client)  │   │   (REST Client)   │
└─────────────────┘   └─────────────────┘   └───────────────────┘

Project Structure

sidebutton/
├── packages/
│   ├── core/              # @sidebutton/core
│   │   └── src/
│   │       ├── types.ts       # Workflow types
│   │       ├── parser.ts      # YAML loader
│   │       ├── executor.ts    # Workflow runner
│   │       └── steps/         # Step implementations
│   ├── server/            # @sidebutton/server
│   │   ├── bin/               # CLI entry point
│   │   └── src/
│   │       ├── server.ts      # Fastify HTTP server
│   │       ├── extension.ts   # WebSocket client
│   │       ├── mcp/           # MCP handler
│   │       └── cli.ts         # Commander CLI
│   └── dashboard/         # Svelte web UI
│       └── src/
│           ├── App.svelte
│           └── lib/
├── extension/             # Chrome extension
├── workflows/             # Public workflow library
├── actions/               # User-created workflows
└── run_logs/              # Execution history

Browser Extension Setup

1. Open Chrome and go to chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked
4. Select the extension/ folder
5. Navigate to a website and click the extension icon
6. Click "Connect This Tab"

MCP Server (AI Agent Integration)

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "sidebutton": {
      "type": "sse",
      "url": "http://localhost:9876/mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sidebutton": {
      "url": "http://localhost:9876/mcp"
    }
  }
}

Available MCP Tools

Environment Variables

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Start server locally
pnpm start

# CLI commands
pnpm cli list          # List workflows
pnpm cli status        # Check status
pnpm cli serve         # Start server

Watch Mode

# Full dev mode (all packages with hot reload)
pnpm dev

# Individual components
pnpm dev:server        # Server with auto-restart on :9876
pnpm dev:dashboard     # Dashboard with HMR on :5173
pnpm dev:core          # Core library watch build

In dev mode:

• Dashboard runs at http://localhost:5173 with Vite HMR
• Server auto-restarts on code changes via tsx watch
• API proxy forwards /api/* and /ws/* from dashboard to server

Platform Automation Disclaimer

SideButton is a general-purpose browser automation framework. When automating third-party platforms:

• Review Terms of Service: Many platforms prohibit or restrict automation. You are responsible for complying with the terms of any platform you automate.
• Account Risk: Automation may result in account restrictions or suspension on some platforms.
• Use Responsibly: Only automate actions you would perform manually. Respect rate limits and platform guidelines.

The authors do not endorse or encourage violations of third-party terms of service.

Legal

• Terms of Service
• Privacy Policy

License

Apache-2.0