Neko: a Go reimplementation of the cat that chases your cursor

A reimplementation that borrows only the art

Neko is the name of a cat that chases the mouse cursor across the screen, an app written in the late 1980s and ported for many platforms, and this repository is a re-implementation of it using Golang. The README is explicit about the boundary: the code has no relationship to the original software, and this version does not use any part of the original source code except sprites and sounds. The stated goal is to demonstrate the Go language with a fun and very nostalgic example, without necessarily being tied to the behaviour of the original version. That framing matters for anyone expecting pixel-identical nostalgia, because the author is explicit that the behaviour is not a goal. The rendering library is Ebitengine, described as an incredibly easy-to-use gaming library, and the primary language is Go with a BSD-2-Clause licence, the default branch is trunk, the last push was on 2026-09-26, and the recent release tags are v0.1.46, v0.1.45 and v0.1.44.

go run main.go

That is the whole source route, if you have Go installed and want to run Neko without building a release artefact.

Prebuilt binaries for five platforms, no toolchain needed

The download section is unusually thorough for a small project, and the first line of it is the point: you can use Neko without Go or any developer tools by taking a prebuilt binary from the latest release. There are five artefacts covering the common desktop targets. macOS on Intel or Apple Silicon is a single universal zip, neko-darwin-universal.zip, which means there is no architecture to choose. Windows 64-bit is neko-windows-amd64.exe and Windows on ARM is neko-windows-arm64.exe. Linux on Intel or AMD 64-bit is neko-linux-amd64.gz and Linux on ARM 64-bit is neko-linux-arm64.gz. The macOS artefact is a neko.app bundle, signed and notarized by Apple, so it should open normally, and the README explains at length what to do if macOS reports the app as damaged, including unzipping before opening, using Open from the context menu, and the xattr command that clears the quarantine attribute. On Windows, SmartScreen may warn because the app is not from the Microsoft Store, and the answer is More info and then Run anyway.

  xattr -dr com.apple.quarantine /Applications/neko.app

On Linux the archive is decompressed and run directly.

gunzip neko-linux-amd64.gz
chmod +x neko-linux-amd64
./neko-linux-amd64

Building on Linux, where Ebitengine needs Cgo

The source route is simple everywhere except Linux. The README says that on macOS and Windows no extra dependencies are needed, while on Linux Ebitengine requires Cgo and the system development libraries, so you build with CGO_ENABLED=1 after installing the packages listed in the Ebitengine install guide, and it names them for Debian and Ubuntu: libgl1-mesa-dev, libasound2-dev, libxcursor-dev, libxi-dev, libxinerama-dev, libxrandr-dev, libxxf86vm-dev and pkg-config. Building the binary is a single command, and the Makefile at the root does the same thing across targets with CGO_ENABLED=0, including a darwin amd64 and arm64 pair that is then combined into a single universal binary with lipo, which is how the macOS download works. The install route through go install is the one for people who want it on their PATH permanently.

go build -o neko main.go

The install flow resolves dependencies, builds, and puts the binary in your Go bin directory.

cd neko
go mod tidy
go install

If the Go bin directory is not on your PATH, the README suggests adding the export line to your shell configuration, and then you can run neko in a terminal or add it to an .xinitrc or similar startup script.

Configuration is a Filo script, and flags beat the file

Neko is configured with a script in Filo, a small scripting language made by the same author for embedding in Go programs. On startup it looks for a config file in one of two places, ./neko_init.filo in the current directory first, and then $XDG_CONFIG_HOME/neko/init.filo, which defaults to ~/.config/neko/init.filo. If no file is found, the built-in defaults are used, and any setting you leave out of the file keeps its default. The settings are Speed for the movement speed of the cat, Scale for its on-screen size, Quiet to disable sound, MousePassthrough to let clicks pass through the window, and SpriteSheet for a custom sprite sheet path, with the empty default meaning the built-in cat is used. Command-line flags exist for the same five things plus help, and the README gives the precedence explicitly: defaults, then the config file, then the flags, with the flags winning.

(do
  (set Speed 2.0)             ;; movement speed of the cat
  (set Scale 2.0)             ;; on-screen scale of the cat
  (set Quiet #f)              ;; #t disables sound
  (set MousePassthrough #f)   ;; #t lets clicks pass through the window
  (set SpriteSheet ""))       ;; path to a custom sprite sheet; empty uses the built-in cat

The MousePassthrough setting is the one that changes the character of the program. With it off, the cat window takes clicks; with it on, the clicks pass through to whatever is underneath, which is the setting you want if you are working in another application and want the cat to chase the cursor without stealing the pointer.

Sprites come from the oneko ecosystem, on a fixed grid

Neko draws its frames from a single sprite sheet laid out as an 8 by 4 grid of 32 by 32 tiles, which is 256 by 128 pixels in total. The layout follows oneko.js, so sprite sheets from the oneko ecosystem can be loaded as skins, and you pass one with the -spritesheet flag or the SpriteSheet setting, and with no sheet the built-in cat is used. The built-in sheet at assets/neko.png is generated from the individual sprite files in sprites/, and the README documents how to regenerate it after editing those sprites, which is a Go test invocation with an environment variable set.

GENSHEET=1 go test -run TestGenerateSpriteSheet

That mechanism, a build-time test that stitches the source frames into one sheet, is the kind of small detail that tells you the project is set up for people who want to make their own cat. The tree supports that reading, with a sprites/ directory, an assets/ directory, a fixtures/ directory, a references/ directory and a neko_init-sample.filo file to start from. The go.mod is minimal too, with the module at github.com/crgimenes/neko requiring Go 1.27.1, Filo at 0.0.23 and Ebitengine v2 at 2.10.3, and the indirect dependencies are all Ebitengine internals, which is what you would expect from a program that draws a cat and reads a config file.

What this is not, and the honest boundaries

Two limits are worth naming. The first is behavioural fidelity. The project says outright that it is not tied to the behaviour of the original version, so if you are looking for the exact 1980s cat, with its sleep, its scratch, its run animations and its particular timing, this is a re-creation with a different personality rather than a port, and the README does not document a compatibility list. The second is the platform surface. The downloads cover macOS, Windows and Linux desktops, and the source build works on macOS and Windows without extra dependencies, but on Linux it needs Cgo and a set of development libraries, which is a real cost for a program whose purpose is decorative. The alternative to weigh is simply running the original Neko, or any of the other cursor-chasing pets, on a system that still supports it. The difference in approach is that this one is a small Go program with a scripting config file and a cross-compiled release for five targets, where the older implementations are what they always were, which is fine on an X11 desktop and awkward anywhere else.

Editorial conclusion

Adopt Neko if you want the cursor-chasing cat on a modern desktop and you are either running Go yourself or happy to take a prebuilt binary, since the whole point of the project is a small, pleasant, self-contained Go program rather than a framework. Do not adopt it if you are looking for the original Neko behaviour, because the README says this version is not tied to the behaviour of the original and shares no source with it. Before you build from source on Linux, install the Cgo development libraries Ebitengine needs, and if you want a different cat, read the sprite sheet section, since the layout is fixed at an 8 by 4 grid of 32 by 32 tiles.

Frequently asked questions

Official sources

1. crgimenes/neko on GitHub
2. Issues
3. License: BSD-2-Clause
4. README
5. Releases