tauri-plugin-debug-tools

Comprehensive debug utilities for Tauri WebView applications with AI-powered automated debugging workflows.

Features

• WebView State Capture - Capture URL, title, viewport, and User-Agent
• Console Log Collection - Ring-buffer based log collection with batched flushing
• Screenshot Integration - System screenshot command integration
• AI Agent Skill - Automated debugging workflow for AI agents
• Debug Snapshots - Save comprehensive debug state to disk
• Event-based Communication - Send debug commands to frontend via Tauri events

Quick Start

Installation

Add to your Tauri project's Cargo.toml:

[dependencies]
tauri-plugin-debug-tools = "0.1.1"

Install the frontend package:

npm install tauri-plugin-debug-tools
# or
bun add tauri-plugin-debug-tools

Setup

1. Register the plugin in your Tauri app:

// src-tauri/src/main.rs or lib.rs
fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_debug_tools::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

2. Configure the plugin (optional) in your tauri.conf.json if you want to override defaults:

{
    "plugins": {
        "debug-tools": {
            "timeout": 30
        }
    }
}

If you don't need custom configuration, you can omit this section.

3. Enable permissions in src-tauri/capabilities/default.json:

{
  "permissions": [
    "debug-tools:default"
  ]
}

**4. Initialize frontend logger** in your app entry point:

// src/main.ts or src/App.tsx
import { debugTools } from "tauri-plugin-debug-tools/consoleLogger";

// Use instead of console.*
debugTools.log("Application started");
debugTools.error("Something went wrong");

// Or import individual functions
import { log, error, warn } from "tauri-plugin-debug-tools/consoleLogger";

Usage

Frontend API

Console Logging

import { debugTools, consoleLogger } from "tauri-plugin-debug-tools/consoleLogger";

// Log messages (automatically collected)
debugTools.log("Info message");
debugTools.warn("Warning message");
debugTools.error("Error message", { context: "data" });

// Retrieve logs
const allLogs = consoleLogger.getLogs();
const errors = consoleLogger.getErrors();
const recent = consoleLogger.getRecentLogs(50);

// Get statistics
const stats = consoleLogger.getStats();
// { total: 150, byLevel: { log: 100, warn: 30, error: 20, info: 0, debug: 0 } }

WebView State Inspection

import { captureWebViewState } from "tauri-plugin-debug-tools/debugBridge";

const state = await captureWebViewState();
console.log(state);
// {
//   url: "http://localhost:5173",
//   title: "My App",
//   user_agent: "TauriWebView/2.0",
//   viewport: { width: 1200, height: 800 }
// }

Debug Commands

import { sendDebugCommand } from "tauri-plugin-debug-tools/debugBridge";

// Send event-based commands to frontend
await sendDebugCommand("refresh_state", { force: true });

Backend Commands

All commands are available through the Tauri IPC system:

Command	Description	Output
capture_webview_state	Capture WebView state	WebViewState JSON
get_console_logs	Legacy console logs	Empty array (use frontend logger)
send_debug_command	Send event to frontend	Success message
append_debug_logs	Append logs to file	Returns actual file path string
reset_debug_logs	Clear log file	Returns actual file path string
clear_debug_log_files_command	Delete/truncate debug log files	ClearDebugLogsResult JSON
copy_screenshot_to_debug_dir	Copy screenshot to debug-tools/screenshots	CopyScreenshotResult JSON
write_debug_snapshot	Save debug snapshot (legacy, uses temp dir)	Returns actual file path string

Finding Log File Locations

Both reset_debug_logs and append_debug_logs commands return the actual file path where logs are stored:

import { invoke } from '@tauri-apps/api/core';

// Get log file path
const logPath = await invoke('plugin:debug-tools|reset_debug_logs');
console.log('Logs are stored at:', logPath);
// Example output: "/Users/you/Library/Logs/com.example.app/debug-tools/frontend_console_my_app_12345.jsonl"

Typical locations:

• macOS: ~/Library/Logs/<bundle-id>/debug-tools/frontend_console_[app_name]_[pid].jsonl
• Linux/Windows: Application log directory resolved by Tauri path APIs

Where [app_name] is the application name from package_info and [pid] is the process ID.

The exact path can vary by host app configuration. Always use the path returned by reset_debug_logs / append_debug_logs as the source of truth.

Clear Debug Log Files

import { invoke } from '@tauri-apps/api/core';

const result = await invoke('plugin:debug-tools|clear_debug_log_files_command');
console.log(result);
// {
//   deleted_paths: [...],
//   truncated_paths: [...],
//   failed_paths: [...]
// }

clear_debug_log_files_command cleans up files under the plugin log root (.../debug-tools) and these subdirectories when they exist:

• dom_snapshots/
• screenshots/

Typical startup workflow in host apps:

1. Call clear_debug_log_files_command once during app boot.
2. Re-capture runtime artifacts (for example capture_dom_snapshot) after initialization.

Live Monitoring (Recommended)

LOG_DIR="$HOME/Library/Logs/<bundle-id>/debug-tools"
LATEST=$(ls -1t "$LOG_DIR"/frontend_console_*.jsonl | head -n 1)
tail -f "$LATEST"

If you don't know the exact location, fetch it via IPC first:

# in your host app code, call once:
# invoke('plugin:debug-tools|reset_debug_logs')
# then monitor the returned absolute path

Filter error logs only:

grep -in '"level":"error"' "$LATEST"

Copy Screenshot to Debug Directory

