Onboarding: hydralauncher/hydra

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/hydralauncher/hydra shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 25% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live hydralauncher/hydra repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/hydralauncher/hydra.

What it runs against: a local clone of hydralauncher/hydra — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in hydralauncher/hydra | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>hydralauncher/hydra</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of hydralauncher/hydra. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/hydralauncher/hydra.git
#   cd hydra
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of hydralauncher/hydra and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hydralauncher/hydra(\\.git)?\\b" \\
  && ok "origin remote is hydralauncher/hydra" \\
  || miss "origin remote is not hydralauncher/hydra (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "electron.vite.config.ts" \\
  && ok "electron.vite.config.ts" \\
  || miss "missing critical file: electron.vite.config.ts"
test -f "src/big-picture/src/app.tsx" \\
  && ok "src/big-picture/src/app.tsx" \\
  || miss "missing critical file: src/big-picture/src/app.tsx"
test -f "native/hydra-native/src/lib.rs" \\
  && ok "native/hydra-native/src/lib.rs" \\
  || miss "missing critical file: native/hydra-native/src/lib.rs"
test -f "python_rpc/main.py" \\
  && ok "python_rpc/main.py" \\
  || miss "missing critical file: python_rpc/main.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/hydralauncher/hydra"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Hydra Launcher is an open-source gaming platform built with Electron, React, TypeScript, Python, and Rust that acts as a unified library manager for PC games. It aggregates games you own, syncs progress to Hydra Cloud, unlocks achievements, and surfaces personalized game recommendations using a proprietary suggestion algorithm—functioning as a single entry point for gaming across multiple sources. Classic Electron + React monorepo: TypeScript frontend lives in src/, native Rust addon at native/hydra-native/ (compiled to .node via napi-build), Python RPC server in python_rpc/, and build artifacts in build/ (icons, NSIS installer config). Electron configuration via electron-builder.yml and electron.vite.config.ts orchestrates packaging for Windows (NSIS), macOS (DMG w/ entitlements), and Linux. CI/CD workflows coordinate TypeScript linting, Rust builds, and release distribution.

Who it's for

Gamers who want a consolidated gaming library across multiple platforms and sources; open-source contributors interested in cross-platform desktop apps (Electron), game distribution systems, or Python/Rust interop; and maintainers building community-driven gaming infrastructure.

Maturity & risk

The project is actively maintained and production-ready: it has public releases via GitHub releases, multiple distribution channels (Chocolatey, AUR via update-lp workflow), automated CI/CD pipelines (build.yml, release.yml, lint.yml), and is written in mature, widely-supported languages. The TypeScript codebase (2.1M LOC) and established architecture suggest a stable, non-experimental project, though maturity of specific subsystems varies.

Risk is moderate: the project depends heavily on Electron and the Node ecosystem (large transitive dependency tree typical of React/TypeScript projects), maintains native bindings (hydra-native Rust addon compiled via napi), and requires synchronized Python 3.9+ RPC infrastructure (python_rpc). No obvious single-maintainer risk visible, but the native compilation step during postinstall and multi-language build process (Rust → Node bindings → Python RPC) create potential cross-platform breakage points. Last visible commits suggest active maintenance, but native addon failures could block development.

Active areas of work

Active development indicated by recent CI workflows (build.yml, lint.yml, release.yml), Husky pre-commit/pre-push hooks enforcing code quality, and structured PR process (.github/pull-request-template.md). The project maintains update pipelines for AUR (update-aur.yml) and likely a marketing site trigger (trigger-lp.yml), suggesting ongoing distribution and user-facing iteration.

Get running

git clone --recursive https://github.com/hydralauncher/hydra.git
cd hydra
node --version  # ensure 16+
yarn install  # installs deps + auto-runs postinstall (builds hydra-native.node)
pip install -r requirements.txt  # Python 3.9+ RPC
yarn dev  # starts Electron dev server

Daily commands:

