Skip to main content
Glama

Sleeper

English · 简体中文 · 日本語 · Português · Español · Deutsch

Sleeper browser control for agents

Let your agent control the browser you already use, whether it’s on your desktop or Android phone. Sleeper connects Firefox or Chromium through MCP or CLI to navigate websites, read pages, fill forms, take screenshots, and extract structured data without copying session credentials into agent configuration.

Features · Install · Commands · Agent setup · Privacy · Security · Benchmarks · Contribute

Features

  • 📱 Firefox for Android (beta): Run Sleeper on Android through a private Tailscale Serve connection to your desktop daemon. No Caddy, router port, or public listener is required.

  • 🖥️ Firefox + Chromium desktop: Control pages in an existing browser session through the extension. Linux and macOS are supported; Windows is best-effort.

  • 🗂️ Profiles and tabs: Each browser installation has its own persistent ID. Agents discover connected browsers and target the intended tab.

  • 🎯 Element targeting: Find controls by CSS selector, accessible role and name, or a reference returned by snapshot.

  • 📝 Page interaction: Fill inputs, press keys, click controls, and wait for selectors or text before the next action.

  • 📋 Structured extraction: Read one element, collect matching elements, or extract a JSON map. Save repeatable work as recipes and schemas.

  • 📸 Screenshots: Capture the viewport or full page, with optional annotations. PNG output has a size limit; capture options explain it.

  • 🌐 Network and APIs: Inspect captured requests and call allowed HTTPS APIs with credentials kept in the browser and bound to their source host.

  • 🔒 Secret masking: Structured results receive best-effort redaction before reaching the CLI or MCP client. Screenshots can still contain private information.

  • 🔌 CLI and MCP: Run shell commands or call MCP tools through the local daemon.

  • 📖 Included skill: Give agents instructions for session selection, action verification, and connection recovery.

Related MCP server: browser-control

Install

Install uv first, then run from a checkout on Linux or macOS (the supported desktop platforms):

./install.sh

Windows works on a best-effort basis and is not a launch-supported platform; run in PowerShell:

py scripts/install.py

Choose Everything or Customize to select MCP, native agent plugins, and standalone instructions. The installer starts the daemon, installs the CLI, registers Firefox's extension-scoped native host for automatic XPI pairing, keeps Chromium's extension in a permanent folder, and copies browser packages to Downloads.

Firefox for Android connects through Tailscale Serve (beta). Run sleeper mobile setup, then open the QR code in Firefox; see the Android setup guide. The daemon remains loopback-only.

Troubleshooting

Toolbar icon opens a thin full-width strip instead of the popup — fixed by using a fixed popup width; rebuild and reinstall the extension package (see docs/commands.md for daemon environment configuration).

"no browser connected" / popup shows "Daemon disconnected" — check curl http://127.0.0.1:8790/health (daemon must be running), then run sleeper sessions (your browser should appear under profiles). For Firefox, rerun ./install.sh update if the native host was not registered; the fields under Advanced connection are manual recovery only. Extension origins are pinned to the first browser add-on that pairs with the daemon; restrict them further with SLEEPER_ALLOW_ANY_EXTENSION=false and SLEEPER_ALLOWED_EXTENSION_IDS=<uuid>,... in the daemon's startup service (systemd user unit on Linux, LaunchAgent on macOS — see docs/commands.md).

Run sleeper --version for the installed CLI version. sleeper sessions reports daemon, protocol, and connected add-on versions; an incompatible or older add-on is marked in its browser record.

Codex and Claude Code

The main installer can register Sleeper's native plugin when you choose Everything or Customize. For manual setup, install the Sleeper runtime first, then run the commands for your agent from the repository root.

Codex

codex plugin marketplace add .
codex plugin add sleeper --marketplace sleeper-local

Claude Code

claude plugin marketplace add . --scope user
claude plugin install sleeper@sleeper --scope user
# Codex
codex plugin marketplace add https://github.com/shy-tangerine/Sleeper.git
codex plugin add sleeper --marketplace sleeper-local

# Claude Code
claude plugin marketplace add https://github.com/shy-tangerine/Sleeper.git --scope user
claude plugin install sleeper@sleeper --scope user

Restart the agent after installation so it loads the bundled skill and MCP server. See agent setup for public-GitHub installation, verification, updates, and removal commands.

Browser

Finish installation

Chromium

Open the extensions page, enable Developer mode, choose Load unpacked, and select the folder printed by the installer.

Firefox

Install the signed sleeper-firefox.xpi release asset through Add-ons → Install Add-on From File. Signed releases are pending Mozilla signing credentials.

Browser permission approval is required once. Installation, updates, and removal.

Prefer manual client setup? Use the verified Codex and Claude Code plugin commands.

curl -fsSL https://raw.githubusercontent.com/shy-tangerine/Sleeper/main/install.sh | bash

Inspect the open tabs and current page:

