guides

every tool ships an install.sh that copies files into your home directory, adds a launcher, and prints which optional backends it found. it downloads nothing from outside your distro's repos, and it backs up anything it replaces.

install what you want

clone, dry run, run. the same three steps for all of them.

clone one tool

$ git clone https://github.com/Maidware-Project/Maid-AU
$ cd Maid-AU

see what it would do
```
$ bash install.sh --check
```
do it
```
$ bash install.sh
```

the installers don't know about each other. there's no suite-wide installer, and removing one tool leaves the rest alone. everything goes under your home directory - ~/.local/bin and friends - never into /usr.

bind a key to the runner

the suite never touches your shortcuts. those are yours, they stay on your machine. on plasma:

settings → keyboard → shortcuts → custom shortcuts
add → command/url, command: ~/.local/bin/maid-runner
pick a key. meta+space is the usual one

check that they can see each other

$ update-all.sh --check   # what would update, nothing changed
$ maid-runner             # empty query on the maid tab lists every action
$ maidshare --check       # which send backends are available

tool by tool

files & sharing shell kde connect · adb · qr

MaidShare

it tries the backends in order and takes the first one that works. kde connect is best, if the phone is paired on the same wifi; usb/adb needs no network at all; the http fallback puts up a temporary wifi page with a qr code. a popup says which one it used, so check it before you walk away.

$ bash install.sh              # copy + icon, reports backends
$ maidshare file.pdf           # auto-picks
$ maidshare --via adb file.pdf # force one
$ maidshare --receive          # phone → pc: qr + browser upload

hand it several files or links at once and it fans them out
receive side is token + https + expiry by default
dolphin right-click: send, or send via qr
optional: kdialog or zenity for popups, qrencode for qr codes

full readme →

launcher python · qt rofi fallback

Maid Runner

type, enter. tab cycles five sources, and the maid one is the only search box that knows what's going on with your system: earbuds state, pending updates, share targets.

$ bash install.sh   # app + six rofi themes + launcher
$ maid-runner

applications - read from the same xdg menu data plasma shows. respects NoDisplay/Hidden/TryExec, flatpak exports included
maid - every action in the suite. leave the query empty to list them all
run - binaries on your PATH, always opened in a terminal so the cli ones work
calculator - an ast allowlist, never eval. enter copies the result
web - yt, wiki, gh and g/ddg prefixes, bare urls, duckduckgo for everything else

no pyqt6, or no display? it runs the rofi fallback with one of six themes: maid-dark, maid-light, maid-tokyo, maid-mallow, maid-green, maid-blue.

full readme →

system updates shell zypper · dnf · pacman · apt

Maid AU

system packages, flatpak and firmware in one run. the backend comes from /etc/os-release, so it just works on your distro; set UPDATE_PM= to force a different one.

$ bash install.sh              # deps (sudo) + copy + launcher
$ update-all.sh --check        # dry run, change nothing
$ update-all.sh                # real run - snapshots first
$ UPDATE_PM=pacman ./bin/update-all.sh --check

a snapshot before and after every real run
prints PARTIAL when one layer failed but the others didn't
warns when a reboot is needed. never reboots for you
a launcher too: system-updater, a terminal picker that holds off sleep while it runs

passwordless sudo is opt-in. by default the installer asks for your password like anything else. a NOPASSWD rule for the package manager is passwordless root in practice, so it only prints the safe version if you ask for it.

full readme →

audio shell pipewire · bluez

Maid BT

keep your normal bluetooth tool for pairing mice and keyboards. this one handles the earbuds routine: where the sound is right now, and moving it around without a fight.

$ bash install.sh                # asks for your mac + fallback sink
$ bluetoothctl pair <MAC>        # then: trust <MAC>
$ bluetooth-toggle.sh on         # sound moves to your earbuds
$ bluetooth-toggle.sh release    # hand buds to phone, back is instant
$ bluetooth-toggle.sh off        # disconnect + radio off

release is the everyday one - the buds stay half-connected so coming back is instant. set MULTIPOINT=1 once if yours connect to two devices
the watcher connects the buds when they show up and parks the sound on your speakers when they disappear
optional maid watcher: on a call it pauses music, mutes discord, and puts both back when you hang up. warns at 25% and 12% battery
a tray widget with pc / phone / off buttons

also optional, and off unless you turn them on: the phone remote (phone/, macrodroid or tasker), pausing ldac when the battery is low, and a wireplumber fix for a start that lags a second behind.

full readme →

repair shell check · fix

Maid Helper

