RuruGrab

RuruGrab is a local-first media and utility toolkit built from two pieces:

• a Tauri desktop app in app/
• a Chrome / Edge extension in extension/

The extension captures page context, cookies when needed, and browser-side actions. The desktop app owns the local HTTP API, SQLite data, download queue, file tools, and bundled runtimes.

Core data is kept on your device by default. Network access is used for the sites, metadata providers, downloads, update checks, or integrations that you enable.

Installable releases are available from RuruGrab Releases.

What It Does

Media Download Queue

Queue downloads from supported sites and monitor progress in the desktop app.

• YouTube downloads through yt-dlp
• X / Twitter and Instagram downloads through gallery-dl
• optional MP3/audio-only queueing from the extension
• retry, cancel, clear, open-folder, and delete actions
• local thumbnail and metadata capture for queue items

Browser Extension

Use the extension to send the current page or selected media to the desktop app.

• Chrome / Edge Manifest V3 extension
• context menu and popup actions
• YouTube watched-history tracking
• visual watch marks on YouTube thumbnails
• optional SQLite sync / restore workflow with the desktop app
• content scripts for YouTube, X / Twitter, Instagram, and Telegram Web helpers

File Manager Tools

RuruGrab includes a shared file-manager area with three focused tools.

• Organizer: move files into folders using filename rules
• Renamer: preview and apply rule-based filename transforms
• Duplicate finder: scan folders, group duplicates, and delete selected files

Local Utilities And Integrations

Additional tools are available from the desktop app and feature toggles.

• metadata provider search, caching, curated records, and translation settings
• text extraction jobs, local text browsing, and search previews
• QR code studio with PNG / SVG export
• XMPP chat with roster, message history, OMEMO state, and file transfer
• Telegram bot configuration with command and model-provider profiles
• external tool status and download management
• tray icon, local server settings, diagnostics, and in-place app updates

Repository Layout

app/                              Tauri + Vite + React desktop app
app/src/                          frontend tabs, shared UI, bootstrap code
app/src-tauri/src/                Rust app, local API, worker, DB, commands
app/src-tauri/crates/             feature crates for organizer, duplicate finder, vault, VVV, XMPP, etc.
app/site_template_sidecar/        Node / Playwright sidecar runtime
extension/                        Chrome / Edge extension source
docs/                             human-facing docs
docs/ai/                          feature-focused maintenance maps
extension_dist/                   built extension output

Prerequisites

• Node.js
• Rust toolchain
• Tauri build prerequisites for your platform
• required sidecar binaries under app/binaries/

Common sidecar binaries:

• yt-dlp-<target-triple>
• gallery-dl-<target-triple>
• ffmpeg-<target-triple>
• ffprobe-<target-triple>
• fpcalc-<target-triple>

On Windows these use .exe filenames such as yt-dlp-x86_64-pc-windows-msvc.exe. The helper script is host-aware:

cd app
npm run binaries:check
npm run binaries:update

Setup

Install dependencies for each workspace:

cd app && npm ci
cd ../extension && npm ci
cd ../app/site_template_sidecar/sidecar && npm ci

Run the desktop app in development:

cd app
npm run dev

Build the extension dist:

cd extension
npm run build

Build the sidecar runtime:

cd app
npm run build:sidecar

Desktop App And Extension Setup

The browser extension talks to the desktop app through the local HTTP API. Start the desktop app before using extension actions that queue downloads, sync watched state, or restore watched state.

Default local API URL:

http://127.0.0.1:16969

The API Token is created once and stored in the desktop app settings. App restart and app update do not rotate it.

To connect the extension:

1. Open the desktop app.
2. Open the desktop app server settings.
3. Copy the API Token from the API Token row.
4. Open the browser extension Options page.
5. Set Server URL to http://127.0.0.1:16969, unless you changed the app bind address.
6. Paste the copied value into API Token.
7. Run Sync now, Restore from server, or a popup queue action.

Status meanings:

• Desktop app is not running: the extension did not reach the local API.
• API token is required: the local API is reachable, but the extension token is missing or invalid.
• TypeError: Failed to fetch: the browser did not receive a readable local API response. Reload the extension after rebuilding it, restart the desktop app after rebuilding it, then verify Server URL and API Token.

When developing locally, rebuild and reload the extension after changes under extension/. Restart the desktop app after changes under app/src-tauri/.

Verification

Full app-side verification:

cd app
node dev-tools/test-all.mjs

Focused checks:

cd app && npm run test:run
cd app && npm run lint
cd app && npm run build:frontend
cd app/src-tauri && cargo test
cd extension && npm run test:run

Versioning And Releases

The version source of truth is:

app/package.json

Sync the desktop, Rust, and extension versions with:

cd app
npm run version:sync

Release workflow details live in docs/release-workflow.md.

Guides

• Development and release workflow
• Testing strategy
• Metadata DB reference
• Message code contract

License

MIT License.