tauri-plugin-screenshots saves screenshots to app_data_dir/tauri-plugin-screenshots/. Use copy_screenshot_to_debug_dir to copy them into the unified debug-tools directory:

import { captureMainWindowToDebugDir } from "tauri-plugin-debug-tools/screenshotHelper";

// Capture and copy in one step
const path = await captureMainWindowToDebugDir();
console.log(path);
// ~/Library/Logs/<bundle-id>/debug-tools/screenshots/1740145200_window-1.png

Or manually:

import { invoke } from '@tauri-apps/api/core';

const result = await invoke('plugin:debug-tools|copy_screenshot_to_debug_dir', {
  sourcePath: '/path/to/screenshot.png'
});
console.log(result.destination_path);

AI Agent Skill

Skill Installation

Copy the bundled skill to your agent's skills directory:

(example: Codex)

cp -R skills/debug-tauri ~/.codex/skills/debug-tauri

Or for custom skill directories:

cp -R skills/debug-tauri /path/to/your/skills/debug-tauri

Skill Usage

Invoke the skill to start automated debugging:

/debug-tauri

The skill will:

1. ✅ Verify the app process is running
2. 📸 Capture a screenshot
3. 📝 Collect console logs (via IPC)
4. 🔍 Analyze visual and runtime state
5. 📄 Generate a comprehensive debug report
6. 💡 Propose fixes based on findings

Example Report

# Tauri Debug Report - 2025-12-31T22:00:00Z

## Screenshot
/tmp/tauri_debug_1735689600.png

## Process Status
- Status: Running
- PID: 12345

## Console Logs
### Recent Errors
- [ERROR] WebGL context lost (timestamp: 1735689550)
- [ERROR] Failed to load texture.png (timestamp: 1735689555)

### Log Statistics
- Total: 1,234 logs
- Errors: 2
- Warnings: 15

## Visual Analysis
### UI State
Main window visible with rendering artifacts in canvas area.

### Recommendations
1. Investigate WebGL context loss - check GPU driver
2. Verify texture.png exists in public/ directory

Architecture

flowchart TB
    subgraph DevEnv["Development Environment"]
        subgraph AIAgent["AI Agent (Codex/Claude Code)"]
            Skill["debug-tauri skill<br/>- Process verification<br/>- Screenshot capture<br/>- Log collection<br/>- Analysis & reporting"]
        end

        subgraph Tauri["Tauri Application"]
            subgraph Frontend["Frontend (TypeScript)"]
                CL["consoleLogger<br/>- Ring buffer (1000 entries)<br/>- Auto flush (1s/200 logs)<br/>- Error handling"]
                DB["debugBridge<br/>- State capture<br/>- Log retrieval<br/>- Debug commands"]
                CL -->|"Logs"| DB
            end

            subgraph Backend["Backend (Rust)"]
                Plugin["tauri-plugin-debug-tools<br/>- capture_webview_state<br/>- append_debug_logs<br/>- reset_debug_logs<br/>- write_debug_snapshot<br/>- send_debug_command"]
            end

            DB -->|"Tauri IPC"| Plugin
            CL -->|"Batch flush"| Plugin
        end

        FS["File System<br/>App log directory (logs & snapshots)<br/>e.g., ~/Library/Logs/<bundle-id>/debug-tools/frontend_console_app_12345.jsonl"]

        Plugin -->|"Write logs & snapshots"| FS
    end

    Skill -->|"1. Verify process"| Tauri
    Skill -->|"2. Invoke IPC commands"| DB
    Skill -->|"3. Read logs & snapshots"| FS
    Skill -->|"4. Capture screenshot"| FS
    FS -->|"5. Analyze & report"| Skill

    style Frontend fill:#e1f5ff
    style Backend fill:#ffe1e1
    style FS fill:#fff4e1
    style AIAgent fill:#f0e1ff
    style Skill fill:#e8d4ff

Log Collection System

The plugin uses a sophisticated ring-buffer based logging system:

• Buffer Size: Max 1,000 log entries (automatically drops oldest)
• Batch Flushing: Every 1 second or 200 pending logs
• Auto-initialization: Starts on module load
• Error Handling: Catches global error and unhandledrejection events
• Stack Traces: Automatically captures and normalizes stack traces
• Zero Config: No Safari DevTools required

Troubleshooting

Symptom	Check command	Action
Logs are not being written	invoke('plugin:debug-tools|reset_debug_logs') and verify returned path exists	Monitor the returned absolute path directly with tail -f
EADDRINUSE when starting dev app	lsof -tiTCP:5173 -sTCP:LISTEN | xargs kill	Kill the listed PID, then restart the host app
IPC permission error (denied / forbidden)	Inspect src-tauri/capabilities/*.json	Add "debug-tools:default" and restart app
Continuous NetworkError in logs	grep -in '"level":"error"' "$LATEST" and inspect API/auth logs	Fix host app API/auth state first (usually not plugin failure)
Playback state error (play() without pause()/stop())	grep -in 'play()' "$LATEST"	Fix host app playback state transition ordering

Development

# Install dependencies
bun install

# Build TypeScript
npm run build

# Lint
npm run lint

# Format
npm run format

Platform Support

• ✅ macOS (tested)
• ⚠️ Windows (log directory resolved by Tauri path APIs)
• ⚠️ Linux (log directory resolved by Tauri path APIs)

License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• Tauri - Build smaller, faster, and more secure desktop applications
• Codex - AI-powered code assistant