sidebutton

# SideButton

**Open-source AI agent platform — MCP server, knowledge packs, and workflow automation tools.**

[![License](https://img.shields.io/badge/license-Apache--2.0%20%2B%20FSL--1.1-blue.svg)](LICENSING.md)
[![Website](https://img.shields.io/badge/website-sidebutton.com-purple)](https://sidebutton.com)
[![Docs](https://img.shields.io/badge/docs-docs.sidebutton.com-green)](https://docs.sidebutton.com)

> **[Website](https://sidebutton.com)** · **[Documentation](https://docs.sidebutton.com)** · **[GitHub](https://github.com/sidebutton/sidebutton)**

<p align="center">
  <a href="https://sidebutton.com/media/sidebutton-open-source-platform-release">
    <img src="https://sidebutton.com/media/sidebutton-agent-stack.png" alt="The AI Agent Stack — SideButton" width="700" />
  </a>
</p>

AI agent platform with 40+ AI agent tools. Run autonomous AI agents with agentic workflows, knowledge packs, and real browser control. Connect Claude Code, Cursor, ChatGPT, or any MCP client.

```bash
npx sidebutton@latest
# Dashboard at http://localhost:9876
```

## What you get

| | |
|---|---|
| **MCP Server** | 40+ AI agent tools for browser control, workflow execution, knowledge pack access. Stdio and SSE transports. |
| **REST API** | 60+ endpoints. Trigger workflows remotely from webhooks, cron jobs, mobile apps, or other agents. |
| **Workflow Engine** | AI workflow automation with 34+ step types — browser, shell, LLM, control flow. Define agentic workflows in YAML. |
| **Knowledge Packs** | Installable domain knowledge — CSS selectors, data models, state machines. Role playbooks turn coding agents into an AI software engineer, QA, or PM. |
| **Chrome Extension** | 40+ browser commands. Real DOM access via WebSocket, not screenshots. Recording mode. |
| **Dashboard** | Svelte UI — workflow browser, run logs, skill pack manager, system status. |

## Quick Start

```bash
# Install and start
npx sidebutton@latest

# Or from source
pnpm install && pnpm build && pnpm start

# Open http://localhost:9876
```

### CLI

```bash
pnpm cli serve          # Start server with dashboard
pnpm cli serve --stdio  # Start with stdio transport (for Claude Desktop)
pnpm cli list           # List available workflows
pnpm cli status         # Check server status

# Skill pack management
pnpm cli registry add <path|url>   # Install skill packs from a registry
pnpm cli registry update [name]    # Update installed packs
pnpm cli registry remove <name>    # Uninstall packs and remove registry
pnpm cli search [query]            # Search available skill packs

# Creating skill packs
pnpm cli init [domain]             # Scaffold a new skill pack
pnpm cli validate [path]           # Validate pack structure
pnpm cli publish [source]          # Publish to a registry
```

## MCP Server

SideButton is an AI agent platform and MCP server. AI coding agents connect to it directly for browser control, workflow automation, and domain knowledge.

Works with **Claude Code**, **Cursor**, **Claude Desktop**, **VS Code**, **Windsurf**, **ChatGPT** — any MCP client.

### Claude Code

Add to `~/.claude/settings.json`:

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

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sidebutton": {
      "command": "npx",
      "args": ["sidebutton", "--stdio"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

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

### MCP Tools

| Tool | Description |
|------|-------------|
| `run_workflow` | Execute a workflow by ID |
| `list_workflows` | List all available workflows |
| `get_workflow` | Get workflow YAML definition |
| `get_run_log` | Get execution log for a run |
| `list_run_logs` | List recent workflow executions |
| `get_browser_status` | Check browser extension connection |
| `capture_page` | Capture selectors from current page |
| `navigate` | Navigate browser to URL |
| `snapshot` | Get page accessibility snapshot |
| `click` | Click an element |
| `type` | Type text into an element |
| `scroll` | Scroll the page |
| `screenshot` | Capture page screenshot |
| `hover` | Hover over element |
| `extract` | Extract text from element |
| `extract_all` | Extract all matching elements |
| `extract_map` | Extract structured data from repeated elements |
| `select_option` | Select dropdown option |
| `fill` | Fill input value (React-compatible) |
| `press_key` | Send keyboard keys |
| `scroll_into_view` | Scroll element into viewport |
| `evaluate` | Execute JavaScript in browser |
| `exists` | Check if element exists |
| `wait` | Wait for element or delay |
| `check_writing_quality` | Evaluate text quality |

## REST API

60+ JSON endpoints for external integrations. Same workflows available via MCP locally and via REST remotely.

```bash
# Run a workflow
curl -X POST http://localhost:9876/api/workflows/check_ticket/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"ticket_id": "PROJ-123"}}'

# List workflows
curl http://localhost:9876/api/workflows

# Get run log
curl http://localhost:9876/api/runs/latest
```

Trigger workflows from webhooks, cron jobs, mobile apps, or other agents on different machines.

## Workflow Engine

YAML-first orchestration. 34+ step types:

### Step Types

| Type | Description |
|------|-------------|
| **Browser** | |
| `browser.navigate` | Open a URL |
| `browser.click` | Click an element by selector |
| `browser.type` | Type text into an element |
| `browser.fill` | Fill input value (React-compatible) |
| `browser.scroll` | Scroll the page |
| `browser.extract` | Extract text from element into variable |
| `browser.extractAll` | Extract all matching elements |
| `browser.extractMap` | Extract structured data from repeated elements |
| `browser.wait` | Wait for element or fixed delay |
| `browser.exists` | Check if element exists |
| `browser.hover` | Position cursor on element |
| `browser.key` | Send keyboard keys |
| `browser.snapshot` | Capture accessibility snapshot |
| `browser.injectCSS` | Inject CSS styles into page |
| `browser.injectJS` | Execute JavaScript in page |
| `browser.select_option` | Select dropdown option |
| `browser.scrollIntoView` | Scroll element into view |
| **Shell** | |
| `shell.run` | Execute a bash command |
| `terminal.open` | Open a visible terminal window (macOS) |
| `terminal.run` | Run command in terminal window |
| **LLM** | |
| `llm.classify` | Structured classification with categories |
| `llm.generate` | Free-form text generation |
| **Control Flow** | |
| `control.if` | Conditional branching |
| `control.retry` | Retry with backoff |
| `control.stop` | End workflow with message |
| `workflow.call` | Call another workflow with parameters |
| **Data** | |
| `data.first` | Extract first item from list |

LLM steps work with Ollama (local), OpenAI, Anthropic, and Google.

### Example

```yaml
id: check_ticket_status
title: "Check Jira ticket and classify"
steps:
  - type: browser.navigate
    url: "https://your-org.atlassian.net/browse/{{ticket_id}}"
  - type: browser.extract
    selector: "[data-testid='status-field']"
    as: current_status
  - type: control.if
    condition: "{{current_status}} != 'Done'"
    then:
      - type: llm.classify
        prompt: "Should this ticket be closed? Context: {{current_status}}"
        classes: [close, keep_open]
        as: decision
```

### Variable Interpolation

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

```yaml
steps:
  - type: browser.extract
    selector: ".username"
    as: user
  - type: shell.run
    cmd: "echo 'Hello, {{user}}!'"
```

## Knowledge Packs

Installable domain knowledge (skill packs) per web app or domain. Knowledge packs power AI code review, automated testing, and enterprise AI agent deployments.

Also referred to as skill packs in code and CLI commands.

- **Selectors** — CSS selectors for UI elements
- **Data models** — entity types, fields, relationships, valid states
- **State machines** — valid transitions per state
- **Role playbooks** — role-specific procedures (QA, SE, PM, SD)
- **Common tasks** — step-by-step procedures, gotchas, edge cases

```bash
sidebutton install github.com
sidebutton install atlassian.net
```

11 domains, 28+ modules published. Open registry — build and share packs for any web app.

## Chrome Extension

Install from the **[Chrome Web Store](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)**.

- 40+ browser commands — navigate, click, type, extract, scroll, wait, snapshot
- Real DOM access via CSS selectors — not pixel coordinates, not screenshots
- Recording mode — capture manual actions as workflows
- Embed buttons — inject action buttons into any web page
- WebSocket connection — stable reconnection, works with local or remote server

After installing:
1. Navigate to any website
2. Click the SideButton extension icon
3. Click **"Connect This Tab"**

## Dashboard & Observability

Svelte UI at `http://localhost:9876`:

- Workflow browser — list, search, run
- Run logs — step-by-step execution traces with timing, variables, errors
- Skill pack manager — install, browse, inspect
- System status — extension connection, LLM config, server health

SideButton handles AI agent orchestration — from workflow execution to knowledge injection.

## Architecture

```
┌──────────────────────────────────────────────────────────────────────────┐
│                          @sidebutton/server                               │
│                                                                          │
│  ┌─────────────────────┐   ┌──────────────────────────────────────────┐  │
│  │  stdio Transport    │   │    Fastify HTTP + WebSocket (port 9876)  │  │
│  │  ─────────────────  │   │    ────────────────────────────────────  │  │
│  │  stdin → JSON