mirror of
https://github.com/garrytan/gstack.git
synced 2026-08-29 01:10:50 +02:00
feat: /pair-agent skill — syntactic sugar for browser sharing
Users remember /pair-agent, not $B pair-agent. The skill walks through agent selection (OpenClaw, Hermes, Codex, Cursor, generic), local vs remote setup, tunnel configuration, and includes platform-specific notes for each agent type. Wraps the CLI command with context. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
cd85bdc196
commit
7bc46ed8f2
@@ -0,0 +1,246 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user