yarn dev              # Electron dev server (hot reload)
yarn build:win        # Windows installer + portable
yarn build:mac        # macOS DMG
yarn build:linux      # Linux AppImage
yarn build:python-rpc # Standalone Python RPC server

Map of the codebase

• package.json — Main project manifest defining dependencies (Electron, React, TypeScript) and build scripts; essential for understanding project setup and dev workflow.
• electron.vite.config.ts — Electron + Vite configuration that defines the build and dev pipeline; critical for understanding app bundling and dev server setup.
• src/big-picture/src/app.tsx — Root React component for the Big Picture (game-centric UI) interface; entry point for the primary UI layer.
• native/hydra-native/src/lib.rs — Rust native addon exposing system info, image processing, and native bindings via NAPI; bridges Node.js and native performance-critical code.
• python_rpc/main.py — Python RPC server handling torrent downloads and game management; core backend service for game library operations.
• .github/workflows/build.yml — Primary CI/CD pipeline automating builds and releases; shows build matrix and deployment targets.
• electron-builder.yml — Electron app packaging configuration for macOS, Windows, Linux; defines installer behavior and code signing.

How to make changes

Add a new game library UI component

1. Create a new React component in src/big-picture/src/components/common/ following the pattern of existing components like game-card (src/big-picture/src/components/common/game-card/index.tsx)
2. Add SCSS styles in a sibling styles.scss file, following naming conventions from existing components (src/big-picture/src/components/common/game-card/styles.scss)
3. Import and integrate the component in the main Big Picture app or container component (src/big-picture/src/app.tsx)
4. For gamepad/focus support, wrap grid layouts with grid-focus-group component (src/big-picture/src/components/common/grid-focus-group/index.tsx)

Add a new game management service

1. Create a new Python module in python_rpc/ to handle the service logic (e.g., game metadata fetching, installation tracking) (python_rpc/main.py)
2. Expose RPC endpoints in main.py that the Electron app can call via IPC to trigger the new service (python_rpc/main.py)
3. Add any dependencies to requirements.txt for the Python service (requirements.txt)
4. Test by running the Python RPC server and calling it from the Electron main process IPC handlers (python_rpc/main.py)

Add a new system capability (native Rust addon)

1. Add new functions to native/hydra-native/src/lib.rs using the #[napi] macro to expose to Node.js (native/hydra-native/src/lib.rs)
2. Update Cargo.toml with any new Rust dependencies required (native/hydra-native/Cargo.toml)
3. Run the native build script to compile the Rust addon (scripts/build-native-addon.cjs)
4. Call the new native function from React components or Electron main process via require('hydra-native') (src/big-picture/src/app.tsx)

Add a new CI/CD workflow or modify release process

1. Create or edit a workflow file in .github/workflows/ (e.g., .github/workflows/custom-check.yml) following GitHub Actions syntax (.github/workflows/build.yml)
2. Configure build matrix and step dependencies to match the main build.yml pipeline (.github/workflows/build.yml)
3. For release automation, update .github/workflows/release.yml or .github/workflows/update-aur.yml (.github/workflows/release.yml)
4. Ensure electron-builder.yml is aligned with any new platform or distribution targets (electron-builder.yml)

Why these technologies

• Electron + React + TypeScript — Cross-platform desktop UI with rich component ecosystem; TypeScript adds type safety for large codebase; React enables reusable components and state management.
• Python RPC — Python excels at file I/O, system automation, and game library management; RPC pattern decouples backend from Electron frontend and allows independent scaling.
• Rust native addon (NAPI) — System-level operations (sysinfo, image processing) require performance; Rust provides memory safety and speed; NAPI enables seamless Node.js integration.
• Vite for bundling — Fast dev server and optimized production builds; better tree-shaking than webpack; native ES modules support.
• 7-Zip, UMU, Ludusavi binaries — Battle-tested tools for archive extraction, game compatibility layers, and save management; bundled to eliminate external dependencies.

Trade-offs already made

• Multi-language architecture (Node.js + Python + Rust)

  • Why: Optimal tool for each layer: JS for UI, Python for game management scripting, Rust for performance-critical system code.
  • Consequence: Increased deployment complexity, separate build pipelines, more potential failure points; requires polyglot developer mindset.

