How to Capture Screenshots with Agent Browser

To capture a screenshot with Agent Browser, open the page, wait for the appropriate load milestone, then run agent-browser screenshot page.png. The filename sets the output path. Add --full to capture the entire page instead of the current viewport.

agent-browser open https://example.com
agent-browser wait --load load
agent-browser screenshot page.png

These commands follow the official Agent Browser quick start and command reference. Since CLI flags and defaults can change between versions, check agent-browser screenshot --help and the current project documentation if an option behaves differently in your installation.

1. Install and capture your first screenshot

Use the installation method and browser setup documented for your Agent Browser version. Once the CLI is available, capture a page with this sequence:

agent-browser open https://example.com
agent-browser wait --load load
agent-browser screenshot page.png

open navigates to the target URL.
wait --load load waits for the page’s load milestone before capture.
screenshot page.png captures the current viewport and writes it to page.png.

Use a destination directory when you want the file somewhere specific, for example artifacts/homepage.png. Ensure that directory already exists and that the process can write to it. Without a path, the command saves the screenshot in a temporary directory; that is convenient for inspection, but less suitable when another script must find the result reliably.

2. Choose viewport or full-page capture

A regular screenshot captures the currently visible browser viewport. It is appropriate for checking what a user sees without scrolling, or for comparing a fixed-size page region. To include content below the fold, use the full-page option:

agent-browser screenshot --full full-page.png

Choose full-page capture for long articles, complete landing pages, or visual archives. A full-page image can be much taller and larger than a viewport image. If you need a paginated document rather than one tall image, use the PDF command described below.

3. Set an output path and format

Pass a path to control where the output goes. Use a descriptive filename and extension that matches your intended format. The project README documents PNG and JPEG output, JPEG quality, a screenshot directory, and annotation options. Consult the installed version’s help for exact flag spelling and supported values because these options are version-sensitive.

# Viewport image at a chosen path
agent-browser screenshot artifacts/page.png

# Full-page image at a chosen path
agent-browser screenshot --full artifacts/page-full.png

# PDF output
agent-browser pdf artifacts/page.pdf

PNG is a practical choice when you need lossless pixels or expect to inspect fine UI detail. JPEG can reduce file size for photographic pages; set quality according to the CLI documentation if that option is available in your version. For paginated output, use PDF rather than assuming a tall full-page screenshot will be easy to print or review.

4. Capture only when the page changes

For repeated captures, --if-changed asks Agent Browser to report whether the screenshot changed. The first capture for a scope is always reported as changed. Use --threshold when small pixel differences should be ignored; its value is a ratio from 0 to 1 and it implies --if-changed.

# Capture conditionally
agent-browser screenshot --if-changed artifacts/page.png

# Treat changes below the threshold as unchanged
agent-browser screenshot --threshold 0.01 artifacts/page.png

The command response includes change information, such as the pixel change ratio. Choose a threshold carefully: too low and minor rendering variation can trigger a change; too high and a real but small visual update may be missed. The documentation does not establish a universal threshold that works for every page.

5. Wait for the right page state

The example waits for load, as shown in the quick start. A page may continue changing after that milestone because of client-side rendering, images, animations, or delayed content. If the screenshot is consistently premature, use a wait condition supported by your installed CLI that corresponds to the content you need, or wait for an appropriate page-specific condition before capturing.

For stable repeat captures, avoid capturing during animations or while dynamic content is still updating. If the page itself changes on every request, conditional capture can correctly report changes even when your code is unchanged.

6. Scrollbars, annotations, and PDF output

Headless Chromium screenshots hide native scrollbars by default. If the scrollbar itself matters to the image, the command reference documents --hide-scrollbars false at launch. This is a launch setting, so apply it when starting the browser rather than assuming it is a screenshot subcommand option.

The project README also documents annotation support. Its availability depends on the browser path: the README specifies support on the CDP-backed Chrome/Lightpanda path. Check the current README before relying on annotations with another backend.

For a PDF, use agent-browser pdf output.pdf. A PDF is useful when the deliverable should be a document rather than a raster image. Refer to the installed CLI’s help for any additional PDF configuration supported by your version.

7. Automate screenshot capture

A shell script can make the open, wait, and capture sequence repeatable. This example uses the commands documented in the quick start and writes to an explicit path:

#!/usr/bin/env bash
set -euo pipefail

url="${1:?Usage: capture.sh URL OUTPUT_PATH}"
output="${2:?Usage: capture.sh URL OUTPUT_PATH}"

agent-browser open "$url"
agent-browser wait --load load
agent-browser screenshot "$output"

Save it as capture.sh, make it executable with chmod +x capture.sh, and run ./capture.sh https://example.com artifacts/example.png. Create the output directory before running the script. For a full-page variant, add --full to the screenshot command.

When integrating this sequence into a larger job, make the output path unique per run if earlier images must be retained. Check the command’s exit status and confirm the expected file exists before passing it to a later step.

8. Troubleshooting

Symptom	Likely cause	Fix
The screenshot is saved somewhere unexpected	No output path was supplied, so it went to a temporary directory.	Pass an explicit filename, such as `artifacts/page.png`.
The screenshot misses content below the fold	The default capture covers the current viewport.	Use `agent-browser screenshot --full output.png`.
The page looks incomplete	Capture happened before the content you need was ready.	Wait for the documented load milestone or a page-specific condition supported by your CLI before taking the screenshot.
The screenshot command rejects a flag	The flag may differ by version, or may be documented for another browser path.	Check `agent-browser screenshot --help` and the current official command reference for your installed release.
The scrollbar is missing	Headless Chromium hides native scrollbars by default.	Launch with the documented `--hide-scrollbars false` setting when the scrollbar must appear.
A repeat capture is reported as changed	The page may have dynamic content or small pixel differences.	Wait for a stable state; if appropriate, use `--threshold` with a carefully chosen 0–1 ratio.
The output file cannot be written	The target directory may not exist or may not be writable.	Create the directory and check filesystem permissions for the process running Agent Browser.

9. Performance, reliability, and cost

Capture time depends on navigation and page behavior; the reviewed Agent Browser sources publish no benchmark that would support a general speed estimate. Waiting for the state you need avoids capturing too early, while waiting longer than necessary adds time to each run. Full-page images generally contain more pixels than viewport images, so they can require more storage and take longer to handle downstream.

For reliable automation, use explicit output paths, wait for the relevant page state, and check the command result before consuming the file. Conditional capture can help workflows that only need to process changed images, but validate the threshold against the variability of the target page. The cited Agent Browser sources do not specify a price for the CLI, so consult the project’s current distribution and licensing information for cost details.

10. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Instead of installing and running a browser, send one GET request with the target URL. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers identify the page verdict and whether the request was billed.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

11. FAQ

Does a screenshot without a filename still get saved?

Yes. Agent Browser saves it in a temporary directory when you omit the path. Supply a path when a script or teammate needs a predictable location.

Does `--threshold` work without `--if-changed`?

Yes. The documented behavior is that setting a threshold implies --if-changed.

Can I capture a PDF instead of an image?

Yes. Use agent-browser pdf output.pdf.

Are native scrollbars included in the default headless screenshot?

No. Headless Chromium hides them by default; the command reference documents a launch option to retain them.