How to Set Up Memory Readers Like tosu and gosumemory with osu-winello

osu-winello provides built-in support for tosu and gosumemory, allowing you to launch these memory readers alongside osu! using simple command-line flags that automatically handle installation, wrapper creation, and process lifecycle management.

Setting up memory readers like tosu and gosumemory with osu-winello requires no manual Wine configuration or complex workarounds. The nellokudo/osu-winello repository ships with automated installation scripts that download, configure, and wrap these popular osu! memory readers, enabling seamless integration with streaming overlays and OBS widgets on Linux.

What Are tosu and gosumemory?

tosu is the modern, Windows-only memory reader for osu! that exposes gameplay data via a local web server. gosumemory is the legacy reader that provides similar functionality. Both tools run on localhost:24050 and allow external applications like OBS or custom overlays to read live gameplay statistics, map metadata, and performance data.

Prerequisites and Installation

Before configuring memory readers, ensure you have completed the base osu-winello installation:

# Clone and run the installer

git clone https://github.com/nellokudo/osu-winello.git
cd osu-winello
./osu-winello.sh

The installer creates the necessary directory structure at $XDG_DATA_HOME/osuconfig/ (typically ~/.local/share/osuconfig/), where memory reader configurations and wrappers are stored.

Setting Up tosu with osu-winello

Installation and Launch

To enable tosu, use the --tosu flag when launching osu!:

osu-wine --tosu

This command triggers the tosu() function in osu-winello.sh, which performs the following actions:

1. Checks for existing installation at $XDG_DATA_HOME/osuconfig/tosu/
2. Downloads the latest release from the configured ${TOSULINK} variable
3. Extracts the archive to the configuration directory
4. Calls SetupReader() to create the wrapper batch file

How the tosu Wrapper Works

The SetupReader() function in osu-winello.sh (lines 38-71) generates launch_with_memory.bat inside your osu! Wineprefix. This Windows batch script:

• Launches osu!.exe and the tosu executable simultaneously
• Polls for the osu! process every 5 seconds
• Automatically terminates tosu and its overlay process when osu! exits
• Forces a clean Wine shutdown to prevent zombie processes

Setting Up gosumemory with osu-winello

Installation and Launch

For the legacy gosumemory reader, use the --gosumemory flag:

osu-wine --gosumemory

This invokes the Gosumemory() function in osu-winello.sh (lines 74-94), which follows the same pattern as tosu:

1. Verifies installation directory at $XDG_DATA_HOME/osuconfig/gosumemory/
2. Downloads from ${GOSUMEMORYLINK} if not present
3. Extracts and prepares the executable
4. Generates the wrapper via SetupReader()

Runtime Behavior

Both readers expose data on localhost:24050, allowing OBS browser sources or external overlays to connect without additional configuration. The wrapper ensures that when you close osu!, the memory reader terminates immediately, preventing port conflicts on subsequent launches.

Disabling Memory Readers

To launch osu! without any memory reader attached:

osu-wine --disable-memory-reader

This flag bypasses the SetupReader() function entirely, starting osu! directly without the launch_with_memory.bat wrapper.

Troubleshooting and Configuration

Manual Wrapper Execution

If you need to debug the memory reader startup, you can manually execute the generated wrapper:

cd "$XDG_DATA_HOME/osuconfig"
wine "$OSUPATH/launch_with_memory.bat"

Custom Configuration

Advanced users can modify launch behavior by creating a configuration file at ~/.local/share/osuconfig/configs/custom.cfg. Refer to the example.cfg in the repository's stuff/ directory for available variables such as PRE_LAUNCH_ARGS and POST_LAUNCH_ARGS.

Port Conflicts

If localhost:24050 is already in use, ensure no orphaned reader processes are running:

pkill -f tosu
pkill -f gosumemory

Then restart osu! with your preferred memory reader flag.

Summary

• osu-winello provides automated setup for tosu and gosumemory through the osu-wine launcher.
• Use osu-wine --tosu for the modern reader or osu-wine --gosumemory for the legacy version.
• The SetupReader() function in osu-winello.sh generates launch_with_memory.bat, which manages process lifecycle and ensures clean shutdowns.
• Both readers expose data on localhost:24050 for OBS and overlay compatibility.
• Disable readers anytime with osu-wine --disable-memory-reader.

Frequently Asked Questions

How do I switch from gosumemory to tosu?

Run osu-wine --tosu to enable tosu instead. The SetupReader() function automatically replaces the wrapper configuration in launch_with_memory.bat to point to the tosu executable rather than gosumemory. Both readers can coexist in $XDG_DATA_HOME/osuconfig/, but only one can run at a time due to the shared localhost:24050 port.

Why does osu-winello use a batch file wrapper instead of launching the reader directly?

The launch_with_memory.bat wrapper, generated by SetupReader() in osu-winello.sh, ensures proper process management within the Wine environment. It polls for the osu! process and automatically terminates the memory reader when the game closes, preventing zombie processes and port conflicts on subsequent launches. This approach handles Wine's process tree limitations more reliably than direct Linux process management.

Can I use custom arguments or environment variables with the memory readers?

Yes. Create a configuration file in ~/.local/share/osuconfig/configs/ (for example, custom.cfg) and define variables such as PRE_LAUNCH_ARGS or POST_LAUNCH_ARGS. The osu-wine script sources these configurations before executing the wrapper. Refer to stuff/example.cfg in the repository for the full list of supported environment variables and argument formats.

What should I do if the memory reader fails to start or crashes?

First, verify that the reader is installed correctly by checking $XDG_DATA_HOME/osuconfig/tosu/ or gosumemory/. If files are missing, rerun the installation flag (--tosu or --gosumemory). Check for port conflicts by ensuring no other process is using localhost:24050 with lsof -i :24050. For debugging, manually run the wrapper with wine "$OSUPATH/launch_with_memory.bat" to see error output directly in the terminal.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}