each module has two modes. check tells you whether it's healthy; fix repairs what it safely can and verifies afterwards. exit 0 means healthy or fixed, exit 2 means it still needs a look.

$ ./bin/mod-flatpak.sh check
$ ./bin/mod-flatpak.sh fix

# the four modules
mod-firmware.sh  # fwupd present? firmware updates possible?
mod-flatpak.sh   # flathub remote configured?
mod-gamepad.sh   # xbox/ps/switch/8bitdo pads missing a driver
mod-gpu.sh       # nvidia on the open stack, unblacklisted

it will not install proprietary drivers. ever. no consent flag, and it won't print the commands for you either. the gpu module only unblacklists nouveau and rebuilds initrd. removing nomodeset from your bootloader stays a manual step, printed out for you.

root only where a fix genuinely needs it. the flathub remote runs at user level, no sudo involved.

full readme →

what each tool needs

everything optional is detected automatically. if a backend is missing the tool says so and moves to the next one. it never installs anything you didn't ask for.

MaidShare

kde connect backend: archkdeconnect debian/ubuntukdeconnect fedorakdeconnect opensusekdeconnect-kde
usb/adb backend: archandroid-tools debian/ubuntuadb fedoraandroid-tools opensuseandroid-tools
qr wifi page: all fourpython3openssl+ qrencode
popups and pickers: all fourkdialog or zenity

Maid Runner

full qt app: all fourPyQt6
rofi fallback: all fourrofi

no pyqt6, or no display? it runs the rofi fallback instead, which needs only rofi.

Maid AU

packages, firmware, notifications: archflatpakfwupdlibnotify+ pacman-contrib debian/ubuntuflatpakfwupdlibnotify-bin fedoraflatpakfwupdlibnotify opensuseflatpakfwupdlibnotify-tools

Maid BT

bluetooth: archbluezbluez-utils debian/ubuntubluezbluetooth fedorabluez opensusebluez
rfkill: archutil-linux debian/ubunturfkill fedorarfkill opensuseutil-linux
notifications: archlibnotify debian/ubuntulibnotify-bin fedoralibnotify opensuselibnotify-tools
audio control: archlibpulse debian/ubuntupulseaudio-utils fedorapulseaudio-utils opensusepulseaudio-utils
python3: archpython debian/ubuntupython3 fedorapython3 opensusepython3
phone pings, optional: archkdeconnect debian/ubuntukdeconnect fedorakdeconnect opensusekdeconnect-kde

Maid Helper

fwupd for the firmware module, flatpak for the flathub check, pciutils so gpus are visible. the opensuse controller packages come from the updater.

arch: add pacman-contrib if you want checkupdates in Maid AU - it checks for updates without touching your local database.

backups and dry runs

why you can leave these running without watching them.

dry run first

almost everything takes --check. it prints what it would do and exits without touching a file.

$ bash install.sh --check
$ update-all.sh --check

timestamped backups

a file an installer is about to overwrite becomes <name>.bak-<timestamp> first - but only if the contents actually differ, so reinstalling doesn't fill your home directory with copies.

snapshots around updates

Maid AU takes one before and after a real run. between that and the dry run you can see the whole update coming, and roll back if the summary ends up PARTIAL.

manual stays manual

reboot warnings - printed, never performed
bootloader edits - printed exactly, run by you
firmware updates - need root and a reboot, so they're described, not run
proprietary drivers - not offered at all

no downloads, ever

the installers fetch nothing. dependencies come from your own package manager. no piping a script from some server into bash.

troubleshooting

where are the logs?

Maid AU → ~/.local/share/update-all.log
MaidShare → force a backend so you see its output directly
the Maid BT watcher → journalctl, or the tray widget if you started it that way

do these install background services?

MaidShare, Maid Runner, Maid AU and Maid Helper don't - they run when you call them and exit. Maid BT ships optional systemd units for its watcher and phone listener. maid watcher runs as a normal user process through xdg autostart, so it doesn't care which init you use.

how do i test a change safely?

each repo carries a suite, run from the repo root:

$ bash tests/run.sh

they use stub farms and overridable test seams, so nothing on your real system is touched unless you say so. ci runs the same suites.

something didn't work

re-run the installer with --check and read the backend report
run the module in check mode - exit 2 means it still needs attention
open an issue with that output. every script prints plain english lines for exactly this

can i use one without the others?

yes. they're separate packages with separate installers. the parts that reach across the suite - the runner's maid tab, the helper handing gamepad work to Maid AU on opensuse - just quietly do less when something's missing.

still stuck? open an issue. links are on each tool on the tools page.

that's it

back to quick start github