npm PyPI License

Hypha Debugger

Inject a remote debugger into any web page or Python process. Let AI agents see, click, type, and control it — via HTTP.

Drag this to your bookmarks bar

Hypha Debugger

Then click it on any web page to inject the debugger. No install needed.

Or copy the bookmarklet code manually
javascript:void ((async () => { if (window.__HYPHA_DEBUGGER__ && window.__HYPHA_DEBUGGER__.instance) { alert("Hypha Debugger already running on this page."); return; } const CDN = "https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"; let code = null; try { const res = await fetch(CDN, { mode: "cors", cache: "no-cache" }); if (!res.ok) throw new Error("HTTP " + res.status); code = await res.text(); } catch (e) { alert("Could not fetch Hypha Debugger from the CDN.\n\nThis page may block cdn.jsdelivr.net via CSP (connect-src).\n\nError: " + e.message); return; } try { (0, eval)(code); return; } catch (e1) {} try { const blob = new Blob([code], { type: "application/javascript" }); const url = URL.createObjectURL(blob); await new Promise((resolve, reject) => { const s = document.createElement("script"); s.src = url; s.onload = () => { URL.revokeObjectURL(url); resolve(); }; s.onerror = reject; (document.head || document.documentElement).appendChild(s); }); return; } catch (e2) {} alert("Hypha Debugger injected, but page CSP blocks script execution (no 'unsafe-eval', no blob: in script-src).\n\nWorkaround: open DevTools (F12) > Console, then paste:\n\nimport('https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.mjs').then(m=>m.startDebugger({server_url:'https://hypha.aicell.io'}))"); })());

How It Works

  1. Inject Click the bookmarklet on any page, or add a script tag, or pip install hypha-debugger for Python.
  2. Connect The debugger connects to Hypha and registers an RPC service. A floating icon shows the service URL.
  3. Control Paste the service URL into your AI agent. It can now inspect, click, type, screenshot, and execute code remotely.
  4. Navigate The debugger auto-reconnects across page reloads and same-origin navigation. Your agent never loses control.

Architecture

Target (Browser / Python)         Hypha Server          Remote Client (AI Agent)
 +-----------------------+      +-------------+      +------------------------+
 | Collects page state   |--WS--| Routes RPC  |--WS--| Calls debug functions  |
 | Registers debug svc   |      | messages    |      | Takes screenshots      |
 | Executes remote code  |      |             |      | Clicks, types, scrolls |
 | Returns results       |      |             |      | Runs arbitrary code    |
 +-----------------------+      +-------------+      +------------------------+

Quick Start

<!-- Add to any HTML page -->
<script src="https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"></script>

// Or via npm
import { startDebugger } from 'hypha-debugger';
const session = await startDebugger({ server_url: 'https://hypha.aicell.io' });
console.log(session.service_url);
# Install and run (one command)
pip install hypha-debugger
hypha-debugger

# Or use in your Python code
from hypha_debugger import start_debugger
session = await start_debugger(server_url='https://hypha.aicell.io')
session.print_instructions()
# After injecting the debugger, use the service URL:

# See all interactive elements
curl "$SERVICE_URL/get_browser_state"

# Click element [3]
curl -X POST "$SERVICE_URL/click_element_by_index" \
  -H "Content-Type: application/json" \
  -d '{"index": 3}'

# Type into input [5]
curl -X POST "$SERVICE_URL/input_text" \
  -H "Content-Type: application/json" \
  -d '{"index": 5, "text": "hello"}'

# Take a screenshot
curl "$SERVICE_URL/take_screenshot"

# Full API docs
curl "$SERVICE_URL/get_skill_md"

Features

🔍
Smart DOM Analysis

Detects interactive elements via CSS cursor, ARIA roles, event listeners, and tag names. Elements indexed as [0], [1], [2]...

🖱
AI Cursor

Animated cursor with gradient border moves smoothly to targets. Click ripple effect. Users see exactly what the agent is doing.

🔄
Auto-Reconnect

Survives page reloads, link clicks, and same-origin navigation. Soft page replacement keeps the debugger alive.

⚛
React Support

Inspect React component tree via fiber traversal. Access props, state, and hooks without React DevTools.

📸
Screenshots

Capture page state as base64 PNG. Works with any element or full viewport. AI agents can verify their actions visually.

🐍
Python Debugger

Persistent REPL with AST-based execution. Inspect variables, read files, get stack traces. One-command install.

🛡
Secure by Default

Service ID includes random hex — the URL is the secret. No token needed. Just keep the URL private.

📦
Library Mode

Import individual functions in your own project. wrapFn() fixes minification issues for production builds.

API Reference

All functions are callable via HTTP. Run curl "$SERVICE_URL/get_skill_md" for the complete reference with parameters.

Index-Based Interaction (recommended)

EndpointDescription
get_browser_stateSmart DOM snapshot with all interactive elements indexed as [0], [1], [2]...
click_element_by_indexClick element by index with cursor animation and smooth scroll
input_textType into input / textarea / contenteditable by index
select_optionSelect a dropdown option by index and visible text
scrollScroll page or specific container (up / down / left / right)
remove_highlightsClear visual highlight overlays from the page

Page Inspection & Control

EndpointDescription
get_page_infoURL, title, viewport, user agent, console logs
get_htmlPage or element HTML content
query_domQuery elements by CSS selector
take_screenshotCapture as base64 PNG / JPEG
execute_scriptRun arbitrary JavaScript and return result
navigateNavigate to URL (auto-reconnects for same-origin)
reloadReload page (auto-reconnects)
get_react_treeInspect React component tree
get_skill_mdFull API documentation

Python

EndpointDescription
execute_codePersistent REPL — variables and imports survive across calls
get_process_infoPID, CWD, Python version, platform, memory
list_files / read_file / write_fileFile system access
get_variable / list_variablesInspect namespace
get_stack_traceStack traces of all threads
get_installed_packagesList pip packages

Library Usage

Import individual functions for use in your own projects (e.g., building a custom agent UI):

import {
  // Smart DOM + index-based interaction
  getBrowserState, clickElementByIndex, inputText, selectOption,
  scroll, removeHighlights,
  // CSS selector-based
  getPageInfo, queryDom, clickElement, fillInput, scrollTo, getHtml,
  // Capture + execution
  takeScreenshot, executeScript,
  // Navigation (auto-reconnect built in)
  navigate, goBack, goForward, reload,
  // Utilities
  wrapFn, PageController, AICursor, startDebugger,
} from 'hypha-debugger';

// wrapFn() creates a wrapper with unminified parameter names
// — critical for production builds where Babel/Terser renames params.
// hypha-rpc uses Function.toString() to map kwargs to positional args.
const wrapped = wrapFn(mySchemaAnnotatedFunction);

Acknowledgments

The smart DOM analysis and interaction engine is derived from PageAgent (MIT), which builds upon browser-use (MIT).

PageAgent — Copyright (c) Alibaba Group, MIT License
Browser Use — Copyright (c) 2024 Gregor Zunic, MIT License