{
  "markdown": "# SideButton\n\n**Open-source AI agent platform for agentic coding — MCP server, knowledge packs, and AI workflow automation.**\n\n[![npm](https://img.shields.io/npm/v/sidebutton)](https://www.npmjs.com/package/sidebutton)\n[![License](https://img.shields.io/badge/license-Apache--2.0%20%2B%20FSL--1.1-blue.svg)](LICENSING.md)\n\n> **[sidebutton.com](https://sidebutton.com)** · **[docs.sidebutton.com](https://docs.sidebutton.com)**\n\n<p align=\"center\">\n  <a href=\"https://sidebutton.com\">\n    <img src=\"https://sidebutton.com/media/sidebutton-oss-stack.png\" alt=\"SideButton open-source AI agent platform for agentic coding: MCP server, agentic workflows, knowledge packs\" width=\"700\" />\n  </a>\n</p>\n\nRun AI coding agents with agentic workflows, knowledge packs, and real browser control. Connect Claude Code, Codex, Cursor, ChatGPT, or any MCP client.\n\n```bash\nnpx sidebutton@latest\n# Dashboard at http://localhost:9876\n```\n\n## What you get\n\n| | |\n|---|---|\n| **MCP Server** | AI agent tools for browser control, workflow execution, and knowledge pack access. Stdio and SSE transports. |\n| **REST API** | Trigger workflows remotely from webhooks, cron jobs, mobile apps, or other agents. |\n| **Workflow Engine** | AI workflow automation with browser, git, issue-tracking, LLM, shell, and control-flow steps. Define agentic workflows in YAML. |\n| **Knowledge Packs** | Installable domain knowledge — CSS selectors, data models, state machines. Role playbooks turn coding agents into an AI software engineer, QA, or PM. |\n| **Chrome Extension** | Browser commands with real DOM access via WebSocket, not screenshots. Recording mode. |\n| **Dashboard** | Svelte UI — workflow browser, run logs, skill pack manager, system status. |\n\n## Quick Start\n\n```bash\n# Install and start\nnpx sidebutton@latest\n\n# Or from source\npnpm install && pnpm build && pnpm start\n\n# Open http://localhost:9876\n```\n\n### CLI\n\n```bash\npnpm cli serve          # Start server with dashboard\npnpm cli serve --stdio  # Start with stdio transport (for Claude Desktop)\npnpm cli list           # List available workflows\npnpm cli status         # Check server status\n\n# Skill pack management\npnpm cli registry add <path|url>   # Install skill packs from a registry\npnpm cli registry update [name]    # Update installed packs\npnpm cli registry remove <name>    # Uninstall packs and remove registry\npnpm cli search [query]            # Search available skill packs\n\n# Creating skill packs\npnpm cli init [domain]             # Scaffold a new skill pack\npnpm cli validate [path]           # Validate pack structure\npnpm cli publish [source]          # Publish to a registry\n```\n\n## MCP Server\n\nSideButton is an open-source [MCP server for AI coding agents](https://sidebutton.com/mcp). Agents connect to it directly for browser control, workflow automation, and domain knowledge.\n\nWorks with **Claude Code**, **Codex**, **Cursor**, **Claude Desktop**, **VS Code**, **Windsurf**, **ChatGPT** — any MCP client.\n\n### Claude Code\n\n```bash\nclaude mcp add sidebutton --transport http http://localhost:9876/mcp\n```\n\nPersists to `~/.claude.json`; add `--scope project` to write `./.mcp.json` instead. Full guide: [Claude Code SideButton MCP setup](https://sidebutton.com/mcp/claude-code).\n\n### Codex\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.sidebutton]\ncommand = \"sidebutton\"\nargs = [\"serve\", \"--stdio\"]\n```\n\nFull guide: [OpenAI Codex SideButton MCP setup](https://sidebutton.com/mcp/codex).\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sidebutton\": {\n      \"command\": \"npx\",\n      \"args\": [\"sidebutton\", \"--stdio\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sidebutton\": {\n      \"url\": \"http://localhost:9876/mcp\"\n    }\n  }\n}\n```\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `run_workflow` | Execute a workflow by ID |\n| `get_run_log` | Get execution log for a run |\n| `list_workflows` | List all available workflows |\n| `get_workflow` | Get workflow YAML definition |\n| `list_run_logs` | List recent workflow executions |\n| `publish_artifact` | Publish evidence (screenshots, reports) from a session |\n| `get_browser_status` | Check browser extension connection |\n| `capture_page` | Capture selectors from current page |\n| `navigate` | Navigate browser to URL |\n| `snapshot` | Get page accessibility snapshot |\n| `click` | Click an element |\n| `type` | Type text into an element |\n| `press_key` | Send keyboard keys |\n| `scroll` | Scroll the page |\n| `extract` | Extract text from element |\n| `screenshot` | Capture page screenshot (pass `path` to write a PNG file instead of returning image bytes) |\n| `select_option` | Select dropdown option |\n| `fill` | Fill input value (React-compatible) |\n| `wait` | Wait for element or delay |\n| `exists` | Check if element exists |\n| `extract_all` | Extract all matching elements |\n| `extract_map` | Extract structured data from repeated elements |\n| `scroll_into_view` | Scroll element into viewport |\n| `hover` | Hover over element |\n| `inject_css` | Inject CSS into the page (blur/hide elements before a screenshot) |\n| `evaluate` | Execute JavaScript in browser |\n| `browser_batch` | Run a sequence of browser actions in one call |\n| `set_basic_auth` | Set HTTP Basic Auth credentials for the connected tab |\n| `clear_basic_auth` | Clear stored HTTP Basic Auth credentials |\n\n## REST API\n\nJSON endpoints for external integrations. The same workflows are available via MCP locally and via REST remotely.\n\n```bash\n# Run a workflow\ncurl -X POST http://localhost:9876/api/workflows/check_ticket/run \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"params\": {\"ticket_id\": \"PROJ-123\"}}'\n\n# List workflows\ncurl http://localhost:9876/api/workflows\n\n# Get run log\ncurl http://localhost:9876/api/runs/latest\n```\n\nTrigger workflows from webhooks, cron jobs, mobile apps, or other agents on different machines.\n\n## Workflow Engine\n\nYAML-first orchestration for agentic workflows. Step types by family:\n\n### Step Types\n\n| Family | Steps |\n|------|-------|\n| `browser.*` | navigate, click, type, fill, extract, extractAll, extractMap, snapshot, screenshot, wait, exists, hover, key, scroll, scrollIntoView, select_option, injectCSS, injectJS |\n| `git.*` | createPR, getPR, listPRs, getIssue, listIssues |\n| `issues.*` | create, get, search, comment, attach, transition |\n| `llm.*` | classify, decide, generate |\n| `control.*` | if, foreach, retry, stop |\n| `shell` / `terminal` | shell.run, terminal.open, terminal.run |\n| `data.*` | first, get |\n| `workflow.call` | Call another workflow with parameters |\n\nLLM steps work with Ollama (local), OpenAI, and Anthropic.\n\n### Example\n\n```yaml\nid: check_ticket_status\ntitle: \"Check Jira ticket and classify\"\nsteps:\n  - type: browser.navigate\n    url: \"https://your-org.atlassian.net/browse/{{ticket_id}}\"\n  - type: browser.extract\n    selector: \"[data-testid='status-field']\"\n    as: current_status\n  - type: control.if\n    condition: \"{{current_status}} != 'Done'\"\n    then:\n      - type: llm.classify\n        prompt: \"Should this ticket be closed? Context: {{current_status}}\"\n        classes: [close, keep_open]\n        as: decision\n```\n\n### Variable Interpolation\n\nUse `{{variable}}` syntax to reference extracted values or parameters:\n\n```yaml\nsteps:\n  - type: browser.extract\n    selector: \".username\"\n    as: user\n  - type: shell.run\n    cmd: \"echo 'Hello, {{user}}!'\"\n```\n\n## Knowledge Packs\n\nInstallable domain knowledge (skill packs) per web app or domain. Knowledge packs power AI code review, automated testing, and enterprise AI agent deployments.\n\nAlso referred to as skill packs in code and CLI commands.\n\n- **Selectors** — CSS selectors for UI elements\n- **Data models** — entity types, fields, relationships, valid states\n- **State machines** — valid transitions per state\n- **Role playbooks** — role-specific procedures (QA, SE, PM, SD)\n- **Common tasks** — step-by-step procedures, gotchas, edge cases\n\n```bash\nsidebutton install github.com\nsidebutton install atlassian.net\n```\n\nOpen registry with published packs for popular web apps. Build and share packs for any domain.\n\n## Chrome Extension\n\nInstall the **[SideButton Chrome Extension](https://chromewebstore.google.com/detail/sidebutton/odaefhmdmgijnhdbkfagnlnmobphgkij)** from the Chrome Web Store.\n\n- Browser commands — navigate, click, type, extract, scroll, wait, snapshot\n- Real DOM access via CSS selectors — not pixel coordinates, not screenshots\n- Recording mode — capture manual actions as workflows\n- Embed buttons — inject action buttons into any web page\n- WebSocket connection — stable reconnection, works with local or remote server\n\nAfter installing:\n1. Navigate to any website\n2. Click the SideButton extension icon\n3. Click **\"Connect This Tab\"**\n\n## Dashboard & Observability\n\nSvelte UI at `http://localhost:9876`:\n\n- Workflow browser — list, search, run\n- Run logs — step-by-step execution traces with timing, variables, errors\n- Skill pack manager — install, browse, inspect\n- System status — extension connection, LLM config, server health\n\nSideButton handles multi-agent orchestration — from workflow execution to knowledge injection.\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────────────────┐\n│                          @sidebutton/server                               │\n│                                                                          │\n│  ┌─────────────────────┐   ┌──────────────────────────────────────────┐  │\n│  │  stdio Transport    │   │    Fastify HTTP + WebSocket (port 9876)  │  │\n│  │  ─────────────────  │   │    ────────────────────────────────────  │  │\n│  │  stdin → JSON-RPC   │   │  GET  /        → Dashboard (Svelte)      │  │\n│  │  stdout ← JSON-RPC  │   │  GET  /ws      → Chrome Extension WS     │  │\n│  │  (Claude Desktop)   │   │  POST /mcp     → MCP JSON-RPC (SSE)      │  │\n│  └──────────┬──────────┘   │  GET  /api/*   → REST API                │  │\n│             │              └──────────────────────┬───────────────────┘  │\n│             │                                     │                      │\n│             └──────────────────┬──────────────────┘                      │\n│                                ▼                                         │\n│  ┌────────────────────────────────────────────────────────────────────┐  │\n│  │                       @sidebutton/core                              │  │\n│  │                                                                     │  │\n│  │  - Workflow types & parser (YAML)                                  │  │\n│  │  - Step executors (YAML step types)                                │  │\n│  │  - Variable interpolation                                          │  │\n│  │  - Execution context & events                                      │  │\n│  └────────────────────────────────────────────────────────────────────┘  │\n└──────────────────────────────────────────────────────────────────────────┘\n      ▲                ▲                      ▲                      ▲\n      │ stdio          │ WebSocket            │ HTTP POST            │ REST\n      ▼                ▼                      ▼                      ▼\n┌──────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────┐\n│Claude Desktop│ │ Chrome Extension│ │   Claude Code   │ │   Mobile App      │\n│ (MCP stdio)  │ │ (Browser Auto)  │ │   (MCP SSE)     │ │   (REST Client)   │\n└──────────────┘ └─────────────────┘ └─────────────────┘ └───────────────────┘\n```\n\n### Project Structure\n\n```\nsidebutton/\n├── packages/\n│   ├── core/              # @sidebutton/core — workflow engine\n│   │   └── src/\n│   │       ├── types.ts       # Workflow types\n│   │       ├── parser.ts      # YAML loader\n│   │       ├── executor.ts    # Workflow runner\n│   │       └── steps/         # Step implementations\n│   ├── server/            # @sidebutton/server — MCP + HTTP + CLI\n│   │   ├── bin/               # CLI entry point\n│   │   └── src/\n│   │       ├── server.ts      # Fastify HTTP server\n│   │       ├── stdio-mode.ts  # stdio transport entry point\n│   │       ├── extension.ts   # WebSocket client\n│   │       ├── mcp/           # MCP handlers\n│   │       │   ├── handler.ts    # MCP JSON-RPC logic\n│   │       │   ├── stdio.ts      # stdio transport adapter\n│   │       │   └── tools.ts      # Tool definitions\n│   │       └── cli.ts         # Commander CLI\n│   └── dashboard/         # Svelte web UI\n│       └── src/\n│           ├── App.svelte\n│           └── lib/\n├── extension/             # Chrome extension\n├── workflows/             # Public workflow library\n├── actions/               # User-created workflows\n├── skills/                # Installed skill packs\n└── run_logs/              # Execution history\n```\n\n## Environment Variables\n\n| Variable | Required For | Description |\n|----------|--------------|-------------|\n| `OPENAI_API_KEY` | `llm.*` steps | OpenAI API key for LLM workflows |\n| `ANTHROPIC_API_KEY` | `llm.*` steps | Anthropic API key (alternative) |\n\n## Development\n\n```bash\npnpm install       # Install dependencies\npnpm build         # Build all packages\npnpm start         # Start server\npnpm cli list      # List workflows\npnpm cli status    # Check status\n```\n\n### Watch Mode\n\n```bash\npnpm dev              # Full dev mode (all packages)\npnpm dev:server       # Server with auto-restart on :9876\npnpm dev:dashboard    # Dashboard watch build\npnpm dev:core         # Core library watch build\n```\n\n## Platform Automation Disclaimer\n\nSideButton is a general-purpose browser automation framework. When automating third-party platforms:\n\n- **Review Terms of Service:** Many platforms prohibit or restrict automation. You are responsible for complying with the terms of any platform you automate.\n- **Account Risk:** Automation may result in account restrictions or suspension on some platforms.\n- **Use Responsibly:** Only automate actions you would perform manually. Respect rate limits and platform guidelines.\n\n**The authors do not endorse or encourage violations of third-party terms of service.**\n\n## License\n\nThis project uses mixed licensing — see [LICENSING.md](LICENSING.md):\n\n- **Engine, server, CLI, dashboard** — Apache-2.0\n- **Browser extension** — FSL-1.1-Apache-2.0 (converts to Apache-2.0 on 2029-03-15)\n",
  "bytes": 14333,
  "sha": "8a9830e91797fee89b3b02a22df42aa605cdda8775b320b41d4a048493fbcd19",
  "repo_slug": "sidebutton/sidebutton",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sidebutton_sidebutton_d6f3457d/readme"
}