tosu: reading osu! memory and serving the numbers to your overlay

A memory reader that publishes over WebSocket

tosu is a memory reader for osu! that sends data to overlays, also known as pp counters, via a WebSocket API, with extra features.

The mechanism is worth understanding because it explains the whole design. Rather than running a game and having a second program poke at its memory, tosu reads the game's memory itself and publishes what it finds as a structured feed. The consumers are overlays, and the transport is a WebSocket on a local port, so an overlay is a separate program that connects and receives JSON.

The dashboard in the readme is a bit of an aside, but it tells you how the project is distributed. You download tosu from the releases page, extract tosu.exe to a folder, run it, and go to http://127.0.0.1:24050, which is the overlays dashboard where you can download counters or tweak settings of tosu. So the counters themselves are separate downloads rather than being bundled, and the dashboard is the place you pick them.

The support statement is broad in a useful way. It supports stable and osu! lazer, and it is compatible with gosuMemory and streamCompanion overlays. The topic list adds counters, overlays, pp and the reader-writer and process terms, and the badges show a Node 24.14.0 or newer requirement and an MIT badge on the readme, though the licence identifiers disagree across the project, with LGPL-3.0 in the repository metadata, GPL-3.0 in the package manifest and an MIT badge on the readme, so that is worth sorting out before you redistribute anything.

The homepage is tosu.app, and the author is Mikhail Babynichev, listed as the lead maintainer with a cat and glasses emoji, alongside a second maintainer listed as Cherry.

Three API dialects, and why compatibility is the point

The API section is the most detailed part of the readme, and reading it tells you what the project is really for.

There is a root endpoint that lists all the counters you have. Then there are three dialects, each with its own pair of endpoints.

The gosu compatible API has /json, which is an example of the /ws response, /ws itself with a response example in the wiki, and /Songs/{path}, which shows the content of a file or lists the files in a folder.

The streamCompanion compatible API has /json/sc as an example of the /tokens response, /tokens itself, and /backgroundImage for the current beatmap background.

The v2 API, described as tosu's own, has /json/v2 and /websocket/v2, plus a /websocket/v2/precise variant, each with its own response example in the wiki. Under v2 there are also file endpoints: /files/beatmap/{path} which is the same as /Songs/{path}, and separate routes for the background, the audio, and the .osu file for the current beatmap, plus /files/skin/{path} for a skin.

The reason for keeping two legacy dialects alongside a new one is that overlays are third party software. The ecosystem already had overlays written against the gosu API and against streamCompanion, and the feature list marks both as compatible. Dropping them would have broken every existing overlay to make the API tidier, which is why the readme lists them as features rather than as legacy.

The precise endpoint is interesting in its own right. It sits alongside the ordinary v2 WebSocket, and the difference is in the name: precise implies more accurate timing data, which for a rhythm game overlay is the difference between a counter that updates on the beat and one that lags. The available data list in the features section backs this up, with entries for gameplay data, user in-game data, beatmap data, session data marked as work in progress, multiple graphs for different skill sets such as aim and speed, extended starrating stats per mode, a leaderboards list, folders paths and file names, direct paths to files, the result screen and tourney data marked as not tested yet.

Calculating pp for an arbitrary beatmap

The API is not only about what is happening right now, because there is an endpoint for calculating pp for a beatmap with custom data.

By default it uses the current beatmap, and all parameters are optional. The path parameter is the path to an .osu file, with an example of C:/osu/Songs/beatmap/file.osu. The lazer parameter is true or false. The mode parameter is the osu! gamemode number, osu equals 0, taiko equals 1, catch equals 2 and mania equals 3.

The rest of the parameters are the hit counts and modifiers that decide how much pp a play is worth. The mods parameter takes a mods id or an array of mods, with an example of 64 for DT or an array with an acronym and a settings object. The acc parameter is accuracy from 0 to 100. Then there is nGeki for the amount of Geki with 300g or MAX, nKatu for the amount of Katu with 100k or 200, n300, n100 and n50 for the other weights, and nMisses for the amount of misses, plus combo and passedObjects, which is the sum of the n-counts. The clockRate parameter is the map rate number, with 1.5 as the DT example.

Several parameters are marked lazer only: sliderEndHits for the amount of slider ends hit, smallTickHits and largeTickHits for the slider tick counts, which do not exist in the stable build's scoring.

