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.

Advanced options

Hypha server URL

Override the Hypha server the debugger connects to — the button above and the copy code update automatically. Default: https://hypha.aicell.io

Or copy the bookmarklet code manually

javascript:(function(){if(window.__HYPHA_DEBUGGER__&&window.__HYPHA_DEBUGGER__.instance)return;var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js';document.head.appendChild(s);})();

How It Works

Inject Click the bookmarklet on any page, or add a script tag, or pip install hypha-debugger for Python.
Connect The debugger connects to Hypha and registers an RPC service. A floating icon shows the service URL.
Control Paste the service URL into your AI agent. It can now inspect, click, type, screenshot, and execute code remotely.
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    |
 +-----------------------+      +-------------+      +------------------------+

Chrome Extension → now Hypha Navigator

The browser-automation extension that grew out of this project is now its own tool: Hypha Navigator. It turns the whole browser into something your AI agent can drive — open / close / switch / navigate tabs, inspect & control the current page (DOM, screenshots, click/type by index, React), run JavaScript on any page — even strict-CSP ones (via the Chrome debugger, like Puppeteer/Playwright), and it accumulates per-site agent skills (agentskills.io) so it gets faster and cheaper on each site over time. The connection runs in a privileged background context the page can't restrict, so it works on any site.

→ Get Hypha Navigator github.com/amun-ai/hypha-navigator

Lineage: the original advanced debugger extension lived here in hypha-debugger/extension; full browser automation now lives in the dedicated Hypha Navigator repo. This project (hypha-debugger) remains the lightweight injectable debugger for web pages and Python — no extension required.

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)

Endpoint	Description
`get_browser_state`	Smart DOM snapshot with all interactive elements indexed as [0], [1], [2]...
`click_element_by_index`	Click element by index with cursor animation and smooth scroll
`input_text`	Type into input / textarea / contenteditable by index
`select_option`	Select a dropdown option by index and visible text
`scroll`	Scroll page or specific container (up / down / left / right)
`remove_highlights`	Clear visual highlight overlays from the page

Page Inspection & Control

Endpoint	Description
`get_page_info`	URL, title, viewport, user agent, console logs
`get_html`	Page or element HTML content
`query_dom`	Query elements by CSS selector
`take_screenshot`	Capture as base64 PNG / JPEG
`execute_script`	Run arbitrary JavaScript and return result
`navigate`	Navigate to URL (auto-reconnects for same-origin)
`reload`	Reload page (auto-reconnects)
`get_react_tree`	Inspect React component tree
`get_skill_md`	Full API documentation

Python

Endpoint	Description
`execute_code`	Persistent REPL — variables and imports survive across calls
`get_process_info`	PID, CWD, Python version, platform, memory
`list_files` / `read_file` / `write_file`	File system access
`get_variable` / `list_variables`	Inspect namespace
`get_stack_trace`	Stack traces of all threads
`get_installed_packages`	List 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);

Hypha Debugger

Drag this to your bookmarks bar

How It Works

Architecture

Chrome Extension → now Hypha Navigator

Quick Start

Features

API Reference

Index-Based Interaction (recommended)

Page Inspection & Control

Python

Library Usage

Acknowledgments