periscope

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.

periscope navigate https://books.toscrape.com/ --session demo

periscope text --session demo # the page as markdown periscope extract --session demo # the page's records as JSON periscope click "text:Next" --session demo

Install

brew install oskar-szulc/tap/periscope

periscope 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- .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

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. Why and how it was built: Building periscope.

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. Made by Oskar Szulc.