ff-rdp

A fast Rust CLI for the Firefox Remote Debugging Protocol. Communicates directly over TCP with Firefox's built-in debugger for minimal latency.

Installation

Homebrew (macOS & Linux)

brew tap ractive/tap
brew install ractive/tap/ff-rdp

Scoop (Windows)

scoop bucket add ff-rdp https://github.com/ractive/scoop-ff-rdp
scoop install ff-rdp

winget (Windows)

winget install ractive.ff-rdp

Cargo (from crates.io)

cargo install ff-rdp-cli

Manual download

Download pre-built binaries from the GitHub Releases page. Binaries are available for Linux (x86_64, ARM64, glibc and musl), macOS (Apple Silicon), and Windows (x86_64, ARM64).

First contact (for AI agents)

If anything goes wrong, run ff-rdp doctor first — it pinpoints connection, port, and version issues in one shot. The probes are:

1. Daemon registry — is a daemon running and reachable?
2. Port owner — who is listening on --port (PID, process, uptime)?
3. RDP handshake — can we receive a Firefox greeting?
4. Tabs — how many tabs are exposed by the connected target?
5. Firefox version compatibility — within the tested range?

A typical first-time session looks like:

ff-rdp launch --headless --temp-profile   # start a fresh Firefox
ff-rdp doctor                             # confirm everything is healthy
ff-rdp navigate https://example.com       # do work

When ff-rdp launch finds the requested port already in use it now fails loudly with the listener's PID and a hint pointing at doctor. Every known-failure-mode error in ff-rdp ends with a hint: line that names the next concrete command to run — connection-related ones name doctor first.

Requirements

• Firefox with remote debugging enabled:

  firefox --start-debugger-server 6000

• Rust toolchain (for building from source)

Build

cargo build --release

Usage

Run ff-rdp --help for the full command surface and options.

Key global flags: --host, --port, --tab, --jq, --timeout, --format text, --no-daemon.

--no-daemon: connect directly to Firefox, bypassing the background daemon. The daemon (default) keeps a persistent Firefox connection and buffers events for streaming commands (--follow). Use --no-daemon for one-off commands or to debug daemon issues.

All output is JSON with a standard envelope (results, total, meta). Use --jq to filter:

# List tab URLs
ff-rdp tabs --jq '.results[].url'

# Navigate to a URL
ff-rdp navigate https://example.com

# Evaluate JavaScript and extract the result
ff-rdp eval 'document.title' --jq '.results'

# Eval from a file (avoids shell quoting issues with ?. or template literals)
ff-rdp eval --file script.js

# Eval from stdin
echo 'document.querySelectorAll("a").length' | ff-rdp eval --stdin

# Target a specific tab by URL substring
ff-rdp eval 'location.href' --tab example.com

# Query DOM elements by CSS selector (default: outerHTML)
ff-rdp dom "h1"

# Get text content of matching elements
ff-rdp dom "ul li" --text

# Get element attributes as JSON
ff-rdp dom "a" --attrs

# Extract all visible page text
ff-rdp page-text

# Count characters in page text
ff-rdp page-text --jq '.results | length'

# Read console messages (errors only); output includes summary.total, summary.shown, summary.by_level
ff-rdp console --level error

# Filter console messages by pattern; limit to 20 results
ff-rdp console --pattern "TypeError" --limit 20

# Check how many messages matched vs how many were shown
ff-rdp console --limit 10 --jq '.summary'

# Show network requests
ff-rdp network

# Filter network by URL substring
ff-rdp network --filter api

# Filter network by HTTP method
ff-rdp network --method POST

# Navigate and capture all network traffic in one shot
ff-rdp navigate https://example.com --with-network

# Find failed requests during navigation
ff-rdp navigate https://example.com --with-network \
  --jq '.results.network[] | select(.status >= 400)'

# Query Performance API resource timing entries (default: --type resource)
ff-rdp perf

# Page load waterfall (DNS, TLS, TTFB, DOM timings)
ff-rdp perf --type navigation

# First Paint and First Contentful Paint timestamps
ff-rdp perf --type paint

# Largest Contentful Paint
ff-rdp perf --type lcp

# Cumulative Layout Shift entries
ff-rdp perf --type cls

# Long tasks (>50ms)
ff-rdp perf --type longtask

# Filter resource entries by URL substring
ff-rdp perf --filter "api/"

# Core Web Vitals summary with ratings (LCP, CLS, TBT, FCP, TTFB)
ff-rdp perf vitals

# Extract a single metric
ff-rdp perf vitals --jq '.results.lcp_ms'

# Click a button
ff-rdp click "button.submit"

# Type into an input (clear first with --clear)
ff-rdp type "input[name=email]" "user@example.com"
ff-rdp type "input[name=email]" "new@example.com" --clear

# Wait for an element to appear (default timeout: 5000ms)
ff-rdp wait --selector ".results"

# Wait for text to appear on the page
ff-rdp wait --text "Success" --wait-timeout 10000

# Wait for a JavaScript expression to become truthy
ff-rdp wait --eval "document.readyState === 'complete'"

# List cookies
ff-rdp cookies

# Filter cookies by name
ff-rdp cookies --name "session_id"

# Dump all localStorage
ff-rdp storage local

# Get a specific sessionStorage key
ff-rdp storage session --key "token"

# Capture a screenshot (saves PNG)
ff-rdp screenshot --output page.png

# Full-page screenshot (captures entire scrollable document)
ff-rdp screenshot --full-page --output full.png

