RunCat for GNOME Shell: a top bar cat that runs faster as the CPU heats up

One animation, one percentage, and an explicit refusal to grow

RunCat for GNOME Shell provides a key-frame animation in the GNOME Shell top bar, and the animation speed changes depending on CPU usage. That is the entire feature, and the project is unusually direct about it.

The README has a section called Philosophy, and the first sentence of it is the design brief: RunCat is intentionally minimalistic, a running cat in the top bar and a CPU percentage next to it, nothing more. It goes on to say the extension is not meant to be a system monitor and will never grow dozens of settings, graphs, sensors or extra indicators, with the reasoning that there are plenty of other extensions for that. The closing note is friendly rather than defensive: if you already use a full-featured monitoring tool, the cat will happily run alongside it in your top bar.

That stance is unusual in a project of this kind, where the usual pattern is a small useful thing that accumulates options until it becomes a different product. RunCat is a GNOME Shell extension written in TypeScript, licensed GPL-3.0, and the author is Sergei Kolesnikov.

For a reader deciding whether to install it, the useful question is what you get in exchange for a slot in your top bar. The answer is a continuously running cat whose gait quickens with the processor load, plus the numeric percentage, so that you can tell at a glance whether something is spinning before you go looking for the cause.

The repository topics reflect the same narrowness: cats, cpu-monitoring, gnome, gnome-shell, gnome-shell-extension and proc-stat.

Installing from the extensions portal, or from a release ZIP

The recommended route is the GNOME Shell Extensions page, and the README justifies that choice on practical grounds, since it does not require the build dependencies for installation.

If you would rather not rely on the portal, there is a release ZIP route. Download `[email protected]` from the releases section and install it with:

$ gnome-extensions install path/to/[email protected] --force

The `--force` flag is there because you are likely replacing an existing copy, and the file name is fixed by the extension UUID.

The source route needs npm, and the README gives the sequence as cloning the RunCat repository, navigating to the cloned directory and running:

$ npm i # one time only
$ make install

The `npm i` step is marked as a one time only operation because it installs the JavaScript dependencies, and `make install` then does the packaging and placement. There is no `pip`, no `cargo` and no manual copying of files into a directory, which is the main convenience of the make-driven approach.

After installation there are two steps. First, restart the GNOME Shell by logging out and logging in. Second, enable the extension, either through GNOME Extensions by opening RunCat and setting it on, or from a terminal with `gnome-extensions enable [email protected]`.

For Linux specifically, note that there is no Linux note to make here, since GNOME Shell only runs on Linux. The macOS counterpart is a separate project by Takuto Nakamura, and the README credits that project and its cat images.

Where the preferences live, and why dconf is the honest answer

The extension exposes its settings in the usual GNOME ways, and the README lists them. You can right-click the extension button in the top bar and choose Settings, or open GNOME Extensions and use the settings icon for RunCat, or use the same control on the RunCat page in the GNOME Extensions portal.

The fourth option is the most interesting for anyone who wants to know exactly what the extension stores, because it bypasses the UI entirely and lists the settings tree directly with the `dconf list` command against the path `/org/gnome/shell/extensions/runcat/`.

The `dconf` path is the one to reach for when you are managing a fleet of machines, or when you want to confirm what a configuration actually is rather than infer it from a preferences dialog.

The Makefile shows where the underlying schema lives, as `src/schemas/org.gnome.shell.extensions.runcat.gschema.xml`, which is the standard GSettings schema location for a GNOME extension and confirms that preferences are stored through the GSettings and dconf mechanism rather than in a custom file.

The Makefile also names the extension UUID as `[email protected]` and the distribution archive as `$(UUID).shell-extension.zip`, so the same identifier appears in the install command, the enable command and the packaging target. That consistency is a small sign of a project where the build and the docs are kept in step.

How the build works, and where TypeScript fits

The build is driven by a Makefile whose default goal is `build`, and the target is a distribution archive rather than a bare install.

The pipeline has four stages. The TypeScript sources under `src/` are compiled with `tsc` to JavaScript under `.build/`, with the package script `build:compile` running `tsc --project tsconfig.json`. The compiled output is then run through ESLint in fix mode by `build:prettify`, which invokes `eslint --fix` over the `.build/` directory with two rules turned off for the generated files. The translatable strings are extracted into a gettext template, and finally `gnome-extensions pack --force` assembles the archive, adding the compiled sources, the stylesheet, the metadata file, the resources directory, the licence file, the translation directory and the settings schema.

The `gnome-extensions pack` invocation is the standard GNOME packaging tool, and the flags show exactly what goes into the extension: `--extra-source` for the built JavaScript, the stylesheet, `src/metadata.json`, `src/resources` and the `LICENSE`, `--podir=./po` for translations and `--schema` for the GSettings schema.

The dependency list in `package.json` explains the technology choices. The `@girs` packages provide generated TypeScript typings for the GNOME platform libraries, including `@girs/gnome-shell` at 50.0.4, `@girs/gtk-4.0`, `@girs/adw-1`, `@girs/gjs`, `@girs/glib-2.0`, `@girs/gio-2.0`, `@girs/gobject-2.0`, `@girs/clutter-18` and `@girs/st-18`, plus `@girs/gtop-2.0` for the GTop library that provides system statistics such as CPU usage. The `gtop` bindings are the mechanism behind the CPU reading, and the `proc-stat` topic on the repository points at the same thing from the other end, since the Linux `/proc` statistics are where the numbers come from.

