CtrlAssist brings "controller assist" functionality to Linux gaming by allowing multiple physical controllers to operate as a single virtual input device. This enables collaborative play and customizable gamepad setups, making it easier for players of all ages and abilities to enjoy games together. While similar features exist on modern game consoles, CtrlAssist is an open source project that enhances accessibility for PC gaming, offering additional quality-of-life improvements through virtual input devices on Linux.

✨ Features

• 🎮 Combine physical controllers into one virtual gamepad
  • Assign controllers as either Primary or Assist
• 🎛️ Customizable multiplexing modes for buttons and axes
  • Logically merging or preempting events is flexible
• 🙈 Hide physical controllers for improved game compatibility
  • Multiple hiding strategies for avoiding interference
• 🕹️ Spoof gamepad vendor for in-game layout recognition
  • Mimic either Primary or Assist controller hardware
• 🫨 Rumble pass-through from virtual to physical devices
  • Forward force feedback to either or both controllers
• 🖱️ System tray interface for graphical desktop environments
  • Configure controllers and mux options via the taskbar
  • Start/stop/alter muxing with live status notifications
  • Persistent user settings across session restarts

🎛️ Modes

🔀 mux

Combine Primary and Assist controllers into one virtual gamepad.

• 👑 Priority (default): Assist controller overrides when active
  • Axes: Prioritize Assist when active (exceeds deadzone)
    • Buttons: Prioritize Assist when button released
    • Triggers: Prioritize largest value from either
  • Ideal for partial and asynchronous assistance
    • E.g. Assist for movement while Primary for actions
• ⚖️ Average: Blend weighted inputs from both controllers
  • Axes: Averaged when both are active (exceed deadzone)
    • Buttons: logically OR'ed between pressed controllers
    • Triggers: Averaged when both are active (exceed deadzone)
  • Ideal for cooperative input and subtle corrections
    • E.g. For counter steer/brake assist in racing games
• 🔃 Toggle: Switch Active controller on demand
  • All inputs forwarded from currently active controller
    • Toggle Active controller via reserved Mode button on Assist
    • Immediately synchronizes input to current Active state
  • Ideal when fine-grain conflict-free control is needed
    • E.g. Game menu navigation or precise interventions

Screencast_20251230_070245.webm

🔁 demux

Split one Primary controller into multiple virtual gamepads.

• 🔂 Unicast (default): route Primary to Active gamepad
  • All inputs forwarded to currently active virtual gamepad
    • Cycle Active gamepad via reserved Mode button on Primary
    • Force feedback synchronized with Active gamepad
  • Ideal for switching between multiple virtual gamepads
    • E.g. Assist multiple players across multiple mux instances
• 📢 Multicast: route Primary to all virtual gamepads
  • All inputs forwarded to all virtual gamepads simultaneously
    • Including Mode button events from Primary controller
    • Force feedback synchronized with all virtual gamepads
  • Ideal for replicating Primary input across multiple devices
    • E.g. For more advanced input multiplexing pipelines

Screencast_20260108_173024.webm

⬇️ Install

The following installation methods are available:

• 🦀 Cargo (Rust package manager)
  • Ideal for customization and unsandboxed use
  • Suitable for development and contributing
  • E.g. fork custom features and upstream fixes
• 📦 Flatpak (Linux application sandbox)
  • Ideal for easy install on SteamOS, Bazzite, etc.
  • Suitable for immutable Linux distributions
  • E.g. where installing build tools is a hassle

🦀 Cargo

• Build dependencies:
  • libudev-dev
  • pkg-config
• Rust toolchain:
  • https://rust-lang.org/tools/install/
  • configure PATH per Notes linked above

Install or upgrade to the latest version:

cargo install ctrlassist --force

📦 Flatpak

• Runtime dependency:
  • Flatpak (likely already installed)

Download latest bundle from releases page and install:

export VERSION=v0.4.0
wget https://github.com/ruffsl/ctrlassist/releases/download/$VERSION/ctrlassist.flatpak
flatpak install --user ctrlassist.flatpak

Run and test via Flatpak using the application ID:

flatpak run io.github.ruffsl.ctrlassist --help

Or launch the system tray via the installed desktop icon.

📖 Usage

Use the --help flag for information on each CLI subcommand:

$ ctrlassist --help
Controller Assist for gaming on Linux

Usage: ctrlassist <COMMAND>

Commands:
  list   List all detected controllers and respective IDs
  mux    Multiplex connected controllers into virtual gamepad
  demux  Demultiplex one controller to multiple virtual gamepads
  tray   Launch system tray app for graphical control
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

🖱️ tray

Launch the system tray app for graphical control:

$ ctrlassist tray
CtrlAssist system tray started
Configure and control the mux from your system tray
Press Ctrl+C to exit

