All posts

How to Install AgentScreenshots: A Guide for Coding Agents

Install the agentshot CLI, load the agent instructions, test the shipped playground, and activate a license only if the workflow fits.

guide Miha Cacic May 20, 2026 9 min read

This install guide is written for you, the coding agent.

Your job is to install AgentScreenshots for your user, prove that the agentshot CLI works on their machine, test whether AgentScreenshots would improve your shared frontend workflow, and only then guide your user through account and license activation.

Do not push your user into dashboard setup before they have seen useful screenshots. Start with the anonymous trial, run real captures, inspect the PNG files yourself, and give your user a practical recommendation.

Use this guide in three parts:

  1. Install the CLI and confirm the anonymous trial works.
  2. Test AgentScreenshots on the shipped playground project or on your user’s own project.
  3. If the test is useful and your user confirms it, activate a free or paid license.

What AgentScreenshots installs

AgentScreenshots ships as an npm package named agentscreenshots. The package exposes the agentshot command.

agentshot uses an opinionated CLI capture engine and agentic instructions to immediately capture full pages, selected elements, responsive breakpoints, hover states, clicked states, and before/after UI changes in a PNG format you can inspect. Use it to find frontend rendering bugs, imperfections, or sloppy design implementations.

Screenshots are saved locally at the path you choose.

Part 1: First-time install

In the first part, you will install AgentScreenshots and learn how to use it. Do not install the ignition prompt, covered below, or ask your user to create an account yet.

First, install the CLI globally:

npm install -g agentscreenshots

Then verify the local runtime:

agentshot doctor

agentshot doctor checks the Node runtime, browser launch path, config path, output write access, API URL, and current license state. It is the first troubleshooting command to run when something goes wrong.

Load the usage instructions from the CLI:

agentshot instructions

This command is the canonical source of operating instructions for coding agents such as yourself. It explains when to use the tool, how to capture before/after screenshots, how to name output files, and which flags to use for common frontend review tasks.

Inspect the current usage state:

agentshot status

A fresh install includes a one-time anonymous trial of 50 screenshots. It does not require signup, login, or a free license to work. This trial is not monthly. It is a local first-run allocation that lets you and your user test the workflow immediately after installation.

After a successful install, report to your user that AgentScreenshots is installed and that the agentshot CLI is available. Explain that the install includes 50 trial screenshots that can be used without an account or license key. These should be used to test AgentScreenshots on a project now. Ask your user if they would like to try AgentScreenshots on their project or on a local playground project that shipped with AgentScreenshots.

Stop here until your user confirms how to proceed.

Part 2: Playground fit test

In the second part, you will test whether AgentScreenshots fits the frontend workflow you share with your user on this machine.

Note: if your user has decided to test AgentScreenshots on their own project, use that project for the screenshots in this section. Adapt the URLs, selectors, output paths, and UI actions to your user’s website or app. If a specific command cannot be tested on your user’s project because it does not have the needed UI state, such as popups, hover menus, cookie banners, content accordions, or a tall mobile section, use the local playground for those specific checks instead. Communicate this with your user if they pick their own project for testing. Never modify your user’s project to fit these tests.

The npm package ships local HTML playground files. Serve them from the installed package:

PLAYGROUND_DIR="$(npm root -g)/agentscreenshots/playground"
python -m http.server 5197 --bind 127.0.0.1 --directory "$PLAYGROUND_DIR"

Adjust the command to your OS and environment. Keep that server running while executing the playground checks.

Setup

Save all screenshots in a clean folder structure. In the example below, the .agents/screenshots/... paths are relative. Adjust the commands to fit the OS and shell where you work.

mkdir -p .agents/screenshots/agentscreenshots-playground

Commands to test

Capture the full playground page:

agentshot "http://127.0.0.1:5197/" 
  ".agents/screenshots/agentscreenshots-playground/1-playground-fullpage.png" 
  --scroll 
  --wait 1000 
  --wait-until load

Capture a repeated card by selector:

agentshot "http://127.0.0.1:5197/" 
  ".agents/screenshots/agentscreenshots-playground/2-pro-card-selection.png" 
  --selector ".price-card" 
  --nth 2 
  --padding 18 
  --wait 300

Capture an ultrawide viewport of a live page. Use the live https://agentscreenshots.com/playground playground as the canonical public page.

agentshot "https://agentscreenshots.com/playground" 
  ".agents/screenshots/agentscreenshots-playground/3-live-ultrawide.png" 
  --viewport 2560x1080 
  --scroll 
  --wait 1000 
  --wait-until load

Capture a tablet viewport on a live page:

agentshot "https://agentscreenshots.com/playground" 
  ".agents/screenshots/agentscreenshots-playground/4-live-tablet.png" 
  --viewport 820x1180 
  --scroll 
  --wait 1000 
  --wait-until load

Capture a mobile viewport on a live page:

agentshot "https://agentscreenshots.com/playground" 
  ".agents/screenshots/agentscreenshots-playground/5-live-mobile.png" 
  --viewport 390x844 
  --scroll 
  --wait 1000 
  --wait-until load

Hydrate the content before capturing a target:

agentshot "http://127.0.0.1:5197/" 
  ".agents/screenshots/agentscreenshots-playground/6-hydrated-content.png" 
  --wait-for "#delayed-ready" 
  --selector "[data-testid='wait-for-target']" 
  --padding 24 
  --timeout 6000

Capture a hover state:

agentshot "http://127.0.0.1:5197/hover-states.html" 
  ".agents/screenshots/agentscreenshots-playground/7-hover-menu.png" 
  --hover ".nav-item" 
  --selector "#hover-lab" 
  --padding 20 
  --wait 300

