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

> Easily set up tosu and gosumemory with osu-winello. This guide shows you how to launch memory readers alongside osu using simple command line flags for automatic setup and process management.

- Repository: [NelloKudo/osu-winello](https://github.com/nellokudo/osu-winello)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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:

```bash

# 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!:

```bash
osu-wine --tosu

```

This command triggers the `tosu()` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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:

```bash
osu-wine --gosumemory

```

This invokes the `Gosumemory()` function in [`osu-winello.sh`](https://github.com/nellokudo/osu-winello/blob/main/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:

```bash
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:

```bash
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`](https://github.com/nellokudo/osu-winello/blob/main/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:

```bash
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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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`](https://github.com/nellokudo/osu-winello/blob/main/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.