mini-tanjiro

A Tanjiro (Demon Slayer) desktop mascot — a Shimeji-style pet that lives on top of every window on your desktop. He wanders and walks along the bottom of your screen on his own; tap him to make him run, double-tap to hear his signature line. Ships as a free, non-commercial npm package: npm install -g mini-tanjiro, then run mini-tanjiro from any terminal.

Tanjiro appears as a small sprite glued to the bottom edge of your primary screen, visible above every other app (Chrome, VS Code, Finder — everything). Everywhere except the small area he occupies, clicks pass straight through the invisible overlay to whatever is underneath — your desktop works normally except where Tanjiro stands.

Current status: Tanjiro lives across all connected displays — one transparent overlay window per screen, with the simulation running in the main process. He wanders and walks along each display's ground line on his own; tap him to run, double-tap for his signature line, grab and carry him between screens, or throw him and watch him arc, bounce, and land. Published to npm — run npx mini-tanjiro, or npm install -g mini-tanjiro and then mini-tanjiro.

Platforms: macOS and Windows are supported and tested. Linux is experimental — the code runs and the app boots, but this project is developed on a Mac with no Linux machine available, so its visual behaviour is unverified. If something looks wrong on Linux, please open an issue: run npx mini-tanjiro --verbose and paste the first line it prints.

Troubleshooting

Quit him. Right-click Tanjiro and choose Quit — this always works. You can also use the menu bar icon when it is visible. If neither is reachable — GNOME has no system tray unless the AppIndicator extension is installed — run pkill -f mini-tanjiro.

The menu bar icon disappeared. macOS gives the newest menu bar item the leftmost slot, and that is the first one the system drops when the bar runs out of room. It is not a crash: Tanjiro is still running, and right-clicking him still opens Guide and Quit.

To keep the icon permanently, ⌘-drag it a few positions to the right in the menu bar. macOS remembers where you put it, and out of the leftmost slot it stops being the first thing evicted. The app cannot do this for you — there is no API to claim a menu bar position.

He is a black rectangle (Linux). Some Linux GPU stacks hand back a window with no alpha channel. Try MINI_TANJIRO_DISABLE_GPU=1 npx mini-tanjiro, and please open an issue either way — whether it helps identifies the cause.

Nothing happens at all. Run npx mini-tanjiro --verbose. That keeps the process attached and prints what the app is doing.

"Electron failed to install correctly". mini-tanjiro ships a small Electron npm wrapper and downloads the separate ~100 MB runtime during npm install (with an X.X MB / Y.Y MB progress bar on a real terminal). If Electron was already cached on your machine, the download finishes quickly and you may only see the static "extracting" line — that is normal. That step can be skipped if npm was configured to skip setup scripts — most often ignore-scripts=true. If the runtime is still missing after install, the first run of mini-tanjiro will try again. To check whether skipped scripts were the cause:

npm config get ignore-scripts

If that prints true, reinstall with npm install -g mini-tanjiro --ignore-scripts=false.

Disclaimer: Unofficial fan project. Not affiliated with Shueisha, Ufotable, or Demon Slayer. Free and non-commercial.

For the full v1 product spec and roadmap, see V1.md. For the v2 spec (in progress), see V2.md.

Prerequisites

• Node.js (v22+ recommended)
• Bun (dev tooling — end users installing the published package via npm never need this)

Install (development)

Clone or download the repo, then:

bun install

Commands

Run (development)

Start the app with hot reload:

bun run dev

Preview the production build locally (no dev server):

bun run start

Build

Typecheck and compile to out/:

bun run build

Run the built app directly (without global install):

node bin/mini-tanjiro.js

Typecheck

Check TypeScript for main, preload, and renderer:

bun run typecheck

Check main/preload only:

bun run typecheck:node

Check renderer only:

bun run typecheck:web

Lint & format

bun run lint
bun run format

Global CLI (local test)

This mirrors the real end-user install path, so it deliberately uses npm rather than bun — end users installing the published package always go through npm.

Install the package globally from this folder, then run from anywhere:

npm install -g .
mini-tanjiro

The process detaches immediately — the terminal returns to a prompt while the overlay keeps running.

Uninstall the global test install:

npm uninstall -g mini-tanjiro

Packaging check

See what would be included in an npm publish tarball:

npm pack --dry-run

Quitting

Right-click Tanjiro and choose Quit. When the menu bar icon is visible, you can also click it and choose Quit.

If the process is ever unresponsive, fall back to Activity Monitor (search for "Electron") or pkill -f mini-tanjiro.

Tech stack

• Electron + TypeScript + electron-vite + React