periscope

io.github.oskar-szulcv0.2.1Updated Sep 30, 2026

A real Safari-engine (WebKit) browser for agents on macOS: sessions, extraction, bot checks.

VerifiedSTDIODesktop onlyBrowser Automation

Installation

In SourceWeft

  1. Open periscope in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

periscope

A command-line browser for AI agents on macOS. It runs Safari's engine (WebKit), so websites see a normal Safari, and it keeps sessions open between commands.

bash
periscope navigate https://books.toscrape.com/ --session demoperiscope text --session demo        # the page as markdownperiscope extract --session demo     # the page's records as JSONperiscope click "text:Next" --session demo

Install

bash
brew install oskar-szulc/tap/periscopeperiscope install-skill    # adds the agent skill to this project

Without Homebrew: curl -fsSL https://raw.githubusercontent.com/oskar-szulc/periscope/main/install.sh | sh

To build from source instead (Xcode 26): swift build -c release, then copy .build/release/periscope onto your PATH.

For agents

  • Claude Desktop: download periscope-<version>.mcpb from the latest release and open it
  • Claude Code: /plugin marketplace add oskar-szulc/periscope, then /plugin install periscope@periscope
  • Codex, Cursor and others: npx skills add oskar-szulc/periscope
  • MCP clients: listed in the MCP Registry as io.github.oskar-szulc/periscope; the command is periscope mcp, e.g. claude mcp add periscope -- periscope mcp, or in a JSON config: {"mcpServers": {"periscope": {"command": "periscope", "args": ["mcp"]}}}
  • Any agent with a shell: periscope docs prints the full reference

Reading a page

CommandReturnsUse it to
textThe page's main content as markdown, links includedRead an article or a post
stateURL, title, headings, the start of the content, and every clickable element with a selector and a number (@3)Decide what to click or fill next
extractJSON: the page's repeated items (cards, results, table rows), its structured data, and the next-page linkScrape a list of jobs, products or results
linksEvery link on the page as an absolute URL (--match to filter)Collect URLs to visit next
screenshotA PNG of the page as displayedSee the layout, or check visual content

What else you can do

  • Act: click, fill, type, select, scroll, mouse, targeting CSS or what a person sees (text:Next, label:Email)
  • Stay logged in: named sessions persist; login and show let you take over the window
  • Know when you're blocked: CAPTCHA and bot-check pages exit with code 5

Full reference: PERISCOPE.md.

Requirements

  • macOS 26 or newer, in a logged-in desktop session with the display on
  • Not inside a shell sandbox (periscope exits with a message if it is)

License

MIT. Contributions: see CONTRIBUTING.md.

Source: README.md at commit 33ef42d

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.1LatestSep 30, 2026