Metadata-Version: 2.4
Name: agentweb-cli
Version: 0.33.1
Summary: Turn websites into fast, structured commands for coding agents
Author: AgentWeb contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/AnayGarodia/agentweb
Project-URL: Documentation, https://github.com/AnayGarodia/agentweb#readme
Project-URL: Issues, https://github.com/AnayGarodia/agentweb/issues
Keywords: agents,cli,web,automation,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: websocket-client>=1.8
Provides-Extra: impersonate
Requires-Dist: curl-cffi>=0.15; extra == "impersonate"
Provides-Extra: registry
Requires-Dist: cryptography>=45; extra == "registry"
Provides-Extra: all
Requires-Dist: curl-cffi>=0.15; extra == "all"
Requires-Dist: cryptography>=45; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: curl-cffi>=0.15; extra == "dev"
Requires-Dist: cryptography>=45; extra == "dev"
Requires-Dist: pytest>=9; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AnayGarodia/agentweb/main/docs/assets/logo-dark.svg">
    <img alt="AgentWeb" width="340" src="https://raw.githubusercontent.com/AnayGarodia/agentweb/main/docs/assets/logo-light.svg">
  </picture>
</p>

<p align="center">
  <b>A browserless web interface for coding agents — typed commands in, JSON out.</b>
</p>

<p align="center">
  <a href="https://github.com/AnayGarodia/agentweb/blob/main/docs/README.md">Docs</a> &nbsp;·&nbsp;
  <a href="https://github.com/AnayGarodia/agentweb/blob/main/docs/SITES.md">Supported sites</a> &nbsp;·&nbsp;
  <a href="https://github.com/AnayGarodia/agentweb/blob/main/docs/BUILDING_ADAPTERS.md">Build an adapter</a> &nbsp;·&nbsp;
  <a href="https://github.com/AnayGarodia/agentweb/blob/main/SECURITY.md">Security</a>
</p>

<p align="center">
  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
  <a href="https://github.com/AnayGarodia/agentweb/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/AnayGarodia/agentweb/actions/workflows/ci.yml/badge.svg"></a>
</p>

<p align="center">
  <img alt="A terminal recording: asking for React's weekly npm downloads returns structured JSON, and a wrong argument returns an error naming the offending field." width="800" src="https://raw.githubusercontent.com/AnayGarodia/agentweb/main/docs/assets/demo.gif">
</p>

<p align="center">
  <i>Both commands are real, keyless and read-only. The recording is scripted,
  not narrated: <a href="https://github.com/AnayGarodia/agentweb/blob/main/docs/assets/demo.tape">docs/assets/demo.tape</a>
  regenerates it with <code>vhs docs/assets/demo.tape</code>.</i>
</p>

---

## What it is

A website is compiled **once** into a typed, versioned adapter. After that,
agents replay its mapped operations as ordinary HTTP requests that return
bounded structured JSON. The browser is an authoring and login surface, not the
ordinary execution engine.

That moves finding controls, filling forms and interpreting results from every
agent run to one shared adapter. It also makes the limitations explicit:
AgentWeb only works on sites and operations someone has mapped, and a typed
operation is not automatically proof that the whole user task works.

## Install

### macOS and Linux

If Python 3.11 or newer is not already available, the installer provisions an
isolated Python for you.

```bash
curl -fsSL https://github.com/AnayGarodia/agentweb/releases/latest/download/install.sh | sh
```

Restart Claude Code or Codex, then paste this prompt:

```text
Use AgentWeb to find the latest version of React on npm.
```

Everything lands under `~/.local/share/agentweb`, plus a global AgentWeb skill
for Claude Code and Codex holding the CLI's absolute path — so new agent
sessions find it even when the app does not inherit `~/.local/bin`. It does not
change your system Python packages and does not register MCP automatically.

Prefer to read scripts before running them? [Read `install.sh`](install.sh), or
install from a checkout with `git clone`, `python3 -m pip install -e .`, and
`agentweb setup`. Already installed? `agentweb upgrade` re-runs the official
installer after checksum-verifying it, preserving your sessions and profiles;
`agentweb upgrade --check` only reports installed vs. latest.