# Screenshot at explicit height
ff-rdp screenshot --viewport-height 2000 --output tall.png

# Get computed color for an element
ff-rdp computed h1 --prop color

# Get all non-default computed styles for a selector
ff-rdp computed .card

# Get the full resolved style object
ff-rdp computed button --all

# Launch Firefox with debugging enabled
ff-rdp launch

# Launch headless Firefox with temporary profile
ff-rdp launch --headless --temp-profile

# Launch with a specific profile and debug port
ff-rdp launch --profile /path/to/profile --debug-port 9222

# Inspect a remote object grip (from eval output)
ff-rdp inspect server1.conn0.child2/obj19

# Recursive inspection (depth 2)
ff-rdp inspect server1.conn0.child2/obj19 --depth 2

# List all loaded JavaScript sources
ff-rdp sources

# Filter sources by URL substring
ff-rdp sources --filter vendor

# Filter sources by regex pattern
ff-rdp sources --pattern "cdn\.example\.com"

# Reload, go back, go forward
ff-rdp reload
ff-rdp back
ff-rdp forward

# Reload and wait until network is idle (replaces sleep)
ff-rdp reload --wait-idle
ff-rdp reload --wait-idle --idle-ms 1000 --reload-timeout 30000

Using ff-rdp from Claude Code

ff-rdp ships a Claude Code skill, ff-rdp-debug, that turns ff-rdp into a symptom-routed debugger for web bugs. Install it once and it's available in any repo on your machine:

ff-rdp install-skill --claude
# → installs the ff-rdp-debug skill to ~/.claude/skills/ff-rdp-debug/
# Skill is then available in any repo on your machine.

Inside Claude Code, trigger it with /ff-rdp-debug or natural-language prompts like "debug this page", "login doesn't work", "why is X failing in the browser". The skill routes the symptom to one of 10 deterministic playbooks (Set-Cookie strip, ChunkLoadError, React controlled-input, consent banner, …) and runs probe commands against a live Firefox tab. See kb/skills/ff-rdp-debug.md for the full skill guide.

Daemon Mode

By default, the first CLI invocation auto-starts a background daemon that holds a persistent Firefox RDP connection and buffers watcher events. Subsequent invocations connect through the daemon for faster execution and cross-command workflows.

How it works:

• First ff-rdp call spawns a daemon process (ff-rdp _daemon) in the background
• The daemon connects to Firefox, subscribes to watcher resources (network, console, errors), and listens on a random TCP loopback port
• Subsequent CLI calls connect to the daemon instead of Firefox directly
• The daemon transparently proxies RDP frames and also exposes a "daemon" virtual actor for draining buffered events
• Daemon exits automatically after 5 minutes of inactivity (configurable via --daemon-timeout)

Cross-command workflows (enabled by daemon):

# Navigate, then inspect network traffic as separate commands
ff-rdp navigate https://example.com
ff-rdp network

# Object grips from eval survive across invocations
ff-rdp eval 'document.querySelector("h1")'
ff-rdp inspect server1.conn0.child2/obj19

Disabling the daemon:

# Connect directly to Firefox (original behavior)
ff-rdp --no-daemon eval "1+1"

Registry and logs:

• Registry file: ~/.ff-rdp/daemon.json (PID, port, Firefox target)
• Log file: ~/.ff-rdp/daemon.log
• Stale registry files are cleaned up automatically when the daemon PID is dead

Troubleshooting:

• If the daemon seems stuck, delete ~/.ff-rdp/daemon.json to force a fresh start
• Use --no-daemon to bypass the daemon and test direct connectivity
• Check ~/.ff-rdp/daemon.log for daemon-side errors

Security

ff-rdp has the same power as Firefox DevTools — it can read httpOnly cookies, execute arbitrary JavaScript, capture screenshots, and navigate to URLs. The security model is "same as opening DevTools": the user is the operator.

Transport: Firefox RDP uses plaintext TCP with no TLS. By default ff-rdp connects to localhost only. For remote debugging, use SSH tunneling (ssh -L 6000:localhost:6000 remote-host) rather than exposing the debug port directly.

URL validation: The navigate command rejects javascript: and data: URLs by default to prevent accidental code execution in the page context. Allowed schemes are http:, https:, file:, and about:. Use --allow-unsafe-urls to bypass this check if needed.

Daemon trust model: The daemon listens on 127.0.0.1 (loopback only). Any local process can connect and send RDP commands through it — the same trust boundary as Firefox DevTools. The registry file (~/.ff-rdp/daemon.json) is created with owner-only permissions (0600 on Unix).

Regex limits: The --pattern flag (used by console and sources commands) applies a 1 MiB NFA size limit to prevent denial-of-service from pathological regular expressions.

Not designed for untrusted networks. Do not expose the Firefox debug port to the network. All RDP traffic (page content, cookies, eval results) is transmitted in plaintext.

Architecture

• ff-rdp-core — Protocol library: blocking TCP transport, length-prefixed JSON framing, typed errors
• ff-rdp-cli — CLI binary: clap args, jq output pipeline, command dispatch, daemon proxy

Releasing

1. Bump the version in Cargo.toml
2. Commit: git commit -am "Bump version to X.Y.Z"
3. Create a GitHub release with tag vX.Y.Z (must match Cargo.toml)

The release workflow automatically builds binaries for all platforms, publishes to crates.io, and updates Homebrew/Scoop/winget.

License

MIT