The system tray provides:

• Controller selection menus for Primary and Assist
• Configuration options for mux mode, hiding, spoofing, and rumble
• Start/Stop buttons with visual feedback
• Live status indicator in the tray icon
• Desktop notifications for status changes
• Persistent settings saved to disk on use

Device invariant options can be altered while the mux is running; all other options are disabled (greyed out) until the mux is stopped.

🧾 list

List all detected controllers and respective IDs:

$ ctrlassist list
(0) Microsoft Xbox One
(1) PS4 Controller

🔀 mux

Multiplex first two detected controllers by default:

$ ctrlassist mux
Primary: (0) Microsoft Xbox One
Assist:  (1) PS4 Controller
...
Mux Active. Press Ctrl+C to exit.

🎮 Primary Assist Mapping

Manually specify Primary and Assist controllers via IDs:

$ ctrlassist mux --primary 1 --assist 0
Primary: (1) PS4 Controller
Assist:  (0) Microsoft Xbox One
...

🎛️ Mux Mode Selection

Manually specify mode for merging controllers:

$ ctrlassist mux --mode priority

🕹️ Spoof Virtual Device

Mimic controller hardware for in-game layout recognition:

$ ctrlassist mux --spoof primary
Primary: (0) Microsoft Xbox One
Assist:  (1) PS4 Controller
Virtual: (2) Microsoft X-Box One pad (Firmware 2015) [#]

[!WARNING] Combining spoofing with some hiding strategies may also hide the virtual device.

🫨 Rumble Pass-Through

Target force feedback to either, none, or both physical controllers:

$ ctrlassist mux --rumble both

Some modes also support dynamically targeting active controllers:

$ ctrlassist mux --mode toggle --rumble active

🙈 Hide Physical Devices

Multiple hiding strategies are available to avoid input conflicts:

Use Steam hiding when running CtrlAssist via Flatpak. For 2v1 scenarios, where a third player not using CtrlAssist shares the same controller make and model, use System to avoid hiding the third player's gamepad.

Steam Input

Automatically configure Steam's controller blacklist:

ctrlassist mux --hide steam

[!NOTE] Restart Steam for blacklist to take effect; CtrlAssist reverts config on exit.

[!WARNING] Combining this hiding strategy with spoofing may also hide the virtual device.

System Level

Restrict device tree permissions system-wide:

sudo ctrlassist mux --hide system

[!NOTE] Restart game/launcher to force rediscovery; CtrlAssist reverts change on exit.

[!IMPORTANT] Not possible via Flatpak sandbox for security. Use --hide steam instead.

🔁 demux

Demultiplex via unicast between two virtual gamepads by default:

$ ctrlassist demux
Primary: (0) Microsoft Xbox One
Virtual: (1) CtrlAssist Virtual Gamepad [0]
Virtual: (2) CtrlAssist Virtual Gamepad [1]
...
Demux Active. Press Ctrl+C to exit.

$ ctrlassist demux --primary 1 --virtuals 3
Primary: (1) PS4 Controller
Virtual: (2) CtrlAssist Virtual Gamepad [0]
Virtual: (3) CtrlAssist Virtual Gamepad [1]
Virtual: (4) CtrlAssist Virtual Gamepad [2]
...

$ ctrlassist demux --mode multicast

$ ctrlassist demux --spoof primary
Primary: (0) Microsoft Xbox One
Virtual: (1) Microsoft X-Box One pad (Firmware 2015) [0]
Virtual: (2) Microsoft X-Box One pad (Firmware 2015) [1]

$ ctrlassist demux --rumble active

⚙️ Configuration

The system tray saves settings to $XDG_CONFIG_HOME/ctrlassist/config.toml:

# Mux configuration
[mux]
primary_name = "Microsoft Xbox One"
assist_name = "PS4 Controller"
mode = "Priority"
hide = "Steam"
spoof = "None"
rumble = "Both"

# Demux configuration
[demux]
primary_name = "Microsoft Xbox One"
virtuals = 2
mode = "Unicast"
hide = "Steam"
spoof = "None"
rumble = "Active"

Settings are loaded on startup and saved when using the mux. Controllers are matched by name (best-effort) if IDs change between sessions.

⚠️ Limitations

• Hiding must be done before starting games or launchers
  • Processes with open file handles may retain device access
• Reconnecting a hidden controller may revert its visibility
  • Steam hiding persists across reconnects while CtrlAssist is running
  • System hiding: custom udev rules needed for persistent permissions
• Toggle mode requires pressing all buttons and axes after startup
  • gilrs lazily initializes gamepad state used for synchronization

❓ FAQ

Frequently Asked Questions about the project.

Who is CtrlAssist for?

CtrlAssist is designed for anyone who wants to combine multiple controllers into one, enabling collaborative play, real-time assistance, or better gamepad ergonomics. Ideal for accessibility and partial asynchronous input, i.e. offloading camera angle management, movements requiring speed and precision, or on standby backup during difficult combat encounters. CtrlAssist is especially useful for:

• Players with disabilities or motor skill challenges
• Beginners still developing muscle memory for controller gameplay
• Experienced gamers helping newcomers through challenging games
• Families with young children or older relatives who want to play together
• Racing or flight sim enthusiasts using a wheel or HOTAS (Hands On Throttle-And-Stick)
• Anyone interested in collaborative co-op for single or multiplayer games

Why not pass around a single controller?

While playing "hot potato" with a gamepad may be sufficient for some scenarios, like turn-based games, divvying up level progression, menu navigation, the approach falls short for many reasons:

• Broken immersion
  • Context switching in real life pulls players out of the story
• Added friction
  • Awkward handoffs and delays interfere with real-time gameplay
• Reduced agency
  • Waiting for returned control can kill spontaneity and focus
• Deprived learning
  • No haptic feedback hinders recognizing cues like attack telegraphs
• Marginal assistance
  • Inhibited intervention may only compound unnecessary frustration

Accessibility features such as control assist address these issues by enabling simultaneous/partial input from multiple controllers, resulting in more fluid and engaging gameplay.

Why was CtrlAssist developed?

CtrlAssist was first created out of personal necessity. After migrating household gaming to Linux, including the family living room, the lack of controller assist features found on older consoles like Xbox and PlayStation became clear. CtrlAssist was developed as an open source solution to make group gaming sessions on PC more inclusive and accessible for players of all ages and abilities.

Following its initial release and personal household success, as well as the broader trend of Linux adoption, CtrlAssist evolved from a simple CLI tool into a desktop-friendly utility. This category of accessibility features has significantly enhanced family gaming time, transforming passive spectators into active participants. From helping grandparents experience new immersive and interactive single player stories, to leveling age gaps across nieces and nephews in multiplayer PvPs, to rescuing friends from critical damage and finally overcoming a challenging boss, assistive players may expect as much enjoyment as primary players.

🧑‍🍳 Cookbook

Other basic examples of how else CtrlAssist can be used include:

• Dual wielding one for each hand, like split Nintendo Switch Joy-Cons
• Combining a standard gamepad with an accessible Xbox Adaptive Controller

However, because running multiple instances is possible, more complex setups can be achieved by chaining multiple mux and demux commands together.

Couch Co-Op Swap

Two players can take turns assisting each other using toggle mode:

$ ctrlassist list
(0) PS4 Controller
(1) PS5 Controller

#!/usr/bin/env bash
ctrlassist mux --primary 0 --assist 1 --mode toggle --hide steam &
sleep 1 # wait to ensure virtual devices are discoverable
ctrlassist mux --primary 1 --assist 0 --mode toggle --hide steam &
wait

flowchart LR
    A[Assist 1 <br> Controller] --> C[Mux <br> Toggle]
    B[Assist 2 <br> Controller] --> C
    A --> D[Mux <br> Toggle]
    B --> D
    C --> E[Virtual 1 <br> Gamepad]
    D --> F[Virtual 2 <br> Gamepad]

Or specify a single assist controller by toggling once before duplicating first mux.

Double Agent Tag Team

Assist multiple Primary players using demux outputs as mux Assist inputs:

$ ctrlassist list
(0) PS4 Controller
(1) PS5 Controller
(2) Xbox One Controller

#!/usr/bin/env bash
ctrlassist demux --primary 2 --virtuals 2 --mode unicast \
  --hide steam --spoof primary & # spoof to not also hide virtual 1 & 2
sleep 1 # wait to ensure virtual devices are discoverable
ctrlassist mux --primary 0 --assist 3 --mode priority --hide steam &
sleep 1 # wait to ensure virtual devices are discoverable
ctrlassist mux --primary 1 --assist 4 --mode priority --hide steam &
wait

flowchart LR
    A[Assist <br> Controller] --> B[Demux <br> Unicast]
    B --> C[Assist 1]
    B --> D[Assist 2]
    G[Primary 1 <br> Controller] --> E[Mux <br> Priority]
    C[Assist 1 <br> Virtual] --> E
    D[Assist 2 <br> Virtual] --> F[Mux <br> Priority]
    H[Primary 2 <br> Controller] --> F
    E --> I[Virtual 1 <br> Gamepad]
    F --> J[Virtual 2 <br> Gamepad]

Simply scale with number of Primary players by adjusting the --virtuals count.

📚 Background

• Controller Assist on Xbox and Windows
• Second Controller Assistance on PlayStation
• InputPlumber: Open source input router and remapper daemon for Linux