Plugins are small additions you choose: a few words in the bar, a key, a Super+m entry, sometimes a program that runs in the background. They come from their own repository, vikix-plugins, at a version Vikix has checked, and nothing is added until you ask for it. This page is a guide to each one: what it does, how to add it, how to use it, where it keeps things, and what to do when it doesn’t work.
vikix plugin list # every plugin, yours marked vikix plugin add NAME # says what it runs, needs and changes, asks, then adds it vikix plugin remove NAME # runs its remove; your settings for it stay vikix plugin off NAME # stop loading it (vikix plugin on NAME brings it back) vikix plugin safe # the next login loads none
A plugin’s keys and bar take effect at once. If a plugin’s key is one Vikix or a web app of yours already has, the plugin’s wins, a message names both, and vikix doctor lists it until one moves; removing the plugin gives the key back. Vikix’s tests check the plugins at its pinned version for such clashes before a release. Each one’s settings are yours, in ~/.config/vikix/plugins/NAME/, copied once and never overwritten. A plugin that keeps a record of what it found (a flight search, a meeting joined) puts it in the record store, vikix records (README), where you can search it.
A plugin’s commands (inbox, repos, flights ...) are on your PATH while it’s added, each with a man page made from what its -h prints: man inbox. man vikix lists them after Vikix’s own, and removing the plugin takes its pages away.
A plugin’s code runs inside the desktop with all its power, like your user.lisp: add the ones you trust. If one ever stops the desktop from starting, log in on a text console (Ctrl+Alt+F2), run vikix plugin safe, log in again, and switch the culprit off.
A plugin needn’t come from the plugins repository: a project of your own (or someone’s you trust) that keeps a plugin folder in the plugins’ shape can be added from its repository, at a commit you choose.
vikix plugin add budanth --from https://github.com/you/budanth # at its newest commit vikix plugin add budanth --from ~/src/budanth --at v0.3 # a folder on this machine, at a tag vikix plugin pin budanth # move it to the newest commit vikix plugin pin budanth 7903146abc... # or to one you name vikix plugin status # each one's repository and commit
The plugin is the folder named after it in that repository (budanth/ in the budanth repository), or the repository itself when its manifest is at the top. Vikix fetches the repository at that commit into ~/.local/share/vikix/plugins-from/NAME and writes a line budanth from REPO at COMMIT in your plugins.list; vikix update keeps the checkout at that commit, and nothing moves it but vikix plugin pin. Everything else is as for any plugin: add shows what it runs and changes and asks, its programs get man pages, its settings are yours, off, on and remove work the same (remove takes the checkout away; your settings stay). The difference is trust: Vikix has checked the plugins at its own pin, not these, and add says so. A name the plugins repository has can’t be taken from elsewhere.
The keys at a glance. A plugin’s keys are all on Super+Alt, with Shift for a second one on the same letter: that is where everything beyond the six main apps opens (the rule for keys).
Plugin: agent-waiting
What it does: Go to the agent waiting for you, or pick among several
Plugin: ai-usage
What it does: How much of your Claude plan is used
Plugin: next-meeting
What it does: Join the meeting on now, or the next
Plugin: next-meeting
What it does: The coming week’s meetings
Plugin: flights
What it does: Search flights
Plugin: repos
What it does: Which projects need pushing, pulling or committing
Plugin: inbox
What it does: A note into your inbox
Plugin: inbox
What it does: A note quoting what you selected
Plugin: inbox
What it does: Sort the inbox
You start Claude Code, or Codex, on a task in one window and get on with something else in another. When it needs you, or has finished, the bar says which session, where it is and whether it asks something of you; a notification says what; and one key takes you there.
Add it: vikix plugin add agent-waiting. It adds five hooks to Claude Code’s settings, ~/.claude/settings.json (a copy of the file is kept first). A Claude Code session already running takes them once you type /hooks in it (it asks you to look them over), or when it starts again. After an update that brings new hooks, add it again: it shows what it changes, asks, and adds only what isn’t there. Where Codex is set up (~/.codex), it also puts Codex’s notify setting in ~/.codex/config.toml (a copy kept first), which runs the plugin when a turn ends; a notify of your own is left as it is, and said.
Use it:
asks: Esploro tags (3) in the bar, in the accent colour: the session called Esploro tags, on workspace 3, wants something of you. Either a dialog is open (a permission, a question with choices) and its work stands still, or it finished and its last words ask something: a question, or a step that is yours (a line that starts You:).
done: Fix the bar (1), quieter: that session finished and asks nothing.
asks: Esploro tags (3) +1, done 2 is two that ask and two that finished. The one named is the one to go to first: an open dialog before a question, the oldest first.
[ ! ] Action Required at the front of its window’s title, and the plugin reads that: asks in the bar, a notification, Super+Alt+w, with nothing to set up. When a turn ends, its notify setting tells the plugin, with the last message: done, or asks when it ends on a question. Nothing of Codex’s says you answered, so a done stays until you look at the window.
Esploro tags asks (workspace 3), and under it what it asks (Bash: Install the build, or its question). Finished sessions stay in the bar only. To have a notification for those too, or none at all, put one of these in ~/.stumpwm.d/user.lisp:
(setf *agent-waiting-notify* :all) ; finished sessions too (setf *agent-waiting-notify* nil) ; the bar only
Where things are: a small file per terminal window in ~/.local/state/vikix/agents/: the state and the time, the folder, and the line of what was said.
When it doesn’t work:
/hooks in it, or start it again.
PermissionRequest) isn’t in your settings. vikix plugin add agent-waiting again adds it.
You:. That is all it goes by.
notify setting isn’t in ~/.codex/config.toml (the plugin was added before Codex was set up, or the file has a notify of its own). vikix plugin add agent-waiting again adds it; a Codex session already running takes it when it starts again. One that waits for your yes is seen anyway, by its title.
Remove it: vikix plugin remove agent-waiting takes the hooks out of ~/.claude/settings.json and the notify setting out of ~/.codex/config.toml again, and leaves your other settings as they were.
With a Claude Pro or Max plan, Claude Code knows how much of the plan you’ve used: the 5-hour window and the week. This puts it in the bar, so you see a limit coming.
Add it: vikix plugin add ai-usage. Claude Code hands those numbers only to its status line (the line under its prompt), so the plugin becomes the status line. If you already had a status line of your own, it keeps running, through the plugin, and comes back as it was when you remove it.
Use it:
plan 24% 41% in the bar: the 5-hour window, then the week. The accent colour from 75%, the alert colour from 90%.
plan 24% 5h · 41% week.
Where things are: the numbers in ~/.local/state/vikix/ai-usage. Every 15 minutes at most, a record in the record store: vikix records list ai-usage is your use over days and weeks.
When it doesn’t work:
Remove it: vikix plugin remove ai-usage puts back the status line you had before (or none).
Your next meeting in the bar, with how long until it starts; a notification five minutes before; and one key to join it, a Teams meeting in the Teams web app.
Add it: vikix plugin add next-meeting. It installs two small Python libraries for reading calendars (it asks first). Then give it your calendars: each one’s private link, an address that lets the plugin read that calendar.
next-meeting add work # asks for the link; what you paste isn't shown next-meeting add home next-meeting calendars # your calendars, by label (never the secret part) next-meeting forget home
Where each calendar’s private link is:
A private link is a key to that calendar: anyone who has it can read it. The plugin keeps them in a file only you can read and never prints them. If one ever gets out, reset it where you got it.
Use it:
Standup 14:30 in 12m in the bar, for the next meeting within four hours; now: Standup while it’s on, in the accent colour.
vikix webapp add teams), a Meet link in the Meet one when you have it, anything else in your browser.
next-meeting list in a terminal: the same week.
Where things are: the links in ~/.config/vikix/plugins/next-meeting/calendars (600); the calendars as last read in ~/.cache/vikix/next-meeting/; what the bar shows in ~/.local/state/vikix/next-meeting. Each meeting you join is a record: vikix records list next-meeting.
When it doesn’t work:
next-meeting calendars). next-meeting fetch reads them all now and says what went wrong with one.
Remove it: vikix plugin remove next-meeting. Your calendar links stay in the settings folder until you delete it.
Type a line like DXB LHR 12 Nov, back 20th and see the flights, cheapest first, with the quickest marked. Enter opens that search on Google Flights, where you book (there or on the airline’s site): the plugin itself never books anything. It can also watch a route and tell you when it gets cheaper.
Add it: vikix plugin add flights. It makes a Python of its own with fast-flights, the library that reads Google Flights (a minute, once). Then set your currency and home airport in ~/.config/vikix/plugins/flights/settings:
currency = AED home = DXB
With a home airport, LHR 12 Nov is enough.
Use it:
back DATE for a return. Also business, premium, first, direct, 2 adults, 1 child. Dates as you’d write them: 12 Nov, Nov 12, 2026-11-12; back 20th for the same month.
flight cheaper in the bar until you look (a click, or Super+m, Flights: the watched ones that got cheaper).
flights "LHR JFK 3 Dec business" # the list, in the terminal flights watch "DXB LHR 12 Nov" # watch a route flights watching # what's watched, and the cheapest seen flights unwatch 2 # stop watching the second
Where things are: the watched routes in ~/.config/vikix/plugins/flights/watched; the prices seen in ~/.local/state/vikix/flights/. Every search with its results, and each watched route’s price at each check, are records: vikix records search singapore, vikix records list flights --kind price.
When it doesn’t work:
direct in the line asks for only those.
currency = in the settings.
Remove it: vikix plugin remove flights removes its Python too. Your watched routes stay in the settings folder.
Which of your git projects have changes not committed, commits not pushed, commits on GitHub not pulled, tags not pushed, or stashes left behind. The bar keeps count; one key opens a terminal with the details and the commands to run.
Add it: vikix plugin add repos. It looks at every project in ~/src, and at ~/.emacs.d and ~/.dotfiles. To change which, see the settings below.
Use it:
git 2 in the bar: two projects need something. In the accent colour when something is waiting to be pushed or pulled.
repos fetch asks GitHub now what’s new (it does every 30 minutes by itself).
repos push pushes every project that needs it, commits and tags (repos push esploro just that one). A project another pins goes first: Esploro and the plugins before Vikix, whose files name the commit of each it builds. It won’t push Vikix while it pins a commit GitHub hasn’t got, since every install that updated would then fail to fetch it. When GitHub has moved on, it brings those commits in first and pushes again.
repos pull brings in GitHub’s new commits for every project, yours put on top of them. It asks over HTTPS, so no passphrase.
repos ship is repos push, then vikix update core: the desktop runs what you pushed. The step after a release.
repos update updates the whole system (vikix update: Void’s packages, Vikix, your tools).
repos also says when a project is past the commit Vikix pins (2 past vikix's pin): it has work Vikix doesn’t use yet.
It never pushes, pulls or merges unless you ask, and asking GitHub never needs your SSH key’s passphrase: it goes over HTTPS, through gh’s login when you have one.
Settings (~/.config/vikix/plugins/repos/settings):
roots = ~/src # folders whose projects it looks at
extra = ~/.emacs.d ~/.dotfiles # single projects elsewhere
skip = # projects to leave out, by folder name
push = gpush {path} # the commands it suggests, if not git's own
pins = esploro:~/src/vikix/bin/vikix-esploro vikix-plugins:~/src/vikix/bin/vikix-plugin
# PROJECT:FILE, the file holding NAME_COMMIT=<sha>
When it doesn’t work:
gh auth login to answer for a private project.
terminal = kitty in the settings names another.
Remove it: vikix plugin remove repos.
A key over whatever you’re doing opens a small box; what you write, or say, lands in your Org inbox in Dropbox, which your phones see too. Later, one key sorts the inbox into your notes files. This has a guide of its own: Your notes.
Add it: vikix plugin add inbox. It needs Emacs (vikix add emacs) for the box; without Emacs, the box is a one-line rofi prompt.
Use it:
3 to move note 3, t 3 to-do or not, d 3 delete), Enter does it. inbox sort --undo puts it all back.
inbox add "call the bank" from a terminal.
notes-sync (or Super+m, Notes: sync with Dropbox): your notes up to Dropbox now. It starts Dropbox if it isn’t running, takes the notes folder back into this laptop’s sync if selective sync left it out, and waits until Dropbox says it’s up to date.
Where things are: the notes in ~/Dropbox/notes/; the inbox is inbox.org (another file: file = ~/notes/inbox.org in ~/.config/vikix/plugins/inbox/settings); the copies each sort keeps in ~/.local/state/vikix/inbox/sorts/.
When it doesn’t work:
vikix update brings the fix.
vikix ai key set todoist once, with the token from Todoist’s Settings, Integrations, Developer.
Remove it: vikix plugin remove inbox. Your notes stay where they are.