Agent Browser - Aircall Local Development

Opens an agent-browser instance authenticated with Aircall staging credentials for localhost development.

Usage

Use this skill when you need to browse a localhost app (http://localhost:<PORT> ) authenticated against the Aircall staging environment.

User provides:

• PORT

• The localhost port (e.g., 3000 , 5173 )

• TARGET_PATH

• The path to navigate to after auth (e.g., /playground , /... )

Steps to Execute

1. Load the agent-browser CLI reference

Always start by running agent-browser --help to get the full, up-to-date CLI reference:

agent-browser --help

This ensures you have the latest commands and options available.

2. Retrieve Fresh Staging Token

Depending on which agent runtime you are in, use the appropriate tool:

Claude Code — call the MCP tool:

mcp__aircall-personal-tools__aircall_staging_auth_token

OpenCode — call the tool:

AircallStagingAuthToken

Both tools take no arguments and return a JSON object:

{ "accessToken": "eyJhbG...", "refreshToken": "eyJhbG..." }

Extract both accessToken and refreshToken from the response.

3. Navigate to SSO callback with token

Build the SSO callback URL and open it in the browser:

agent-browser --session aircall-local open "http://localhost:<PORT>/sso/callback?token=<ACCESS_TOKEN>&refresh_token=<REFRESH_TOKEN>&redirect=<TARGET_PATH>"

Parameters:

Param Source

<PORT>

User-provided localhost port

<ACCESS_TOKEN>

accessToken from step 2

<REFRESH_TOKEN>

refreshToken from step 2

<TARGET_PATH>

User-provided target path (URL-encoded if needed)

What the app does:

• Reads token and refresh_token from the query parameters

• Stores them locally (cookie/localStorage)

• Redirects to <TARGET_PATH> — the user is now authenticated

4. Take Snapshot of Page

After navigation completes, get an interactive snapshot to see the page state:

agent-browser --session aircall-local snapshot -i

This returns interactive elements with refs (@e1 , @e2 , etc.) for further interaction.

5. Interact with Page Elements

Use the refs from the snapshot to interact:

Click an element

agent-browser --session aircall-local click @e1

Fill a text field

agent-browser --session aircall-local fill @e2 "some text"

Take screenshot

agent-browser --session aircall-local screenshot /tmp/screenshot.png

Always re-snapshot after page changes to get updated refs:

agent-browser --session aircall-local snapshot -i

Complete Example Flow

1. Run --help to load CLI reference

agent-browser --help

2. Get token (via the appropriate tool for your runtime — see step 2)

3. Open browser with auth

agent-browser --session aircall-local open "http://localhost:3000/sso/callback?token=eyJhbG...&#x26;refresh_token=eyJhbG...&#x26;redirect=/playground"

4. Get interactive snapshot

agent-browser --session aircall-local snapshot -i

5. Interact based on snapshot refs

agent-browser --session aircall-local click @e5 agent-browser --session aircall-local snapshot -i # Re-snapshot after click

6. Fill form fields

agent-browser --session aircall-local fill @e3 "test input"

7. Take screenshot for verification

agent-browser --session aircall-local screenshot /tmp/result.png

Session Management

Command Description

--session aircall-local

Use isolated browser context

agent-browser --session aircall-local close

Close browser session

agent-browser sessions

List active sessions

Browser Modes

• Headless (default): No visible browser window

• Headed: Add --headed flag to see the browser

agent-browser --session aircall-local --headed open "http://localhost:3000/sso/callback?token=..."

Troubleshooting

Token Expired

Re-run the appropriate token tool for your runtime (see step 2) to get a fresh token.

Page Not Loading

• Verify the localhost server is running on the specified port

• Check the snapshot for any error messages

• Take a screenshot: agent-browser --session aircall-local screenshot /tmp/debug.png

Element Not Found

• Re-snapshot to get current page state

• Use snapshot -i -c for more compact output

• Verify the element exists in the snapshot before interacting

Technical Details

• SSO Route: /sso/callback

• Query Params: token , refresh_token , redirect

• Session Name: aircall-local

• Auth Endpoint: https://id.aircall-staging.com/auth/v1/users/session