Debugging frontend issues in Tauri desktop apps requires manually screenshotting, cropping, and describing what you see. Existing tools either hijack your cursor (xcap-based), render DOM to canvas (html2canvas — can't capture WebGL/video/canvas), or have no authentication.

Combine a bridge's knowledge of element positions (getBoundingClientRect) with real pixel screenshots (import -window + ImageMagick crop). No other tool does this.

# Screenshot a specific DOM element with real pixels
tauri-agent-tools screenshot --selector ".wf-toolbar" -o /tmp/toolbar.png
tauri-agent-tools screenshot --selector "#canvas-area" -o /tmp/canvas.png

# Explore DOM structure first
tauri-agent-tools dom --depth 3
tauri-agent-tools dom ".wf-canvas" --depth 4

# Then screenshot what you found
tauri-agent-tools screenshot --selector ".wf-canvas .block-node" -o /tmp/block.png

npm install -g tauri-agent-tools

System requirements:

• Linux X11: xdotool, imagemagick (sudo apt install xdotool imagemagick)
• Linux Wayland/Sway: swaymsg, grim, imagemagick
• Linux Wayland/Hyprland: hyprctl (included with Hyprland), grim, imagemagick
• macOS: imagemagick (brew install imagemagick) — all other tools are built-in. Grant Screen Recording permission in System Settings → Privacy & Security → Screen Recording.

See rust-bridge/README.md for step-by-step integration.

The bridge runs a localhost-only, token-authenticated HTTP server during development. It auto-cleans up on exit.

# DOM-targeted screenshot (needs bridge)
tauri-agent-tools screenshot --selector ".toolbar" -o /tmp/toolbar.png
tauri-agent-tools screenshot --selector "#main-canvas" --max-width 800 -o /tmp/canvas.png

# Full window screenshot (no bridge needed, works with any window)
tauri-agent-tools screenshot --title "My App" -o /tmp/full.png

# Explore DOM
tauri-agent-tools dom --depth 3
tauri-agent-tools dom ".sidebar" --depth 2 --styles

# Evaluate JS
tauri-agent-tools eval "document.title"
tauri-agent-tools eval "document.querySelectorAll('.item').length"

# Wait for conditions
tauri-agent-tools wait --selector ".toast-message" --timeout 5000
tauri-agent-tools wait --title "My App" --timeout 10000

# Window info
tauri-agent-tools info --title "My App" --json

Capture a screenshot of a window or DOM element.

Query DOM structure from the Tauri app.

Evaluate a JavaScript expression in the Tauri app.

tauri-agent-tools eval "document.title"

Wait for a condition to be met.

Show window geometry and display server info.

tauri-agent-tools info --title "My App" --json

List all visible windows, marking Tauri apps.

Monitor Tauri IPC calls in real-time (read-only). Monkey-patches window.__TAURI__.core.invoke to capture calls, then polls and restores on exit.

Monitor console output (log/warn/error/info/debug) in real-time. Monkey-patches console methods to capture entries, then polls and restores on exit.

Inspect localStorage, sessionStorage, and cookies from the Tauri webview. One-shot read — no writes.

Query webview page state: URL, title, viewport, scroll position, document size, and Tauri detection.

Compare two screenshots and output difference metrics.

Watch DOM mutations on a CSS selector (read-only). Patches a MutationObserver into the webview, polls for changes, and cleans up on exit.

Capture screenshot + DOM tree + page state + storage in one shot. Writes multiple files with a shared prefix.

Monitor Rust backend logs and sidecar output in real-time. Unlike console-monitor (which captures JavaScript console output), this captures Rust tracing/log output and sidecar process stdout/stderr via the bridge's /logs endpoint.

screenshot --selector ".toolbar" --title "My App"
  │
  ├─► Bridge client ──► POST /eval ──► getBoundingClientRect(".toolbar")
  │                                     returns { x, y, width, height }
  │
  ├─► Platform adapter ──► import -window WID png:- (capture full window)
  │
  ├─► Compute crop region:
  │     element rect from bridge + viewport offset (outerHeight - innerHeight)
  │
  └─► ImageMagick crop: png:- -crop WxH+X+Y +repage png:-

The crop accounts for window decoration (title bar, borders) by comparing window.innerHeight from the bridge with the actual window height from xdotool.

All commands are read-only. We don't inject clicks, keystrokes, scroll events, or any input into the Tauri webview. Reasons:

• Native input injection is risky. X11 input injection (e.g. via xdotool) operates system-wide, not per-window — it can grab the mouse cursor and require a hard reboot to recover.
• Simulated events don't work. dispatchEvent() creates events with isTrusted: false. Frameworks (React, Vue, Angular) and browsers reject untrusted events for security-sensitive operations.
• Input injection is fragile across platforms. X11 (xdotool), Wayland (no global input protocol by design), and macOS (requires Accessibility permission + sandbox restrictions) each have different security models. A cross-platform injection layer would be unreliable.
• Read-only is a safer contract for dev tool automation. Tools that can only observe cannot corrupt application state, trigger unintended side effects, or create security vulnerabilities in CI pipelines.

This tool is a CLI that runs commands and exits — not a persistent MCP server. Reasons:

• No daemon to manage. No port to monitor, no process to restart, no state to leak between sessions.
• No .mcp.json auto-start risk. MCP servers start automatically when a project opens in supporting editors. A dev tool that auto-starts and connects to your running app on project open is a footgun.
• No transport complexity. No WebSocket/stdio state machine, no reconnection logic, no transport-layer bugs.
• Composable with any agent framework. Commands return structured output (--json) that any tool-use system can call directly. Define each command as a tool — no MCP SDK dependency required.

• No input injection — no mouse moves, clicks, keystrokes, or cursor changes
• No xcap crate — uses xdotool + ImageMagick (read-only X11 operations)
• No daemon — CLI runs and exits, no background processes
• No .mcp.json — never auto-starts
• All OS interactions read-only — xdotool search, getwindowgeometry, import -window
• Token authenticated bridge — random 32-char token, localhost-only
• execFile (array args) — never exec (shell string), prevents command injection
• Window ID validated — must match /^\d+$/

This package ships Agent Skills so AI coding agents can automatically learn how to use the CLI and set up the bridge.

cp -r "$(npm root -g)/tauri-agent-tools/.agents" ~/.agents

npm install tauri-agent-tools

cp -r node_modules/tauri-agent-tools/.agents .agents

cp -r "$(npm root -g)/tauri-agent-tools/.agents" .agents

Full documentation is available at the docs site:

• Installation — system requirements and setup
• Quick Start — get running in 5 minutes
• Bridge Setup — integrate the Rust bridge into your Tauri app
• Command Reference — all 14 commands with examples
• Platform Support — X11, Wayland, macOS details
• Architecture — how it works under the hood

npm install
npm run build
npm test

Contributions are welcome! See CONTRIBUTING.md for:

• Development setup and prerequisites
• Code style and conventions
• Branch naming and commit message format
• Pull request process

• Open an issue for bugs or feature requests
• Star the repo if you find it useful

MIT