### Windows

Run the signed release-channel PowerShell installer:

```powershell
irm https://github.com/AnayGarodia/agentweb/releases/latest/download/install.ps1 | iex
```

A one-line PowerShell installer, the counterpart of `install.sh`, is built from
[`installer/install.ps1.template`](installer/install.ps1.template) and published
with the same immutable release. Read it before you trust it: **it has not been
run on a real Windows machine.** Its argument handling, wheel verification,
Python discovery and every failure message are covered by tests that execute it
under `pwsh` on Linux and macOS, which catches the class of bug that broke it
once already — but that is not a verified Windows install, and we will not claim
it is until someone runs it on Windows.
[Reports welcome.](https://github.com/AnayGarodia/agentweb/issues)

There is no PyPI release yet, so `pip install agentweb-cli` does not work on any
platform. The release installer above is the current answer.

## Just ask for what you want

Prompts are ordinary tasks. The agent handles discovery and command syntax.

```text
Use AgentWeb to find three recent arXiv papers about coding agents.
Use AgentWeb to compare the dependencies of React and Vue on npm.
Use AgentWeb to research Alan Turing on Wikipedia and follow the most relevant links.
```

If the installer could not detect your coding agent, connect it by hand with
`agentweb install-agent claude --scope user` or
`agentweb install-agent codex --scope user`. See
[agent setup](docs/AGENT_HOSTS.md) for the exact behaviour hosts should follow
around login, retries, and writes.

## What the agent runs underneath

```bash
agentweb sites                                            # what is installed
agentweb capabilities arxiv.org                           # what one site supports
agentweb describe arxiv.org --operation search_papers     # one operation's contract
agentweb arxiv.org search-papers --query "attention" --limit 3
```

**Reads** look things up. **Acts** do things on your own accounts — play a song,
add to a cart, open a pull request — and impactful or irreversible ones require
an explicit `--confirm`. Actions are the point: reads are often a web search
away, but *doing* things is what a browserless interface uniquely unlocks.
Commands accept plain domains and most website URLs, and a command's main
argument works positionally or as a flag, so copy-pasted examples work either
way. Results and expected errors are JSON, so agents need no site-specific
parsing code.

## Why not Playwright MCP?

Microsoft's own Playwright MCP README makes the general case for the CLI shape:

> Modern **coding agents** increasingly favor CLI–based workflows exposed as
> SKILLs over MCP because CLI invocations are more token-efficient: they avoid
> loading large tool schemas and verbose accessibility trees into the model
> context, allowing agents to act through concise, purpose-built commands.
>
> — [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp#playwright-mcp-vs-playwright-cli)

AgentWeb pushes that one step further: the mapping is done ahead of time and
versioned, so the agent never reasons about page structure at all. Browser
automation is still the right tool for a site nobody has mapped and for
exploratory work — and AgentWeb ships `agentweb mcp` if you would rather drive
it through MCP anyway.

The MCP surface is five tools and stays constant as adapters are added:
`site_find`, `sites_list`, `site_describe`, `site_call`, and `site_connect`.
The CLI remains the lower-context path.

## What has actually been measured

In the current live task-completion run, AgentWeb completed **10/10 multi-step
read tasks it attempted**; a stepwise local Chrome completed **4/10**. That is a
completion result, not a speed or cost win. Both arms followed fixed shortest
paths with no model in the loop. This page makes no speed or cost claim.

**Writes were 0/0.** No authenticated write ran in this benchmark, so it is not
evidence that carts, playlists, votes, or issues work end to end. Two separate
signed-out refusal checks are reported separately and are not counted as
completed actions. [Method, task table, and limitations](docs/BENCHMARKS.md).

## Supported sites

<!-- BEGIN GENERATED SITE SUMMARY -->

**30 sites, 364 mapped operations in the signed offline CLI bundle**, with signed adapter updates available from the hosted registry. On the product denominator — reviewed meaningful user tasks — **0 of 30 currently earn the Verified tier**. Operation evidence and route coverage are reported separately. See [all sites and operations](docs/SITES.md), or run `agentweb sites` for what is installed locally.

Before signed sync, the bundled non-mapping runtime exposes 483 operations after shared fallbacks. Live `agentweb sites` is dynamic and can report more after a signed hosted adapter upgrade.

<!-- END GENERATED SITE SUMMARY -->

## Honest coverage

Adapters state only what they have actually proven. Every operation carries a
status computed from bundled evidence rather than asserted by a maintainer:
**verified** (a live replay whose content was checked against reviewed
assertions), **shape-verified** (a live replay that matched the reviewed
schema), or **unverified** (mapped and typed, but with no machine-checked
evidence bundled). Adapters also declare their known gaps, so an agent can check
before promising that a site is fully covered.

Coverage stays honest over time, too. Any operation can be captured once as a
**response oracle** — the redacted response *shape* plus optional assertions,
never captured values — and replayed later to prove the site has not changed
underneath the adapter. `agentweb verify-oracles --dir oracles --strict` replays
a whole directory and exits non-zero on drift, which is what the scheduled
Oracle drift workflow runs against the committed [`oracles/`](oracles/). The
full mechanism, including the browser-assisted read-back path, is documented in
[architecture](docs/ARCHITECTURE.md) and the
[adapter guide](docs/BUILDING_ADAPTERS.md).

## Login only when needed

Try public commands without logging in. When an account action needs
authorization, AgentWeb returns `authentication_required` and you run
`agentweb connect example.com`. That window opens **already signed in** by
default, copying only the target site's session files from your everyday Chrome
profile — never your history or extensions, and never cookies shared across
sites. Pass `--isolated` for a blank window instead. Sessions stay on your
device under `~/.agentweb` and are never bundled into an adapter. Read
[security and trust](docs/SECURITY.md) before installing an authenticated
third-party adapter.

## Add a site

Mapping a public, read-only site is roughly a thirty-minute job:

```bash
agentweb adapter-new example --base-url https://example.com --root ./registry
agentweb registry-build ./registry
agentweb audit example --root ./registry
```

Scaffold the adapter, describe the endpoints you want as typed operations, build
the index, then audit — `audit` verifies adapter contracts and declared
full-site coverage, so it will tell you when you have claimed more than you
mapped. [Building an adapter](docs/BUILDING_ADAPTERS.md) covers login, write
confirmation, evidence, and what must never be committed. Would rather someone
else map it?
[Request a site](https://github.com/AnayGarodia/agentweb/issues/new?template=adapter-request.yml).

## What is in this repository

This repository is the Apache-2.0 open core: the runtime, CLI, adapter tooling,
and the public adapters listed above, bundled as an offline capability floor.
`agentweb sync` can add signed hosted adapters without removing that release
bundle. The automated mapping workbench is not public. Official adapter bundles
and hosted services may use separate terms.

## Usage analytics

`agentweb dashboard` opens a private dashboard on `127.0.0.1` showing installs,
activation, repeat use, success rate, latency, and failures for this
installation. AgentWeb never records prompts, arguments, URLs, website
responses, account identities, cookies, or credentials — run
`agentweb telemetry inspect` to see exactly what one event contains, or
`agentweb telemetry disable` to switch it off ([details](docs/ANALYTICS.md)).

## Status

AgentWeb is an early public preview. Websites change endpoints, revoke sessions,
add verification, and rate-limit requests; AgentWeb reports an adapter's known
gaps and verification state instead of claiming every action will work forever.

Contributions are welcome — see [contributing](CONTRIBUTING.md),
[architecture](docs/ARCHITECTURE.md), and the [changelog](CHANGELOG.md). Coding
agents working on this repository should read [AGENTS.md](AGENTS.md);
[`llms.txt`](llms.txt) is the machine-readable documentation map.
