Puppet is the programmable browser runtime for AI agents.

It allows your AI assistant to write browser automation once and reuse it as tools. These tools run inside a secure browser sandbox and can be called through the Model Context Protocol (MCP).

Instead of repeatedly generating fragile browser scripts during conversations, agents install persistent automation tools that reliably perform web tasks.

Puppet runs locally on your machine and works with assistants such as Claude Desktop, Cursor, and other MCP-compatible clients.

With Puppet, AI agents can:

interact with real websites
understand pages using compressed DOM representations
automate browser workflows
extract structured data
reuse automation tools across tasks

The result is fewer tokens, faster reasoning, and more reliable browser automation.

Core Concepts

Puppet is built around three core ideas. Understanding these concepts will help you understand how AI agents automate the web.

Programmable Browser

Puppet turns the browser into a programmable environment for AI agents. Agents can control a real browser to:

navigate websites
click buttons and links
fill forms
scroll pages
extract information

This allows AI assistants to interact with the web exactly as a user would. Unlike traditional scraping tools, Puppet works with dynamic websites and modern web apps.

Agent Page Understanding

Web pages are complex. A typical page contains thousands of DOM nodes, scripts, and styling information that are irrelevant for automation. Puppet helps AI agents understand pages efficiently.

DOM Compression

Puppet provides DOM compression for agents. Instead of exposing the full DOM tree, Puppet generates a compressed representation of the page that keeps only useful information.

The compressed representation preserves:

page structure
visible text
layout relationships
interactive elements

Unnecessary information is removed, including:

styling
scripts
deeply nested markup
irrelevant attributes

This dramatically reduces token usage while preserving the information agents need.

Interactive Elements

The compressed page representation highlights elements that agents can interact with, including:

buttons
links
form inputs
navigation controls

This makes it easier for agents to decide what actions they can perform on a page.

Faster Reasoning

Because the page representation is smaller and cleaner, agents can:

understand pages faster
identify target elements more reliably
generate more accurate browser actions

This leads to more reliable automation.

Reusable Automation Tools

Puppet allows agents to convert browser scripts into reusable tools. Instead of generating automation logic every time, the assistant installs a tool once and calls it whenever needed.

Example tools might:

scrape product listings
export dashboard reports
submit forms
monitor page changes

Reusable tools reduce token usage and make automation consistent across tasks.

How Puppet Works

The typical workflow looks like this:

AI Assistant
      ↓
Installs Browser Tool
      ↓
Puppet Browser Runtime
      ↓
Real Website

The assistant writes a tool for a browser task
The tool is installed into Puppet
The assistant calls the tool when needed

This architecture makes browser automation predictable and repeatable.

Quick Start

Getting started takes only a few minutes.

Step 1 — Install Puppet

Download the desktop application for your platform.

Download Puppet

Step 2 — Connect Your Assistant

Puppet communicates with AI assistants through Model Context Protocol (MCP). Add the Puppet MCP server to your assistant configuration.

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "puppet": {
      "command": "PASTE_COMMAND_PATH"
    }
  }
}

Once connected, your assistant can install and run Puppet tools.

Step 3 — Create Your First Tool

Ask your assistant to create a browser automation tool.

Example prompt:

Using Puppet, create a tool that opens a webpage and returns the page title.

Your assistant will:

generate the tool
install it
execute it through MCP

After installation, the tool becomes reusable.

Tool Capabilities

Puppet tools allow AI agents to automate complex browser tasks.

Real Browser Automation

Tools can interact with websites using a real browser environment. Agents can:

navigate pages
click buttons
fill forms
scroll and wait for dynamic content
extract page data

This works even on modern JavaScript-heavy websites.

Structured Data Extraction

Tools can return structured outputs such as:

tables
metadata
product information
extracted content

Structured results allow assistants to reason about data more effectively.

File Processing

Tools can process uploaded files such as:

PDFs
images
documents

This allows workflows that combine web interaction and document analysis.

Safety Model

Puppet is designed so AI-generated tools can run safely on your computer.

Local Execution

All automation runs locally on your machine. Scripts are never executed on remote servers.

Browser Sandbox Isolation

Tools run inside an isolated browser sandbox. Scripts cannot access:

local files
system resources
other applications

This keeps your system protected while allowing agents to automate the web.

Permission-Based Access

Each tool declares the capabilities it requires. Examples include:

network access
allowed websites
downloads

Tools cannot access resources unless they are explicitly allowed.

Execution Guardrails

Puppet includes safeguards to ensure predictable behavior:

execution time limits
resource limits
domain allowlists
controlled downloads
task history

These guardrails make it safe to run automation tools created by AI assistants.

Automation & Scheduling

Puppet supports scheduled automation. Tools can run automatically using cron schedules.

Common use cases include:

daily reports
website monitoring
periodic data collection
automated workflows

Example schedules:

0 9 * * * → every morning at 9:00
0 0 * * 0 → every Sunday

MCP Integration

Puppet exposes all installed tools through Model Context Protocol (MCP). This allows assistants to:

list available tools
install new tools
execute tools
retrieve results
cancel running tasks

Puppet works with any MCP-compatible client. Examples include:

Claude Desktop
Cursor
custom agent frameworks

Support & Resources

Website: pptr.app
Email: support@pptr.app
Issues: Report bugs or request features via the application's feedback menu.