sleeper tabs
sleeper snapshot
sleeper type --role textbox --name Search 'your query' --clear
sleeper press Enter

While an agent is working, Sleeper can show a small on-page activity message such as “Opening a page…”, “Clicked an element”, or “Timed out waiting for the page.” These messages use plain language rather than CLI/MCP command names. Typed values, uploaded file contents, and other sensitive action values are not shown. Visible activity can be turned off in the extension settings; the toolbar still exposes connection and access state.

The included agent skill covers session selection, action verification, and connection recovery. Agents can use MCP tools directly; the command guide covers tab targets, extraction, recipes, and API calls.

Waiting

Working

Benchmarks

Five verified runs per interface, on one machine. Each sequence navigates, reads a heading, types, clicks, waits for text, and reads the result.

Tested on Linux with Helium 0.17.0.1 (Chromium 153.0.8010.36). Every interface used the same browser build and a fresh profile.

Percentages use the rounded medians below.

Interface

Median sequence

Median browser RSS

Task-text tokens

Protocol-text tokens

Sleeper CLI

934 ms

1,139 MiB

441

409 (HTTP JSON)

Sleeper MCP

281 ms

1,127 MiB

502

695 (JSON-RPC)

OpenCLI

4,011 ms

1,218 MiB

364

29,152 (HTTP JSON)

Playwright MCP

1,635 ms

1,027 MiB

536

734 (JSON-RPC)

Direct CDP

291 ms

1,038 MiB

Not applicable

956 (CDP)

Task-text tokens estimate agent-facing input and output with o200k_base. Protocol tokens count internal HTTP JSON, JSON-RPC, or CDP traffic; they are not model usage. Direct CDP has no agent-facing task-text interface.

Browser RSS sums browser process memory, can double-count shared pages, and excludes daemons. Timing and protocol captures use separate runs. These results come from one machine, one browser build, and one run date (2026-09-11) measuring deterministic browser primitives, not agent task completion or general speed; see the canonical methodology caveats, which must accompany these figures wherever they are quoted. Raw samples, methodology, discovery costs, and feature comparison.

Browser

Version

Result

Firefox

155.0.1

Passed

Chrome

151.0.7922.47

Passed

Zen

1.22b

Passed

Helium

0.17.0.1 (Chromium 153.0.8010.36)

Passed

The Chrome check used Google Chrome for Testing, the automation distribution of Chrome. Its exact version is shown above.

Contribute

Build and test · Changelog · Third-party notices · Privacy · Security · MIT license · Sponsorship

Directory

Contents

extension/

Browser manifests, page handlers, popup, icons

daemon/

HTTP/WebSocket relay and MCP server

cli/

CLI, recipes, adapter support

plugins/codex/sleeper/skills/

Agent instructions

examples/

Recipes and extraction schemas

test/

Behavioral, transport, and package checks

Star history

View the star-history chart

Python package build (PyPI)

The browser extension release workflow is separate from Python packaging. Python package metadata is in pyproject.toml; uv.lock governs development. Run uv lock --check, uv sync --locked, and uv build to produce an sdist and wheel in dist/. After the owner approves a release and PyPI credentials/trusted publishing are configured, uv publish can upload those artifacts. Do not treat building as release authorization.

Available Tools

49 tools
sleeper_apiC

Call page backend API with captured auth token (background fetch)

Inputs: url (required), body, method, profile.

sleeper_backD

History back

Inputs: tab, profile.

sleeper_batchB

Run ordered browser actions in one request; stops at the first failure by default

Inputs: actions (required), profile, stop_on_error.

sleeper_checkC

Check checkbox

Inputs: selector (required), tab, profile.

sleeper_clickC

Click element by CSS selector (supports :has-text)

Inputs: selector (required), tab, profile.

sleeper_click_allC

Click every matching element

Inputs: selector (required), tab, profile.

sleeper_click_textC

Click element by text

Inputs: text (required), tab, exact, index, +2 more.

sleeper_consoleD

Page console capture

Inputs: tab, limit, profile.

sleeper_dblclickC

Double-click element

Inputs: selector (required), tab, profile.

sleeper_dialogC

Install auto accept/dismiss dialog hook

Inputs: profile.

sleeper_dragC

Drag source to target

Inputs: source (required), target (required), tab, profile.

sleeper_execC

Execute arbitrary JS in Chromium; unavailable in signed Firefox builds

Inputs: code (required), tab, profile.

sleeper_extractD

Extract selector->text map

Inputs: map (required), tab, profile.

sleeper_fill_formC

Fill form by name/id/placeholder (JSON map)

Inputs: fields (required), tab, profile.

sleeper_findC

Inspect elements by CSS selector

Inputs: selector (required), tab, profile.

sleeper_find_textC

Find element by innerText

Inputs: text (required), tab, exact, profile.

sleeper_focusD

Focus element

Inputs: selector (required), tab, profile.

