https://github.com/yandy-r/crosshook
Native Linux trainer launcher for Steam and Proton games, built for desktop and Steam Deck.
https://github.com/yandy-r/crosshook
appimage desktop-app game-modding gaming linux proton react rust steam steam-deck tauri trainer-launcher typescript wine
Last synced: about 13 hours ago
JSON representation
Native Linux trainer launcher for Steam and Proton games, built for desktop and Steam Deck.
- Host: GitHub
- URL: https://github.com/yandy-r/crosshook
- Owner: yandy-r
- License: mit
- Created: 2026-04-15T18:59:32.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-12T01:13:31.000Z (about 15 hours ago)
- Last Synced: 2026-06-12T02:13:38.190Z (about 14 hours ago)
- Topics: appimage, desktop-app, game-modding, gaming, linux, proton, react, rust, steam, steam-deck, tauri, trainer-launcher, typescript, wine
- Language: Rust
- Size: 11.6 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# CrossHook
[](https://github.com/yandy-r/crosshook/releases)
[](https://github.com/yandy-r/crosshook/releases)
[](LICENSE)
[](https://github.com/yandy-r/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/`,
and then returns you to the normal profile editor so you can review the generated profile before
saving it.
## Contents
- [Download](#download)
- [Quick Start](#quick-start)
- [Launch Modes](#launch-modes)
- [Features](#features)
- [Docs](#docs)
- [Build](#build)
- [Release Notes](#release-notes)
- [Contributing](#contributing)
## Download
Get the latest Flatpak bundle from [GitHub Releases](https://github.com/yandy-r/crosshook/releases).
Current releases publish Flatpak bundles only.
```bash
# 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](https://github.com/yandy-r/crosshook/releases).
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](docs/getting-started/quickstart.md).
For Steam/Proton-specific workflow details, see the
[Steam / Proton trainer workflow](docs/features/steam-proton-trainer-launch.doc.md).
## 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 `, 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 ` 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/` 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](docs/getting-started/quickstart.md)
- [Steam / Proton trainer workflow](docs/features/steam-proton-trainer-launch.doc.md)
- [Profile duplication](docs/features/profile-duplication.doc.md)
## Build
CrossHook is built with [Tauri v2](https://v2.tauri.app/) (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:
```bash
# 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
```bash
./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](packaging/flatpak/README.md).
To install or update the locally built bundle immediately:
```bash
./scripts/build-flatpak.sh --rebuild --install --strict
flatpak run dev.crosshook.CrossHook
```
### Development
```bash
./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:
```bash
./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](src/crosshook-native/src/lib/mocks/README.md). Production
Release builds enforce a `verify:no-mocks` CI sentinel that rejects any bundle
containing mock code -- the feature has zero production surface.
### CI
The [release](.github/workflows/release.yml) GitHub Actions workflow builds and uploads the Flatpak
bundle to a GitHub Release on every version tag push (`v*`).
## 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/` 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! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style,
commit conventions, and the pull request process.
For bugs and feature requests, use the
[issue templates](https://github.com/yandy-r/crosshook/issues/new/choose). Questions belong in
[Discussions](https://github.com/yandy-r/crosshook/discussions).
## License
CrossHook is open-source software under the [MIT License](LICENSE).