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
periscope extract --session demo
periscope click "text:Next" --session demo
Install
brew install oskar-szulc/tap/periscope
periscope install-skill
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
| Command | Returns | Use it to |
|---|
text | The page's main content as markdown, links included | Read an article or a post |
state | URL, 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 |
extract | JSON: the page's repeated items (cards, results, table rows), its structured data, and the next-page link | Scrape a list of jobs, products or results |
links | Every link on the page as an absolute URL (--match to filter) | Collect URLs to visit next |
screenshot | A PNG of the page as displayed | See 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.