WebPilot

Self-contained browser agent: OODA loop (observe → orient → decide → act) → Playwright spec.

No FastAPI or database. LLM profiles live in llms.json, agent settings in webpilot.yaml. The interactive shell is OpenTUI. Headless run is for CI.

The loop matches the WebPilot design in test-agent-nexus (backend/docs/WEBPILOT_FLOW.md): DOM observe with shadow roots, viewport JPEG, one JSON action per step, then click / type / select / navigate. See docs/ARCHITECTURE.md and HOW_TO_USE.md.

Install

OpenTUI needs Bun 1.3+. Node cannot load the native renderer.

The CLI is published on npm as @capagents/webpilot (the unscoped name is too close to an existing package). PyPI package webpilot-cli is a pip launcher for the same webpilot command (webpilot is already another project on PyPI).

curl -fsSL https://bun.sh/install | bash

# npm
npm install -g @capagents/webpilot
npx @capagents/webpilot --help

# pip (launcher; runs the npm package via bun)
pip install webpilot-cli
webpilot --help

Live browser profiles also need Chromium: bunx playwright install chromium. The mock profile does not.

From this repo:

cd WebPilot
bun install
bun src/index.ts init
bun src/index.ts start

One-shot release (same version on both registries; assumes npm and twine are already logged in):

./scripts/publish.sh           # current version
./scripts/publish.sh 0.2.0     # bump + publish
./scripts/publish.sh --dry-run # pack only

npm is published first. The pip launcher runs bun x @capagents/webpilot@<version>.

Configure

init writes:

File	Purpose
`webpilot.yaml`	Browser, prompts, export, active profile
`llms.json`	Named LLM profiles
`.env.example`	API key names

webpilot models
webpilot run --goal "Read the homepage" --url https://example.com --profile mock --plain

mock uses a synthetic page, writes workflow.yaml and webpilot.spec.ts, and does not call a model. Switch llm.active to azure-gpt4o or openai-gpt4o for a real browser run.

CLI

webpilot start
webpilot start -u https://example.com -g "Find the documentation link" -p openai-gpt4o

webpilot run --goal "Get a quote" --url https://example.com --profile azure-gpt4o --headed
webpilot run --goal "..." --url https://example.com --profile mock --plain --out ./out/demo

Inside the shell: /url, /goal, /run, /stop, /headed, /steps, /profile, /export, /exit. A line without a slash sets the goal and starts when a URL is known.

Metadata

Release files for webpilot-cli 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for webpilot-cli 0.1.1
File	Size	Uploaded
webpilot_cli-0.1.1.tar.gz	3.7 kB	Sep 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for webpilot-cli 0.1.1
File	Interpreter	ABI	Platform	Reset
webpilot_cli-0.1.1-py3-none-any.whl 4.2 kB Sep 28, 2026	Python 3	none	any	Details

Total release size: 7.9 kB

Release files / webpilot_cli-0.1.1.tar.gz

Download URL	webpilot_cli-0.1.1.tar.gz
Size	3.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`ff16e9aa930f6b985ed66d52f15be7c87c3bdbb86de2fa8d23fbd9243c5e4cf9`
BLAKE2b-256 checksum How to use checksums	`43cd38f5c35e0af7ecc4922da6a66e50abed61f5e0fe9db4d77913b87b726d1f`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.13`

Release files / webpilot_cli-0.1.1-py3-none-any.whl

Download URL	webpilot_cli-0.1.1-py3-none-any.whl
Size	4.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`29d266dce37d1b5544f0ec61b9a428a42c78690de1c44863f8944dac21955297`
BLAKE2b-256 checksum How to use checksums	`652843e5f21729275b49f7ad2189fcde62ba470f8dc0dc95fb27aee46e85712d`
Upload date	Sep 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.13`