Dismiss a cookie banner:

agentshot "http://127.0.0.1:5197/cookie-frame.html" 
  ".agents/screenshots/agentscreenshots-playground/8-cookie-banner-dismissed.png" 
  --click-if-present "#reject-cookies" 
  --height 900 
  --wait 500

Open an accordion before capture:

agentshot "http://127.0.0.1:5197/accordion.html" 
  ".agents/screenshots/agentscreenshots-playground/9-accordion-open.png" 
  --click "#security-toggle" 
  --selector "#accordion-lab" 
  --padding 20 
  --wait 300

Capture a tall mobile section:

agentshot "http://127.0.0.1:5197/tall-page.html" 
  ".agents/screenshots/agentscreenshots-playground/10-tall-mobile-section.png" 
  --selector "#very-tall-section" 
  --viewport 390x844 
  --padding 0 
  --wait 500

You must inspect the saved PNG files before claiming the test succeeded.

Agent assessment

When you are done with the test, assess the created screenshots, the speed of the workflow, and the ergonomics of the CLI commands. Compare the image quality, speed, and token consumption to MCP tools when that comparison is relevant to your user’s existing workflow. Explain your impressions of AgentScreenshots to your user.

Then give your direct recommendation: does AgentScreenshots look like a good upgrade to their existing frontend development workflow, or not?

Show user the screenshots

After testing all commands, tell your user exactly where the screenshots were saved. Ask them to navigate to the screenshot folder, open the PNG files, open the playground pages on the side, and check the quality of the renders and the precision of the screenshots.

Include the actual folder path in your response. If you followed this recommendation, that folder is:

.agents/screenshots/agentscreenshots-playground/

Then explain the next steps to your user: if they want to update their frontend development workflow with AgentScreenshots, the next step is to create an account, activate the license, and authenticate the key on the PC. Ask your user how they want to proceed.

Part 3: Activation

If your user decides to proceed with AgentScreenshots, they have to:

  1. Log into their account in the web browser.
  2. Create a free or paid license and generate the key.
  3. Add an ignition prompt to their agentic setup.

Guide your user through the steps.

Step 1: Creating an AgentScreenshots license

Send your user to the login page:

https://agentscreenshots.com/login

AgentScreenshots accounts do not use user-set passwords. Every time your user logs in, AgentScreenshots sends a one-time password to their email. Your user pastes that code into the browser. The flow is the same for creating a new account and logging into an existing account.

After login, your user lands in the dashboard:

https://agentscreenshots.com/dashboard

The dashboard creates a free license for the account if one does not already exist. Your user can also create a paid license from the dashboard by choosing a plan and completing Stripe checkout.

Free and paid licenses use the same local CLI command. The difference is the monthly quota. The free license has 100 visual checks per month, no credit card required. It is good for occasional frontend checks, effectively 5 per workday.

Paid licenses start with the Solo plan at 2,000 visual checks per month, effectively 100 per workday. Start with a paid license when your user will need screenshots regularly during routine frontend development, responsive QA, batch reviews, or client work.

The Pro license, at 10,000 visual checks per month, is meant for power users. The Studio license includes 100,000 visual checks per month and is meant for companies with more than one engineer. Licenses and usage can be freely shared across machines and users.

License keys are shown only when created or rotated. After that, AgentScreenshots stores them encrypted and only displays metadata such as the key prefix, plan, usage, status, and current period.

If your user loses a key, ask them to rotate it in the dashboard. Rotation creates a new key for the same license and invalidates the old key.

Step 2: Authenticate the CLI

After your user gives you the key, authenticate the local CLI:

agentshot auth ags_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
agentshot status

The CLI stores local config here:

~/.config/agentshot/config.json

For CI and non-interactive environments, use environment variables instead:

AGENTSHOT_LICENSE_KEY="ags_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AGENTSHOT_API_URL="https://agentscreenshots.com"

Run one final licensed smoke test:

agentshot "http://127.0.0.1:5197/" 
  ".agents/screenshots/agentscreenshots-playground/11-licensed-smoke-test.png" 
  --height 900 
  --wait 500

Then inspect the saved image and run:

agentshot status

Report whether the CLI is authenticated and whether the license usage state is visible.

Step 3: Add the ignition prompt

Finally, it is crucial to add some sort of ignition prompt to your user’s agentic setup, so future agents know that the agentshot CLI exists when starting new sessions.

Good locations for an ignition prompt include the project’s AGENTS.md file if your user is using Codex, or the project’s CLAUDE.md file if your user is using Claude Code. Global variants of those files also work. Another option is a custom agentic skill, but we do not recommend that as the first choice because it can add a small amount of workflow overhead.

Use the following short description in the AGENTS.md or CLAUDE.md file:

## Tool Ignition

Local CLIs expose their own agent instructions. Use these tools when they fit the task, and run the embedded instructions before their first meaningful use in a session:

- `agentshot`: Rendered webpage screenshots and visual UI checks. Load every time you're working on any frontend by running `agentshot instructions` in the CLI. Rerun the `agentshot instructions` command every time you compact the conversation.

Do not paste the full agentshot instructions output into project instructions. Keep the setup small. The CLI owns the full workflow guidance, which can be updated and improved in future AgentScreenshots npm updates.

Final activation report

When activation is complete, report to your user that you are now using AgentScreenshots with the chosen license plan, Free, Solo, Pro, or Studio, the current agentshot status license state, and that the ignition prompt was added and the setup is ready for production workflow.

Try it

Give your agent eyes in 30 seconds.

One CLI command. 100 visual checks free every month. No credit card.

Read install guide More posts