CrossHook

CrossHook is a native Linux trainer launcher for Steam and Proton games. It runs directly on your Linux desktop or Steam Deck -- no WINE needed for CrossHook itself -- and orchestrates trainers, mods, and patches that run under the game's own Proton/WINE prefix.

CrossHook also includes an Install Game flow inside the Profile panel. It installs Windows games through direct proton run, defaults new prefixes under ~/.local/share/crosshook/prefixes/<slug>, and then returns you to the normal profile editor so you can review the generated profile before saving it.

Contents

• Download
• Quick Start
• Launch Modes
• Features
• Docs
• Build
• Release Notes
• Contributing

Download

Get the latest Flatpak bundle from GitHub Releases. Current releases publish Flatpak bundles only.

# Download the .flatpak bundle from the release, then install and run it
flatpak install --user --reinstall ./CrossHook_*.flatpak
flatpak run dev.crosshook.CrossHook

The Flatpak bundle is the supported in-repo distribution package.

Quick Start

1. Download the Flatpak bundle from the Releases page.
2. Install or update it: flatpak install --user --reinstall ./CrossHook_*.flatpak
3. Launch it: flatpak run dev.crosshook.CrossHook
4. Select a game from the auto-populated Steam library.
5. Choose a trainer or mod, pick a launch mode, and hit Launch.

For the full setup walkthrough, see the Quickstart guide.

For Steam/Proton-specific workflow details, see the Steam / Proton trainer workflow.

Launch Modes

CrossHook supports three launch modes depending on how your game and trainer need to run.

Steam App Launch

Launches the game through Steam using steam -applaunch <appid>, then runs the trainer against the same Proton prefix. By default the trainer is launched from its original directory so stateful bundles like Aurora keep one shared install, and profiles can opt into Copy into prefix when needed for compatibility. Use this when Steam must own the game launch (DRM, cloud saves, overlay).

Proton Run

Runs the trainer directly using proton run <trainer.exe> against the game's compatdata prefix. Useful when you want to launch a trainer standalone without going through Steam, or when the game is already running.

Profiles can choose whether the trainer runs from its current directory or is copied into the target prefix before launch. Exported standalone trainer launchers follow the same setting.

The same direct Proton path is used by the Install Game workflow in the Profile panel. That flow writes the prefix under ~/.local/share/crosshook/prefixes/<slug> and hands you back a normal GameProfile for review and save.

Profiles that use proton_run also show a Launch Optimizations panel in the right column. It uses a curated v1 option catalog, shows an info tooltip on every visible option, and autosaves checkbox changes only after the profile already exists on disk.

Native

For trainers or tools that run natively on Linux without WINE/Proton. CrossHook launches them as regular Linux processes alongside the game.

Features

Profiles and Launch

• Steam Library Auto-Populate -- Discovers installed Steam games, their App IDs, Proton versions, and compatdata paths automatically.
• Profile Management -- Save and load launch configurations per game. Switch between trainer setups instantly.
• Profile Rename with Overwrite Protection -- Rename profiles with launcher cascade and collision prevention.
• Profile Duplication -- Clone profiles with unique name generation.
• Pinned Profiles -- Pin favorite profiles for quick launch access on the Profiles and Launch pages.
• Install Game Workflow -- Install a Windows game from the Profile panel, review the generated profile, and save it explicitly after install.
• Update Game Panel -- Apply patches to Proton prefixes for game updates directly from the profile.
• Dry Run / Preview Launch Mode -- Preview the exact commands CrossHook will execute before actually launching.
• Post-Launch Failure Diagnostics -- Enhanced launch state management with helper log path tracking and failure analysis.

Launch Configuration

• Launch Optimizations -- Adjust curated proton_run tweaks with readable labels, per-option info tooltips, and autosave for already-saved profiles.
• Extended Launch Optimization Catalog -- Expanded curated optimization toggles with vendor-specific (AMD, NVIDIA, Intel) options.
• Proton Selector -- Choose which Proton version to use for each trainer, with auto-detection of installed versions.
• Compatibility Viewer -- View game/trainer compatibility information and known working configurations.

Launcher Export and Community

