BetterSlack

Eight themes, seventeen plugins, one keystroke

A theme is CSS and nothing else, so several can run at once. When a look needs behaviour CSS cannot do, the theme names a plugin in requires and the panel offers to switch it on — Discord Dark does exactly that, and brings the member column and the account strip with it:

⌘K, and everything is one keystroke away

Slack's quick switcher with everything Slack has no idea about in the same list: any conversation, anyone in the workspace (through Slack's own search, not just your open DMs), every mod's commands, and a plugin's settings — / for actions, @ for people, # for channels.

A theme builder whose preview is Slack

Two colours become twelve roles across all four of Slack's token families, hovering a colour outlines what it paints, and pointing at anything in the app shows the tokens behind it. It writes ordinary CSS you can commit.

Install

git clone https://github.com/AirOne-dev/BetterSlack.git
cd BetterSlack
./install.sh                 # macOS and Linux

On Windows, in PowerShell:

git clone https://github.com/AirOne-dev/BetterSlack.git
cd BetterSlack
powershell -ExecutionPolicy Bypass -File .\install.ps1

No git? You do not need it. git clone is one way to get the folder and nothing here needs the other things git can do -- the installer never calls it, and an install updates itself from GitHub's tarball rather than by pulling. Download the ZIP from the green Code button, unpack it, and run the same installer; or in a terminal:

curl -fsSL https://codeload.github.com/AirOne-dev/BetterSlack/tar.gz/refs/heads/master | tar xz
cd BetterSlack-master
./install.sh

# Windows
Invoke-WebRequest https://codeload.github.com/AirOne-dev/BetterSlack/zip/refs/heads/master -OutFile bs.zip
Expand-Archive bs.zip -DestinationPath .
cd BetterSlack-master
powershell -ExecutionPolicy Bypass -File .\install.ps1

That is the whole thing. Nothing has to be installed first -- not Node, not pnpm, not git. The installer uses a Node already on the machine if there is one recent enough and downloads one into ~/.betterslack/runtime if there is not, verifies it against the checksum nodejs.org publishes, builds, and puts the result in ~/.betterslack/app.

BetterSlack itself is about 6 MB. A Node it had to download is a further ~190 MB and is kept to itself — nothing is added to your PATH and no other project sees it. Nothing is written outside your home directory, with one exception the installer announces before it happens: on macOS the app is copied into /Applications, which needs a password only on a Mac whose owner is not an administrator.

Then delete the clone if you like. The install does not refer back to it. Keep it only to work on BetterSlack itself.

Afterwards BetterSlack is an ordinary application: Spotlight, the Dock, your login items, the Start menu, your desktop's applications menu. Starting it restarts Slack with your mods attached and keeps running for as long as Slack does. Nothing is enabled on a fresh install -- open the panel and pick what you want from Browse.

To update, use the panel's About tab, or run ./install.sh again from a newer copy of the folder, which also moves you to a newer Node. To uninstall, delete ~/.betterslack and the launcher (/Applications/BetterSlack.app, or ~/.local/bin/betterslack and its .desktop file, or the Start menu shortcut).

Two notes for macOS. The first launch needs right-click -> Open, because the app is unsigned. And a C compiler (xcode-select --install) is worth having before you run the installer: without one the app still launches, but macOS refuses it access to ~/Downloads, which is where a mod saves a file.

→ docs/getting-started.md points at the three: running it, writing a plugin, writing a theme -- each with testing and shipping at the end.

What is in the catalogue

Themes — Midnight (a deeper dark), Aurora (frosted glass over a drifting gradient), Cocoa (warm light), Terminal (monospace phosphor), Discord Dark and Discord Light (Slack rebuilt as Discord, colours sampled from the real client), Windows XP (Luna, in Blue, Olive Green or Silver, with an Aero switch), Focus Rings.