The build is a TypeScript to JavaScript to GJS pipeline, with `gjs` being the JavaScript engine GNOME Shell itself runs on.

Developer commands, and the one that needs GNOME 49

The README documents a small set of commands for contributors, and they are worth reading because they show what the project considers testable.

Project JavaScript dependencies must be installed first with `npm i`. After that there are three test scripts and one make target. The `npm run test` command runs all available tests, `npm run test:typecheck` checks types, and `npm run test:lint` lints project files. In the `package.json` these are wired as `test:lint` running `eslint src/`, `test:typecheck` running `tsc --project tsconfig.json --noEmit`, and `test` running the lint and typecheck scripts in sequence.

That is worth pausing on. The test suite is a lint pass plus a TypeScript type check, and there is no unit test file for the animation logic in the documented commands. For a small extension whose entire behaviour is one animation driven by a CPU reading, that is a defensible choice, but it does mean the correctness of the CPU to animation-speed mapping is not covered by an automated test you can point to.

The fourth command is the interesting one. `make spawn-gnome-shell` spawns a nested GNOME Shell session to test the extension interactively, and the README states that it requires GNOME 49 or later and the `mutter-devkit` system package. This is the practical answer to the hardest part of GNOME extension development, namely that you normally have to log out of your session to see a change to an installed extension. A nested session avoids that, at the cost of needing a recent GNOME and a system package that most users will not have installed.

The repository also carries a `.eslintrc.json`, a `.prettierrc`, a `.editorconfig` and a `tsconfig.json`, so the formatting and typing rules are pinned in the tree, and `CONTRIBUTING.md` is required reading before opening a pull request.

Translations are maintained as a duty, not a convenience

The translation workflow is documented in more detail than most projects bother with, which says something about the project's international user base.

The `make translations` command extracts translatable strings and updates existing translations, and the README asks you to run it before pushing changes. It is composed of two make targets, `make po/messages.pot` to extract the translatable strings and `make po/*.po` to update the existing translation files. The Makefile shows the extraction is done with `xgettext`, run twice, once over the TypeScript sources `src/indicator.ts` and `src/prefs.ts` and once over the GTK user interface files in `src/resources/ui/`, with the package version read from `src/metadata.json` using `jq`.

Starting a new language is a single `msginit` call, given as `msginit -i po/messages.pot -l <locale> --no-translator -o po/<locale>.po`, with worked examples for Spanish and for Spanish (Argentina) using the `es` and `es_AR` locale codes.

The catch is stated plainly: you should be prepared to maintain that translation in future versions of the extension. A gettext catalogue is a file that goes stale, and the project is asking translators to own that. It is a fair request for a project whose cost of translation is close to zero but whose upkeep cost is real.

The Makefile completes the picture with a `po/%.po` rule that runs `msgmerge --update` against the extracted template, so updating existing catalogues is a make target rather than a manual step.

Maintenance, the version numbers and the GPL choice

The project is not archived, and the release history shows regular version bumps: v37 on 2026-09-17, v36 on 2026-08-28 and v34 on 2026-08-24, with the last push on 2026-09-17. The version numbers are plain integers rather than semantic versions, which fits an extension whose releases are consumed by a portal that expects a version string, and it also means there is no major and minor axis to reason about.

The regularity is the main signal that the extension is still being worked on. GNOME Shell extensions have a habit of decaying silently when a shell release changes the API they hook into, and a project that has shipped three releases in under a month in 2026 is not one that has been abandoned. The `typescript` dependency is pinned at `~6.0.3` and the GNOME Shell typings at 50.0.4, which tells you the extension is being developed against a current GNOME Shell.

The licence is GPL-3.0, and the `LICENSE` file is included in the packaged archive by the make target, which is what the GPL requires for a distributed work. For a user, GPL-3.0 on a desktop extension carries no practical obligation. The one point worth raising is for anyone who plans to bundle the extension into a larger product or a commercial image: GPL-3.0 is a strong copyleft licence with a patent clause, and the obligations differ from the permissive licences most commercial desktop software uses. This is a description of the licence terms as stated, not legal advice.

Finally, the honest limit. The extension shows one number, CPU usage, and by its own philosophy it will not show you more. It is a peripheral awareness tool. If you need to know which process is eating the CPU, how memory is distributed, or what the disk is doing, this is the wrong tool, and the README is clear that the cat will happily run next to a full-featured monitoring tool that answers those questions.

Editorial conclusion

Adopt RunCat when you want one glanceable indicator of machine load that does not add a panel, a graph or a settings page to your GNOME session, and when you are comfortable with a GPL-3.0 extension that reads CPU usage and nothing else. Do not adopt it as a monitoring tool, because the project states plainly that it is not meant to be a system monitor and will not grow graphs, sensors or extra indicators. Before you install, read the extension's settings through dconf if you care about what it touches, check that your GNOME Shell version is one the extension supports, since the interactive test workflow calls for GNOME 49 or later, and note that the install-from-source route needs npm and a make-driven build that packages the extension with gnome-extensions pack.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. win0err/gnome-runcat on GitHub