Onekotify (Spicetify Oneko)

Onekotify brings the classic Oneko cat back to life inside Spotify using Spicetify.

About

Back when the original Oneko disappeared from Spicetify (not really sure what happened there), I used to love on it a lot—and honestly, I missed it more than I expected.

So while learning and experimenting, I decided to recreate it myself.

This project is my attempt to bring that little cat back. Right now it’s in a kinda working state—nothing fancy yet, just the core behavior—but it’s a start. So, you're welcome to modify it.

---

Files

• onekotify.js — Spicetify extension script
• oneko-assets/ — 32 GIF frames used for animation

---

Prerequisites: Install Spicetify

If you don't have Spicetify installed yet, install it with one command:

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh

Alternative methods:

• Windows (Scoop): scoop install spicetify-cli
• macOS: brew install spicetify-cli
• Linux: Check the official Spicetify guide

For detailed setup and troubleshooting, see the Spicetify Installation Guide.

---

How to Install

Option 1: Install via Spicetify Marketplace (Recommended)

First, install the Spicetify Marketplace:

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.sh | sh

Then:

1. Open Spotify
2. Search for "onekotify" in the Spicetify Marketplace
3. Click Install

---

Option 2: Manual Install

1. Copy the extension files into your Spicetify Extensions folder:

   Make sure both onekotify.js and the oneko-assets folder are inside:

   %APPDATA%\spicetify\Extensions\
   

   On macOS/Linux:

   ~/.config/spicetify/Extensions/
   

2. Enable the extension:

   spicetify config extensions onekotify.js
   

3. Apply changes:

   spicetify apply
   

4. Restart Spotify if needed (If Spotify running, then it should automatically restart).

---

Usage

• Move your mouse inside Spotify — the cat will chase it
• Toggle visibility:

  Alt + Shift + K
  

---

Update

If you do any update to the JS file then;

• After editing onekotify.js:

  spicetify apply
  

• After updating assets:

  • Replace oneko-assets
  • Run:

    spicetify apply
    

---

Credits

The animation frames (GIF assets) in oneko-assets/ are from the original Oneko Java project, which is in the public domain. The state machine logic and behavior have been ported to JavaScript for this Spicetify extension.

---

Troubleshooting

Cat not visible:

• Run spicetify apply again
• Restart Spotify
• Check onekotify.js exists in the Extensions folder
• Ensure oneko-assets contains all 32 GIF files

Extension not loading:

• Run:

  spicetify config extensions
  

• Make sure onekotify.js is listed

---

Performance

Onekotify is extremely lightweight and designed not to interrupt your Spotify experience:

• FPS Rendered: Max 20 FPS (throttled to 50ms ticks, pauses when Spotify is minimized).
• CPU Usage: < 1% (Running simple arithmetic,state machine checks, basic math for distance, and spring physics variables , no heavy calculations).
• RAM Usage: 1-2MB (caches 32 tiny 32x32 image frames).
• GPU Usage: 0% (uses hardware-accelerated CSS transforms).

---