Plugins — Command Palette (⌘K, with / @ # to narrow it), Theme Builder, Motion (Slack with the frames in between), Code Highlight (twenty-one languages, detected), Full Links (Slack stops shortening your URLs), Member Sidebar, Sidebar Account Strip, Quote Reply, Copy Message Link, Composer Character Count, Channel Notes, User Inspector, Avatar Downloader, DevTools, History (everything Slack changes and never tells you about -- edits, deletions, reactions taken back, renames -- on one page you can search and sort), Demo Mode (a Slack full of people who do not exist, for when you are screenshotting or sharing your screen), Custom Sounds (your own files in every sound list of Preferences → Notifications).

Each has a page in the panel — what it is for, in your language, with a picture and its settings:

Several themes can run at once. Terminal is the exception: it restyles through * selectors, so run it on its own.

A mod carries its own version and updates on its own, so a fix to one theme does not mean updating the whole project. The panel also updates BetterSlack itself, from GitHub, keeping your mods and settings.

If something goes wrong

Nothing is applied after a run that never reported itself healthy — a mod that wedges the renderer cannot lock you out. A mod that throws on start is named on its own row, and is skipped after two failures until you switch it off and on again.

To start with every mod off deliberately, run the launcher with --safe:

# Linux: the command the installer put on your PATH
betterslack --safe

# macOS: the app has no way to pass a flag, so run the loader directly, with
# the Node the installer recorded
"$(cat ~/.betterslack/app/node-path)" ~/.betterslack/app/bin/betterslack.mjs --safe

If it does not start at all, the log says why. It is at ~/Library/Logs/BetterSlack.log on macOS and ~/.betterslack/betterslack.log on Linux and Windows.

How it works

BetterSlack attaches to Slack over the Chrome DevTools Protocol and injects a runtime into the renderer. It never modifies Slack.app, so Slack updates cannot break your install.

It talks to Slack over --remote-debugging-pipe, not --remote-debugging-port. The port version opens an unauthenticated TCP listener that any local process can use to drive your Slack session; the pipe uses two file descriptors handed over at spawn time, and nothing listens on the network:

$ lsof -nP -iTCP -sTCP:LISTEN -a -p $(pgrep -x Slack)
$                     # nothing

That does not protect against a program already running as your user — nothing in user space can. Mods are active only while the loader runs, and Slack has to be started by it.

Writing a mod

Mods live in mods/, one folder each, picked up live with no rebuild:

mods/themes/<id>/mod.json    + theme.css
mods/plugins/<id>/mod.json   + index.js  + test.mjs

A theme is CSS. A plugin is an ES module exporting start(api) — and most of what a mod needs is one call:

export default {
  start(api) {
    api.slack.addToolbarButton('channelHeader', {
      id: 'hello', label: 'Say hello', icon: '<svg …>',
      onClick: () => api.ui.toast('Hello', { variant: 'success' }),
    });
  },
};

entry in mod.json is only where the app starts reading: a mod can be as many files as it wants, imported relatively (./lib/x.js, or @import './tokens.css' in a theme) from inside its own folder.

Documentation

Getting started	The three tracks: run it · write a plugin · write a theme
API reference	Every entry, with an example
Theming Slack	The four colour token families, traps, recipes
Contributing	Review rules and the PR checklist

Development

Everything below is for working on BetterSlack itself, and it is the only place in this project that asks anything of your machine. Using BetterSlack needs install.sh; changing it needs a checkout, Node and pnpm.

git clone https://github.com/AirOne-dev/BetterSlack.git && cd BetterSlack
pnpm install && pnpm build
pnpm start                        # launch Slack with mods, from this checkout

pnpm, not npm: esbuild fetches its platform binary in an install script, and pnpm-workspace.yaml is what allows that script to run. If you have no pnpm, corepack enable gets you one on a Node older than 25 (later ones ship no Corepack), and npm i -g pnpm on any of them.

pnpm build is not optional: the loader and the runtime are TypeScript and dist/ is not committed. Run it after cloning and after any change under src/ — never for a change under mods/, which hot-reloads into the running client.

pnpm check                        # everything below that CI would run, in one go
pnpm dev                          # rebuild on change
pnpm new-mod plugin my-plugin "What a user gets"   # a mod that already passes
pnpm test                         # every mod's tests
pnpm test -- <id>                 # one mod
pnpm test:core                    # loader and runtime unit tests
pnpm test:live                    # boot the real Slack and grade what loaded
pnpm check-structure              # is each mod loadable
pnpm validate-mods                # manifests
pnpm registry                     # regenerate mods/registry.json, then commit it
pnpm typecheck
pnpm release patch                # bump, write CHANGELOG.md, tag

pnpm site:dev                     # the presentation site, live at localhost:4321
pnpm site                         # regenerate site/data.js from the catalogue

Mods in ~/.betterslack/mods/ shadow the repo copies, which is handy for iterating on something already merged.

License

MIT