sleeper_formsC

Enumerate form inputs

Inputs: tab, profile, selector.

sleeper_framesC

List cross-origin iframes

Inputs: profile.

sleeper_getC

Get page/element properties

Inputs: tab, profile, selector.

sleeper_gotoC

Navigate to URL

Inputs: url (required), tab, profile.

sleeper_hoverD

Mouseover element

Inputs: selector (required), tab, profile.

sleeper_keysC

Dispatch key events on active element

Inputs: keys (required), tab, profile.

sleeper_mediaC

Per-tab media request log

Inputs: tab, clear, since, profile.

sleeper_networkD

Per-tab request log or fetch

Inputs: tab, url, body, clear, +5 more.

sleeper_newtabC

Open new tab via extension API

Inputs: url (required), profile.

sleeper_pressC

Keyboard events on element/active

Inputs: key (required), tab, profile, selector.

sleeper_readC

Read single element (text/html/value/attr)

Inputs: selector (required), tab, attr, what, +1 more.

sleeper_read_allC

Read all matching elements

Inputs: selector (required), tab, attr, what, +1 more.

sleeper_screenshotC

Alias for shot — viewport PNG screenshot

Inputs: tab, profile.

sleeper_scrollC

Scroll by pixels or to selector

Inputs: y, tab, profile, selector.

sleeper_scroll_untilC

Scroll until text/selector appears

Inputs: tab, text, profile, selector, +2 more.

sleeper_selectC

Set select value + change event

Inputs: value (required), selector (required), tab, profile.

sleeper_sessionsB

List connected stable browser installation IDs for routing

Inputs: profile.

sleeper_shotC

Viewport PNG screenshot (data URL)

Inputs: tab, profile.

sleeper_snapshotC

Headings/inputs/buttons/links summary

Inputs: tab, profile.

sleeper_stateB

Get page state for the selected Sleeper profile (url, title, focus, visibility)

Inputs: profile.

sleeper_submitC

Submit form

Inputs: tab, profile, selector.

sleeper_tabsB

List tabs in the selected Sleeper browser profile

Inputs: profile.

sleeper_typeC

Type into input (React-compatible events)

Inputs: text (required), selector (required), tab, clear, +2 more.

sleeper_uncheckC

Uncheck checkbox

Inputs: selector (required), tab, profile.

sleeper_uploadB

Upload explicit base64 file contents to an input; native paths are unsupported. Total JSON request limit: 1 MiB.

Inputs: files (required), selector (required), tab, profile.

sleeper_waitD

Wait for selector

Inputs: selector (required), tab, profile, timeout.

sleeper_wait_dialogD

Wait for dialog

Inputs: tab, text, profile, timeout_ms.

sleeper_wait_downloadC

Wait for a download matching a URL/filename pattern to finish

Inputs: pattern (required), tab, profile, timeout_ms.

sleeper_wait_textD

Wait for text

Inputs: text (required), tab, exact, profile, +1 more.

sleeper_wait_untilC

Wait for a structured page condition; JavaScript predicates are Chromium-only

Inputs: tab, profile, timeout, interval, +2 more.

sleeper_wait_urlC

Wait until URL contains pattern

Inputs: pattern (required), tab, profile, timeout_ms.

sleeper_wait_xhrC

Wait for XHR matching URL substring

Inputs: url_substring (required), tab, method, profile, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.4/5.0

    Scored across 49 tools

    Disambiguation3/5

    Descriptions generally clarify boundaries, but several clusters overlap heavily: element reading (get, find, find_text, read, read_all, extract) and clicking (click, click_text, click_all) require careful reading to pick correctly, and shot/screenshot are literal aliases. press vs keys vs type also border on each other.

    Naming Consistency4/5

    Nearly all tools follow a consistent sleeper_ prefix with lowercase snake_case verb or verb_noun names (goto, click_text, wait_url), which is highly predictable. Minor deviations like the shot/screenshot alias and single-word verbs slightly break the pattern.

    Tool Count2/5

    49 tools is well above a comfortable range for a single server and includes redundant entries (shot/screenshot alias, multiple near-duplicate click/read/find variants). The surface could be consolidated substantially without losing capability.

    Completeness4/5

    Coverage of browser automation is broad: navigation, interaction, waiting, forms, uploads, dialogs, tabs, frames, network/console capture, and screenshots. Only some gaps remain (e.g. cookie/storage management), but core workflows are fully supported.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to control the user's Chrome or Firefox browser, leveraging existing sessions for tasks requiring authentication and user handoff.
      18
      47 npm
      21
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables AI agents to control existing Chrome and Firefox browser sessions locally, including tab management, navigation, form filling, screenshots, and persistent scripts, without remote relays or debugging ports.
      36
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any coding agent to use the user's existing Chrome profiles and logins to open tabs, read pages, fill forms, click through flows, and take screenshots.
      81 npm
      MIT