hypha-debugger

Hypha Debugger

Remote debugger for web pages and Python processes — designed for AI agents. Inject it into any running target, then control it remotely via HTTP.

Homepage & Bookmarklet Install | npm | PyPI

JavaScript — Bookmarklet (no install)

Grab the bookmarklet from the install page — drag the button to your bookmarks bar, then click it on any web page. It injects the debugger script from the CDN and auto-starts.

Click the bookmarklet → a floating bug icon appears → click it to copy the service URL → paste into your AI agent.

Strict-CSP sites / full browser automation: a page with a strict Content Security Policy can block the bookmarklet (its script-src/connect-src stop in-page scripts from loading and connecting out). For those sites — or to drive the whole browser — use Hypha Navigator, the dedicated MV3 extension that grew out of this project's "advanced debugger": open/close/navigate tabs, control pages, run JS on any site (even strict-CSP), and accumulate per-site agent skills — all in a privileged context the page can't restrict.

Python — One command

pip install hypha-debugger
hypha-debugger

Prints a service URL and instructions. Paste them into your AI agent.

Remote Control

Use the service URL to call functions via HTTP:

# Get all interactive elements with smart DOM analysis
curl "$SERVICE_URL/get_browser_state"

# Click element by index (e.g. click [3])
curl -X POST "$SERVICE_URL/click_element_by_index" -H "Content-Type: application/json" -d '{"index": 3}'

# Type into an input by index
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"

# Execute JavaScript remotely
curl -X POST "$SERVICE_URL/execute_script" -H "Content-Type: application/json" -d '{"code": "return document.title"}'

# Python debugger
curl "$SERVICE_URL/get_process_info"
curl -X POST "$SERVICE_URL/execute_code" -H "Content-Type: application/json" -d '{"code": "import sys; sys.version"}'

# Full API docs (both JS and Python)
curl "$SERVICE_URL/get_skill_md"

The URL contains a unique random ID — no token needed. Keep the URL secret.

Smart DOM Analysis + Index-Based Interaction

The JavaScript debugger includes a smart DOM analysis engine that detects interactive elements using multiple heuristics (CSS cursor, ARIA roles, event listeners, HTML tags, contenteditable, scrollable containers). Elements are indexed as [0], [1], [2], ... for reliable AI agent interaction.

Recommended workflow:

1. get_browser_state → see all interactive elements with indices
2. click_element_by_index / input_text / select_option / scroll → act by index
3. take_screenshot → verify the result visually

Visual effects (visible to end users watching the page):

• Animated AI cursor with gradient border that moves smoothly to target elements
• Click ripple animation
• Colored highlight boxes with number labels on interactive elements
• Smooth scrolling to elements before interaction

Library Usage

Import individual functions for use in your own projects:

import {
  // DOM analysis + index-based interaction
  getBrowserState, clickElementByIndex, inputText, selectOption,
  scroll, removeHighlights,
  // Classic CSS selector-based functions
  getPageInfo, queryDom, clickElement, fillInput, scrollTo, getHtml,
  getComputedStyles, getElementBounds,
  // Capture + execution
  takeScreenshot, executeScript,
  // Navigation
  navigate, goBack, goForward, reload,
  // React inspection
  getReactTree,
  // Utilities
  wrapFn, generateSkillMd, installConsoleCapture,
  // Classes
  PageController, AICursor, HyphaDebugger, startDebugger,
} from 'hypha-debugger';

// wrapFn fixes minification issues — use it when registering
// functions with hypha-rpc in production builds (Babel/Terser)
const wrappedFn = wrapFn(mySchemaAnnotatedFunction);

<script src="https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"></script>

<script src="https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"
  data-server-url="https://hypha.aicell.io"
  data-workspace="MY_WORKSPACE"
  data-token="MY_TOKEN"></script>

import { startDebugger } from 'hypha-debugger';
const session = await startDebugger({ server_url: 'https://hypha.aicell.io' });
console.log(session.service_url);

# Async
from hypha_debugger import start_debugger
session = await start_debugger(server_url='https://hypha.aicell.io')
session.print_instructions()

# Sync
from hypha_debugger import start_debugger_sync
session = start_debugger_sync(server_url='https://hypha.aicell.io')

Acknowledgments

The smart DOM analysis and interaction engine in the JavaScript package is derived from PageAgent (MIT License), which in turn builds upon browser-use.

PageAgent — https://github.com/alibaba/page-agent Copyright (c) Alibaba Group Licensed under the MIT License

Browser Use — https://github.com/browser-use/browser-use Copyright (c) 2024 Gregor Zunic Licensed under the MIT License

We gratefully acknowledge both projects and their contributors for their excellent work on web automation and DOM interaction patterns that made this possible.

License

MIT