• Launcher Export -- Generate standalone shell scripts and .desktop entries from any profile for one-click launching without opening CrossHook.
• Stale Launcher Detection -- Detect when exported launchers are out of sync with the current profile state.
• Community Profile Sharing -- Browse, import, and export launch profiles with other users via Git-based taps.
• Community Profile Export -- Export shareable profiles from the GUI directly to community taps.
• Tap Commit Pinning -- Pin community taps to specific commits with pin/unpin UI for reproducible installs.

Diagnostics and Health

• Health Dashboard -- Profile diagnostics page showing health scores, staleness detection, trend analysis, and sortable metadata columns for all profiles.
• Diagnostic Bundle Export -- Export a diagnostic bundle of system and app state for troubleshooting.
• SQLite Metadata Layer -- Persistent metadata tracking for stable profile identity, operational history (launches, launchers), community catalog, collections, cache, and usage insights.

UI and Platform

• Adaptive Deck Layout -- Responsive layout that adapts to Steam Deck Gaming Mode for comfortable big-picture use.
• Gamepad Navigation -- Full controller and touchscreen support for Steam Deck Gaming Mode.
• Console Log Viewer -- See exactly what commands CrossHook executes, with real-time process output for debugging.
• Dark Theme -- Native dark UI that fits in on Steam Deck and Linux desktops.

Docs

• Quickstart guide
• Steam / Proton trainer workflow
• Profile duplication

Build

CrossHook is built with Tauri v2 (Rust backend + React/TypeScript frontend). Building from source requires Rust, Node.js, and system libraries for WebKitGTK.

Prerequisites

Install build dependencies automatically using the included script:

# Supports pacman, apt, dnf, and zypper
./scripts/install-native-build-deps.sh

Or install manually. You need: cargo, npm, flatpak, flatpak-builder, and development libraries for GTK3, libsoup3, WebKitGTK 4.1, and OpenSSL. Flatpak packaging also uses ImageMagick for regenerating icons from assets/*.svg before bundling.

Build the Flatpak Bundle

./scripts/build-flatpak.sh --rebuild --strict

The Flatpak helper builds the production Tauri binary, stages runtime helpers and generated icons, and produces a .flatpak bundle. For Flatpak packaging details, see packaging/flatpak/README.md.

To install or update the locally built bundle immediately:

./scripts/build-flatpak.sh --rebuild --install --strict
flatpak run dev.crosshook.CrossHook

Development

./scripts/dev-native.sh

This starts the Tauri dev server with hot-reload for the React frontend and Rust backend.

Browser Dev Mode

The React frontend can also run as a plain Vite dev server at http://localhost:5173 with all IPC calls served by hand-rolled mock handlers -- no Rust toolchain required. Start it with:

./scripts/dev-native.sh --browser

This is an iteration tool, not a parity environment. WebKitGTK (the Tauri WebView) and Chromium differ in scroll physics, color-mix() support, and font rendering, so real Tauri behavior must always be re-verified with ./scripts/dev-native.sh (no flag) before merging UI changes. For security, the server binds loopback only; --host 0.0.0.0 is unsupported by policy.

Contributors adding new #[tauri::command] handlers should register a matching mock in the mock handler registry. Production Release builds enforce a verify:no-mocks CI sentinel that rejects any bundle containing mock code -- the feature has zero production surface.

CI

Forgejo Actions workflows under .forgejo/workflows/ run collaboration checks for PRs and publish releases from tags pushed to origin. The release GitHub Actions workflow is release-only: it builds and uploads the Flatpak bundle to a GitHub Release on every version tag push (v*) to the github remote. ./scripts/prepare-release.sh --push pushes release tags to both remotes by default.

Release Notes

• Releases publish a Flatpak bundle for x86_64 Linux.
• Flatpak is the supported packaged distribution format for CrossHook.
• Legacy AppImage-era host data is imported into the Flatpak sandbox on first launch as a one-way compatibility bridge for existing users. This does not mean AppImage remains an active distribution target.
• User state (profiles, settings) is stored in ~/.config/crosshook/ or the XDG config directory, separate from the application binary.
• Install prefixes default under ~/.local/share/crosshook/prefixes/<slug> and are only saved into a profile after review in the Profile panel.
• macOS support is planned for a future release.

Contributing

Contributions are welcome on Forgejo. See CONTRIBUTING.md for development setup, code style, commit conventions, and the pull request process.

For bugs and feature requests, use the Forgejo issue templates.

License

CrossHook is open-source software under the MIT License.