laantungir/sovereign_browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
master
sovereign_browser/.roo/agents.md

3.5 KiB
Raw Permalink Blame History

Agent Instructions — sovereign_browser

Browser Management

ALWAYS use ./browser.sh to start/stop/restart the browser. Never launch ./sovereign_browser directly — it will hang the terminal because the GUI process keeps stdout/stderr open.

./browser.sh start    # build + launch (detached, waits for MCP ready)
./browser.sh stop     # kill running instance
./browser.sh restart  # stop + build + start
./browser.sh status   # check if running + MCP responsive
./browser.sh log      # tail last 50 lines of browser log

The browser's MCP server runs on http://localhost:17777/mcp (Streamable HTTP transport).

Login

The browser requires Nostr login before any browser tools work. The quickest way to log in is with a random key:

# Via MCP (curl):
curl -s -X POST http://localhost:17777/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"login","arguments":{"method":"random"}}}'

Or use the login MCP tool with {"method": "random"}. This generates a fresh random Nostr keypair and logs in immediately. The response includes the nsec so you can save it if needed.

Other login methods: local (nsec/hex), seed (mnemonic), readonly (npub), nip46 (bunker URL), nsigner (hardware signer).

MCP Server

The browser exposes 100 MCP tools for browser automation:

  • Login tools: login_status, login, logout, switch_identity
  • Navigation: open, back, forward, reload, get_url, get_title
  • Snapshot & inspection: snapshot, get_text, get_html, get_attr, eval, screenshot, screenshot_annotated
  • Interaction: click, dblclick, fill, type, press, scroll, hover, focus, select, check, uncheck, drag, keyboard_type, insert_text, keydown, keyup, scroll_into_view
  • Find elements: find_role, find_text, find_label, find_placeholder, find_alt, find_title, find_testid, find_first, find_last, find_nth
  • Get info: get_value, get_count, get_box, get_styles
  • Check state: is_visible, is_enabled, is_checked
  • Tabs: tab_list, tab_new, tab_switch, tab_close, close, close_all
  • Wait: wait, wait_for, wait_for_text, wait_for_url, wait_for_load, wait_for_fn
  • Batch: batch (execute multiple tool calls in sequence)
  • Cookies & storage: cookies_get, cookies_set, cookies_clear, storage_local_*, storage_session_*
  • Mouse: mouse_move, mouse_down, mouse_up, mouse_wheel
  • Clipboard: clipboard_read, clipboard_write, clipboard_copy, clipboard_paste
  • Settings: set_viewport, set_media, set_offline, set_headers, set_credentials
  • Frames: frame_switch, frame_main
  • Dialogs: dialog_accept, dialog_dismiss, dialog_status
  • Debug: console, errors, highlight
  • State: state_save, state_load
  • Files: upload, pdf

Common Workflow

  1. ./browser.sh start (or restart if already running)
  2. Login: call login tool with {"method": "random"}
  3. Navigate: call open tool with a URL
  4. Snapshot: call snapshot to get the accessibility tree with element refs
  5. Interact: use refs (e.g. @e1) with click, fill, etc.
  6. Screenshot: call screenshot to see the page visually

Building

make            # build the browser
make clean      # clean build artifacts

The browser is a WebKitGTK + C99 application. It links against webkit2gtk-4.1, libsoup-3.0, and nostr_core_lib (vendored).