• RPC over embedded IPC

  • Why: Python services can be spawned independently, restarted without killing Electron, easier to debug/test.
  • Consequence: Network latency between main process and RPC, additional process overhead, complexity in error handling and serialization.

• Big Picture UI as first-class feature (separate from desktop UI)

  • Why: Gamepad-first couch gaming experience with dedicated layout and focus management.
  • Consequence: Maintenance burden of two UI codebases; feature parity challenges; testing complexity for both input modes.

• Bundled external binaries (7z, UMU, Ludusavi

  • Why: undefined
  • Consequence: undefined

Traps & gotchas

Postinstall compilation: yarn install auto-runs yarn build:python-rpc and native Rust addon compilation (hydra-native.node). Failures here block full installation—ensure Rust toolchain (rustc, cargo) is present and Python 3.9+ is in PATH. Multi-process IPC: Electron main/renderer split requires understanding of ipcMain/ipcRenderer in TypeScript; data passed between processes must be serializable. Python RPC: python_rpc is a separate service; dev workflows may require running it in a separate terminal or via yarn dev orchestration. Signed commits: .husky/pre-push enforces commitlint; non-conforming messages will be rejected. Platform-specific binaries: native/hydra-native must compile for each target OS (Windows, macOS, Linux) during CI; cross-compilation may require platform-specific toolchains (e.g., osxcross for macOS on Linux). Recursive submodules: .gitmodules present; clone with --recursive to avoid missing dependencies.

Architecture

Concepts to learn

• Electron IPC (Inter-Process Communication) — Hydra splits Electron main (system access, Python RPC calls) and renderer (React UI) processes; data flows via ipcMain/ipcRenderer, which requires careful serialization and error handling.
• NAPI (Node API) for Rust Native Addons — hydra-native is compiled to .node using napi v3.5.2; understanding NAPI is critical for extending system-level functionality (sysinfo, image processing, UUID) without Node.js native module fragility.
• electron-builder Multi-Platform Packaging — Hydra targets Windows (NSIS), macOS (DMG + code signing), and Linux (AppImage) from a single config (electron-builder.yml); knowing platform-specific quirks (signing, entitlements) is essential for releases.
• Monorepo Native + JavaScript Interop — Hydra's postinstall script auto-compiles Rust to Node.js bindings, then packages everything in Electron; this workflow avoids common pitfalls in cross-language builds and version mismatches.
• Game Cloud Sync & Achievement Unlocking — Hydra Cloud backend (implemented in python_rpc) syncs game progress and awards achievements; understanding state management and server-side validation prevents cheating and data corruption.
• Recommendation Algorithm (Proprietary) — Hydra surfaces personalized game suggestions via 'powerful suggestion algorithm' mentioned in README; understanding the algorithm (likely collaborative filtering or content-based) is valuable for improving discovery and engagement.
• SCSS Modularization at Scale (341k LOC) — Managing 341k lines of SCSS across a large React codebase requires clear naming conventions and import hierarchy to avoid cascade conflicts and maintainability issues.

Related repos

• Heroic-Games-Launcher/HeroicGamesLauncher — Direct competitor: cross-platform game launcher for Epic/GOG/Prime gaming using React + Electron; shares target audience and architecture patterns.
• lutris/lutris — Alternative gaming platform for Linux using Python + GTK; complements Hydra for Linux users and shows Python-first game management patterns.
• gogcom/galaxy-integrations-python — GOG Galaxy integration framework (Python); Hydra could extend python_rpc to support Galaxy store integrations via this official API.
• electron/electron — Core framework dependency; understanding Electron process model (main/renderer IPC) is essential for Hydra development.
• proton-labs/proton — Companion tool: Proton Windows game compatibility layer for Linux; Hydra users on Linux depend on Proton to run non-native games.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow for Rust native addon compilation and testing

The repo has a native Rust addon (native/hydra-native/) with Cargo.toml and napi bindings, but there's no dedicated GitHub Actions workflow to validate Rust compilation across platforms (Windows, macOS, Linux). Currently only build.yml exists. This prevents catching Rust-specific regressions early and ensures the napi bridge stays functional.

• [ ] Create .github/workflows/test-rust.yml to run 'cargo test' and 'cargo build --release' for native/hydra-native/
• [ ] Add matrix strategy for windows-latest, macos-latest, ubuntu-latest
• [ ] Ensure Rust toolchain is installed via actions-rs/toolchain@v1
• [ ] Add cache for cargo dependencies to speed up CI
• [ ] Reference the napi-build script in scripts/build-native-addon.cjs within the workflow

Add unit tests for python_rpc module with CI validation

The python_rpc/ directory contains main.py and torrent_downloader.py but has no test suite. Given this is a backend component handling torrents and RPC calls, adding tests + a pytest CI workflow would prevent regressions and document expected behavior.

• [ ] Create python_rpc/tests/ directory with test_torrent_downloader.py and test_main.py
• [ ] Add pytest to requirements.txt
• [ ] Create .github/workflows/test-python.yml that runs 'pytest python_rpc/tests/' on Python 3.9+ matrix
• [ ] Add basic unit tests for torrent_downloader.py functions (e.g., mocking downloads)
• [ ] Include coverage reporting via pytest-cov

Add missing DevTools/Debug documentation for native Rust development

The repo mixes Node.js (Electron/React), Python, and Rust, but has no docs/ guide for contributors working on the native addon. The Cargo.toml references napi8 and tokio_rt, suggesting async Rust patterns that aren't documented. New contributors building native modules need a setup guide.

• [ ] Create docs/NATIVE_DEVELOPMENT.md documenting Rust environment setup (rustup, napi-cli)
• [ ] Add instructions for running scripts/build-native-addon.cjs locally
• [ ] Document how to debug the napi bridge between Node.js and Rust (e.g., via napi test utilities)
• [ ] Include examples of calling native functions from the Electron main/renderer process
• [ ] Reference the image, sysinfo, and uuid dependencies and their use cases in native/hydra-native/src/lib.rs

Good first issues

• Add unit tests for hydra-native Rust functions (sysinfo, image processing). Currently native/hydra-native/src/lib.rs has no visible tests; contributors could add #[cfg(test)] modules to verify UUID generation, MIME type guessing, and image format detection.: Rust testing is straightforward via cargo test, improves reliability of the critical native layer, and no test infrastructure overhead exists yet.
• Document the Python RPC API contract: create docs/python-rpc.md describing endpoints, request/response schemas, and example IPC calls from the Electron main process. python_rpc/ lacks inline API documentation.: Contributors frequently need to extend or debug the backend; formalized API docs reduce onboarding friction and catch breaking changes early.
• Extract and componentize the game card and library UI from src/ into a reusable Storybook-based component library. Currently styles live in SCSS (341k LOC) without isolated component showcases.: UI consistency improvements and design system clarity are high-value for open-source games projects; Storybook integration is lightweight and attracts designer contributions.

Top contributors

• @chubbygrannychaser — 25 commits
• @Kiwo.2 — 15 commits
• @zamitto — 13 commits
• @japa2k — 9 commits
• @dependabot[bot] — 8 commits

Recent commits

• 0d759fb — Add missing translation strings to en.json & cleanup code (#2205) (juliazero)
• 0ef09d0 — Translated using Weblate (Polish) (#2189) (juliazero)
• 3fcaedd — Merge pull request #2215 from hydralauncher/feat/small-perf-change-on-game-extraction (zamitto)
• 8a5c415 — fix: consider force prop when short cutting (zamitto)
• ca45693 — feat: remove unused prop for extraction on leveldb and simplify calls (zamitto)
• 39568f0 — Merge pull request #2195 from skyhancloud/fix-custom-game-shortcut-icons (zamitto)
• e6b01ef — Merge pull request #2210 from hydralauncher/feat/refactor-main-loop (zamitto)
• f14df0b — fix: increase powerSaveBlockerSync interval to 20 seconds (zamitto)
• 697cb75 — feat: move leveldb read out of find achievement files loop (zamitto)
• e3fb28f — Merge pull request #2196 from spectre365/main (zamitto)

Security observations

• High · Potential Insecure Dependency: napi with tokio_rt feature — native/hydra-native/Cargo.toml. The napi dependency (version 3.5.2) is enabled with the 'tokio_rt' feature, which creates an embedded Tokio runtime. This can introduce complexity in async runtime management and potential deadlock issues if not carefully handled. Additionally, napi-derive (3.3.2) is used for bindings, which could expose unsafe code patterns. Fix: Review the actual usage of tokio_rt feature and evaluate if it's necessary. Consider using stable, well-audited versions of napi. Add security audits via 'cargo audit' in CI/CD pipeline.
• High · Dependency Version Pinning Issues — native/hydra-native/Cargo.toml, package.json. Multiple critical dependencies use loose version constraints (e.g., 'image = 0.25.8' without explicit upper bounds). This allows automatic updates to minor/patch versions that could introduce breaking changes or security issues. The native module's dependencies are not pinned to exact versions in some cases. Fix: Use exact version pinning (=) for production dependencies or at minimum use tilde constraints (~) instead of caret (^). Implement dependency lock files and automate security scanning with 'cargo audit' and 'npm audit'.
• Medium · Unencrypted Sensitive Configuration in .env.example — .env.example. The .env.example file contains references to sensitive endpoints (MAIN_VITE_AUTH_URL, MAIN_VITE_WS_URL, MAIN_VITE_NIMBUS_API_URL) and referral codes (RENDERER_VITE_REAL_DEBRID_REFERRAL_ID, RENDERER_VITE_TORBOX_REFERRAL_CODE). While the file itself is an example, it indicates that sensitive configuration is managed via environment variables without clear guidance on secure handling. Fix: Ensure all actual .env files are properly gitignored (already in .gitignore). Document secure configuration management practices. Consider using secrets management tools (e.g., HashiCorp Vault) for production deployments. Add clear warnings in documentation about not committing .env files.
• Medium · Python RPC Module Without Dependency Pinning — python_rpc/, requirements.txt. The python_rpc module (python_rpc/main.py, torrent_downloader.py) lacks a detailed requirements.txt with pinned versions. Python dependencies in requirements.txt are not visible in the provided context, creating potential for supply chain attacks or version conflicts. Fix: Generate and commit a requirements-lock.txt with pinned versions using pip-tools or pip freeze. Use only specific package versions in production. Implement automated vulnerability scanning for Python dependencies using tools like Safety or Bandit.
• Medium · External Binary Execution Risk — binaries/ directory. The codebase includes pre-compiled binaries in the 'binaries/' directory (7z.dll, 7z.exe, 7zzs, umu-run, etc.). These are typically extracted and executed at runtime. If these binaries are not properly validated or sourced from untrusted locations, they could pose a supply chain attack risk. Fix: Verify integrity of all binaries using checksums or signatures. Document the source and build process for each binary. Consider downloading binaries at runtime from verified sources rather than including them in the repository. Implement binary signature verification before execution.
• Medium · Electron Application Security Hardening — electron-builder.yml, src/big-picture/src/app.tsx. The project uses Electron with React and TypeScript. While the tech stack is modern, there's no visibility into critical Electron security configurations such as preload script isolation, context isolation, or sandboxing. The electron-builder.yml configuration is present but not shown in detail. Fix: Verify that Electron is configured with: nodeIntegration: false, enableRemoteModule: false, contextIsolation: true, preload scripts properly isolated, and sandbox: true. Conduct security audit of the main process. Use Electron's security documentation as a baseline.
• Low · Missing Security Headers Configuration — undefined. No explicit Content Security Policy (CSP) or other security headers are visible in the configuration. While this is common in Electron apps, web-based components could be vulnerable to XS Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.