gstack/pair-agent/SKILL.md.tmpl

---
name: pair-agent
version: 0.1.0
description: |
  Pair a remote AI agent with your browser. One command generates a setup key and
  prints instructions the other agent can follow to connect. Works with OpenClaw,
  Hermes, Codex, Cursor, or any agent that can make HTTP requests. The remote agent
  gets its own tab with scoped access (read+write by default, admin on request).
  Use when asked to "pair agent", "connect agent", "share browser", "remote browser",
  "let another agent use my browser", or "give browser access".
voice-triggers:
  - "pair agent"
  - "connect agent"
  - "share my browser"
  - "remote browser access"
allowed-tools:
  - Bash
  - Read
  - AskUserQuestion

---

{{PREAMBLE}}

# /pair-agent — Share Your Browser With Another AI Agent

You're sitting in Claude Code with a browser running. You also have another AI agent
open (OpenClaw, Hermes, Codex, Cursor, whatever). You want that other agent to be
able to browse the web using YOUR browser. This skill makes that happen.

## How it works

Your gstack browser runs a local HTTP server. This skill creates a one-time setup key,
prints a block of instructions, and you paste those instructions into the other agent.
The other agent exchanges the key for a session token, creates its own tab, and starts
browsing. Each agent gets its own tab. They can't mess with each other's tabs.

The setup key expires in 5 minutes and can only be used once. If it leaks, it's dead
before anyone can abuse it. The session token lasts 24 hours.

**Same machine:** If the other agent is on the same machine (like OpenClaw running
locally), you can skip the copy-paste ceremony and write the credentials directly to
the agent's config directory.

**Remote:** If the other agent is on a different machine, you need an ngrok tunnel.
The skill will tell you if one is needed and how to set it up.

{{BROWSE_SETUP}}

## Step 1: Check prerequisites

```bash
$B status 2>/dev/null
```

If the browse server is not running, start it:

```bash
$B goto about:blank
```

This ensures the server is up and healthy before pairing.

## Step 2: Ask what they want

Use AskUserQuestion:

> Which agent do you want to pair with your browser? This determines the
> instructions format and where credentials get written.

Options:
- A) OpenClaw (local or remote)
- B) Hermes (local or remote)
- C) Codex / OpenAI Agents (local)
- D) Cursor (local)
- E) Another Claude Code session (local or remote)
- F) Something else (generic HTTP instructions)

Based on the answer, set `TARGET_HOST`:
- A → `openclaw`
- B → `hermes` (if not in hosts registry, use generic)
- C → `codex`
- D → `cursor`
- E → `claude`
- F → generic (no host-specific config)

## Step 3: Local or remote?

Use AskUserQuestion:

> Is the other agent running on this same machine, or on a different machine/server?
>
> **Same machine** skips the copy-paste ceremony. Credentials are written directly to
> the agent's config directory. No tunnel needed.
>
> **Different machine** requires an ngrok tunnel so the remote agent can reach your
> browser over the internet. A setup key and instruction block are generated for
> copy-paste.
>
> RECOMMENDATION: Choose A if the agent is local. It's instant, no copy-paste needed.

Options:
- A) Same machine (write credentials directly)
- B) Different machine (generate instruction block for copy-paste)

## Step 4: Execute pairing

### If same machine (option A):

Run pair-agent with --local flag:

```bash
$B pair-agent --local TARGET_HOST
```

Replace `TARGET_HOST` with the value from Step 2 (openclaw, codex, cursor, etc.).

If it succeeds, tell the user:
"Done. TARGET_HOST can now use your browser. It will read credentials from the
config file that was written. Try asking it to navigate to a URL."

If it fails (host not found, write permission error), show the error and suggest
using the generic remote flow instead.

### If different machine (option B):

Check if a tunnel is running:

```bash
$B pair-agent
```

If the output shows "No tunnel active" and mentions ngrok:

Tell the user:
"Your browser server is localhost-only. For a remote agent to connect, you need
an ngrok tunnel. Here's how to set one up:

1. Sign up at ngrok.com (free tier works)
2. Copy your auth token
3. Save it: `echo 'NGROK_AUTHTOKEN=your_token_here' > ~/.gstack/ngrok.env`
4. Restart the server with tunnel: `BROWSE_TUNNEL=1 $B restart`
5. Run `/pair-agent` again

If you just want to test locally, choose 'Same machine' instead."

STOP here. Wait for the user to set up ngrok and re-invoke.

If the tunnel IS active (or if the user is OK with localhost-only for same-network use),
the pair-agent command will print the instruction block. Show it to the user and tell them:

"Copy everything between the ═══ lines and paste it into your other agent's chat.
The agent will follow the instructions to connect. The setup key expires in 5 minutes."

### Admin access

If the user mentions needing JavaScript execution, cookie access, or storage access:

```bash
$B pair-agent --admin
```

Tell the user: "This gives the remote agent full admin access including JS execution,
cookie reading, and storage access. Only do this if you trust the agent and need
these capabilities."

## Step 5: Verify connection

After the user pastes the instructions into the other agent, wait a moment then check:

```bash
$B status
```

Look for the connected agent in the status output. If it appears, tell the user:
"The remote agent is connected and has its own tab. You'll see its activity in the
side panel if you have GStack Browser open."

## What the remote agent can do

With default (read+write) access:
- Navigate to URLs, click elements, fill forms, take screenshots
- Read page content (text, HTML, snapshot)
- Create new tabs (each agent gets its own)
- Cannot execute arbitrary JavaScript, read cookies, or access storage

With admin access (--admin flag):
- Everything above, plus JS execution, cookie access, storage access
- Use sparingly. Only for agents you fully trust.

## Troubleshooting

**"Tab not owned by your agent"** — The remote agent tried to interact with a tab
it didn't create. Tell it to run `newtab` first to get its own tab.

**"Domain not allowed"** — The token has domain restrictions. Re-pair with broader
domain access or no domain restrictions.

**"Rate limit exceeded"** — The agent is sending > 10 requests/second. It should
wait for the Retry-After header and slow down.

**"Token expired"** — The 24-hour session expired. Run `/pair-agent` again to
generate a new setup key.

**Agent can't reach the server** — If remote, check the ngrok tunnel is running
(`$B status`). If local, check the browse server is running.

## Platform-specific notes

### OpenClaw / AlphaClaw

OpenClaw agents use the `exec` tool instead of `Bash`. The instruction block uses
`exec curl` syntax which OpenClaw understands natively. When using `--local openclaw`,
credentials are written to `~/.openclaw/skills/gstack/browse-remote.json`.

### Hermes

Hermes agents work the same way as OpenClaw. Use the generic instruction block
(option F) which provides standard curl commands that any agent can execute.

### Codex

Codex agents can execute shell commands via `codex exec`. The instruction block's
curl commands work directly. When using `--local codex`, credentials are written
to `~/.codex/skills/gstack/browse-remote.json`.

### Cursor

Cursor's AI can run terminal commands. The instruction block works as-is.
When using `--local cursor`, credentials are written to
`~/.cursor/skills/gstack/browse-remote.json`.

## Revoking access

To disconnect a specific agent:

```bash
$B tunnel revoke AGENT_NAME
```

To disconnect all agents and rotate the root token:

```bash
# This invalidates ALL scoped tokens immediately
$B tunnel rotate
```