The pp calculation itself is not implemented here. The feature list says all gamemodes are supported, using rosu-pp for pp calculations, and the counters project is a separate repository under the tosu organisation, so a counter that shows performance points is reading numbers that came from that library rather than from a reimplementation.

The reasoning behind the design is that osu! stable and osu! lazer score differently, and the two need separate handling. The same split shows up in the mods parameter, where the mods id 64 means DT for stable while a lazer mod is expressed as an acronym and a settings object with a speed_change of 1.3, since lazer stores the actual rate rather than a bit flag.

Running it on Windows and on Linux through Wine

The installation guide is seven steps and assumes Windows.

You download tosu from the releases page, extract tosu.exe to a folder, run it, go to http://127.0.0.1:24050, and from there you are in the overlays dashboard where you can download counters or tweak the settings of tosu. There is a link to a video walkthrough of the dashboard.

The in-game overlay is a separate feature with its own configuration. To enable it you need to edit tosu.env and turn on ENABLE_INGAME_OVERLAY=true, and the readme admits the tutorial is to be announced.

The project's own one line description of the tool is worth quoting, because it names the transport and the audience:

Tosu is a memory reader for osu! that sends data to overlays (aka pp counters) via WebSocket API, with extra features.

The Linux section is the one to read if that is your platform, and it is specific rather than aspirational. The osu! stable build is tested on the osu-winello script with Arch Linux 2025.03.01, which the note says was the latest confirmed that everything works. Lazer builds are tested on the AppImage from the official osu repository and on the flatpak image.

There is one gotcha with a custom Wine prefix, and the fix is a single environment variable. If the Wine cwd is breaking, meaning your working directory is showing a Windows path instead of the full Linux one, you should set TOSU_OSU_PATH in your bash or zsh profile, with the example TOSU_OSU_PATH=/home/kotrik/.local/share/osu-wine/osu!. The reason is that tosu has to find the game's files and directories, and under Wine the paths it sees depend on how the prefix is set up.

The project also lists low CPU usage as a checked feature, with the parenthetical claim that it has a much lower memory recoil than the gosu, which is the tool it replaces. Memory footprint is the thing that matters here, because a memory reader competes with the game for the machine's resources.

A pnpm monorepo with a deliberate release process

The repository is a pnpm workspace with the packages/ directory holding the subprojects, and the tooling is where the project's process shows.

The root package.json is the workspace manifest and its scripts delegate into the subpackages. There is a start script that runs the dev task in packages/tosu, a watch script, separate build:win and build:linux scripts that compile for the two platforms, and a build:overlay script that builds the ingame-overlay package. Releases are cut with commit-and-tag-version, and the prepare script installs husky hooks.

The linting setup is unusually complete. There are separate prettier scripts that write and check, and eslint scripts that fix and check, with eslint run over the TypeScript files. The lint-staged configuration runs the prettier fix and the lint fix on staged js and ts files, so a commit hook formats what you staged. The dev dependencies include a prettier plugin that sorts imports, the standard eslint config, and plugins for import, node, prettier and promise rules.

The versions tell you the pace. The root package is at 4.26.2, the three most recent release tags are v4.26.2 from 2026-09-04, v4.26.1 from 2026-08-27 and v4.26.0 from 2026-08-24, so patch releases are frequent. The repository is not archived, the default branch is master, and the last push was on 2026-10-20, two days before the current date.

Two other details are worth noting for anyone reading the licences. Code signing on Windows is provided by SignPath.io under the SignPath Foundation, and the in-game overlay is provided by storycraft, both acknowledged in the sponsorship table.

Editorial conclusion

tosu suits a player who wants an in-game overlay or a leaderboard app to read live gameplay data from osu! without the memory scraping that the older tool required, and it suits an existing overlay author who wants the established APIs kept alive. It does not suit someone who wants a managed service, since the counters come from the tosu organisation's own repository and the overlay is a separate download, and it does not suit a Linux player without a Wine setup. Before running it, download the release, extract tosu.exe, start it and open the dashboard on port 24050, and on Linux set TOSU_OSU_PATH if your Wine prefix changes the working directory.

Frequently asked questions

Official sources

1. License: LGPL-3.0
2. Project website
3. README
4. Releases
5. tosuapp/tosu on GitHub