What Vikix put on your machine, where, and whose it is. Three kinds of file:
vikix update replaces it. Don’t edit it; your change would be lost, and vikix update would stop, because it pulls with git pull --ff-only.
~/vikix/config/, then never touched again. Edit freely. These have a history: see undo.
ls -l tells the first two apart: Vikix’s files show -> /home/you/vikix/....
~/ ├── vikix/ the checkout: Vikix itself (see below) │ ├── .stumpwm.d/ │ ├── init.lisp Vikix's loads Vikix's layer, then rules.lisp and user.lisp │ ├── vikix/ Vikix's the layer: errors, theme, groups, registry, commands, windows, rules, viri, drawer, layouts, overview, resume, day, why, used, keys, help, webapps, modeline, plugins, rescue, door, swank-guard, swank, socket │ ├── rules.lisp yours your rules for the desktop: copied once, every example switched off; Super+Shift+t adds to it (rules.md) │ ├── user.lisp yours your StumpWM settings; loaded last, so they win │ └── modules/ stumpwm-contrib, cloned by 30-lisp (swm-gaps, ttf-fonts, ...) │ ├── .xinitrc Vikix's runs vikix-session inside dbus-run-session ├── .bash_profile yours with Vikix's marked blocks: PATH, read .bashrc, startx on tty1 ├── .bashrc yours with one marked block at the top that reads vikix.bash ├── .Xresources yours text size (Xft.dpi) and cursor size ├── .sbclrc yours loads Quicklisp (added by 30-lisp) ├── .slime-secret yours Swank's password (600): Emacs and vikix eval send it │ ├── .config/ │ ├── vikix/ │ │ ├── vikix.bash Vikix's aliases, prompt, fzf/zoxide/atuin setup │ │ ├── keyboard yours layout and XKB options │ │ ├── network/preferences.json yours discovery choice for each network (Network Office) │ │ ├── plugins.list yours the plugins you added (vikix plugin add); "NAME from REPO at COMMIT" is one from another repository, at the commit you pinned; "#off " in front, one switched off │ │ ├── tray yours the tray in the bar: on or off (vikix tray switches it), and the applets it starts │ │ ├── plugins/NAME/ yours your settings for plugin NAME (copied once) │ │ ├── obsidian yours vikix obsidian's vault, where its notes go, and the folders it leaves out │ │ ├── idle yours minutes before lock, dark screen, suspend (make it; see customize.md) │ │ ├── backup yours where backups go, and the reminder's days │ │ ├── backup-exclude yours what backups leave out │ │ ├── backup-password yours the backup password (never in snapshots) │ │ ├── secrets/ yours API keys, one file each (vikix ai key), and windows-password, your Windows account's (vikix windows apps); never in snapshots │ │ ├── ai yours which model Super+i uses: use=local, claude or codex, model=, translate_model=, effort=, languages= │ │ ├── agent yours which agent Super+a starts (vikix agent --default NAME) │ │ ├── dictation yours dictation's model: base.en, small or large-v3-turbo (vikix dictate models) │ │ ├── voice yours how the AI talks back: voice=, speak=, idle= (vikix voice) │ │ ├── notes yours the folder `note` reads: folder=, skip=, embed= (note index) │ │ ├── projects yours where `vikix project` looks: root=, depth=, logs= (copied once, all comments) │ │ ├── features yours the features you chose (vikix add, vikix remove, vikix features) │ │ ├── packages-skip yours packages you dropped (vikix pkg drop); updates leave them out │ │ ├── windows yours where the Windows VM's disk is │ │ ├── webapps yours your web apps: NAME URL [KEY] (vikix webapp) │ │ ├── docs-browser yours the browser for guides and docs, one word (make it; Nyxt without it, when installed) │ │ ├── docs-links yours your own links for the catalogue, a URL and its title a line (make it; listed, never fetched) │ │ ├── wallpaper yours a link to the picture you chose │ │ ├── wallpaper-off yours exists if you set the wallpaper with your own tool │ │ ├── titlebars-off yours exists if you turned the title bars off (Super+Ctrl+y) │ │ ├── gestures yours the touchpad's sweeps and the touchscreen's pan: fingers, distance, natural, pan (vikix gestures) │ │ ├── wallpaper-theme yours exists if the wallpaper follows the theme instead of cycling │ │ ├── wallpaper-minutes yours how often the wallpaper changes when cycling (vikix-wallpaper cycle MINUTES; 30 without it) │ │ ├── themes/ yours your own themes (NAME.theme, NAME.jpg) │ │ └── theme/ written each program's colours, and `current`, the theme you chose (`vikix theme`); GTK's and Qt's too: `mode` (dark or light), xsettingsd.conf, gtk4.css, qt6ct-colors.conf │ ├── alacritty/alacritty.toml yours imports ../vikix/theme/alacritty.toml │ ├── picom/picom.conf yours the compositor: shadows, fading, backend │ ├── dunst/dunstrc yours notifications │ ├── dunst/dunstrc.d/10-vikix-theme.conf written the theme's colours for dunst │ ├── rofi/config.rasi yours the launcher and menus │ ├── gammastep/config.ini yours night light times and colours │ ├── mimeapps.list yours which program opens which kind of file │ ├── fontconfig/conf.d/50-vikix-iosevka.conf Vikix's monospace means Iosevka │ ├── autorandr/ yours screen layouts, one folder each (Vikix's are auto-…); predetect.d/vikix, Vikix's, lays out a screen with none │ ├── udiskie/config.yml yours, if you make it: replaces Vikix's udiskie settings │ ├── nyxt/config.lisp yours with the feature lisp-apps: Nyxt's settings, in Lisp; loads Vikix's part first (the desktop's colours) │ └── nvim/ yours with the feature neovim: init.lua (your settings at its end), your plugins in lua/plugins/, lazy-lock.json │ ├── .emacs.d/ with the feature emacs: a git clone of the Emacs config (vukini/emacs-void) ├── .claude/skills/vikix Vikix's tells Claude Code how Vikix works: SKILL.md, the short first page, and a page a subject │ ├── .local/ │ ├── bin/ │ │ ├── vikix, vikix-* Vikix's the command and its helpers │ │ ├── stumpwm built the window manager, built by 30-lisp (`vikix rebuild-wm`) at the Quicklisp release it pins │ │ ├── stumpwm.prev built the one before: the session starts it when a new image dies at login │ │ └── pil, claude, ... installed by 65-languages, the npm language servers, Claude Code │ ├── share/applications/*.desktop Vikix's JupyterLab, vikix-image, Lazarus in the launcher (Super+d); your web apps' too, Lem's and the Listener's (lisp-apps), Esploro's, and the Windows programs you added (vikix-win-NAME.desktop, vikix windows apps add) │ ├── share/vikix/fonts/wm.ttf built the bar's font, made by vikix-font │ ├── share/vikix/nvim Vikix's Vikix's part of Neovim: AstroNvim and Vikix's plugins (a link to config/nvim) │ ├── share/vikix/nyxt/vikix.lisp Vikix's Vikix's part of Nyxt: its colours from vikix theme's palette, followed live, and Swank on 127.0.0.1:4006 with ~/.slime-secret (a link to config/nyxt) │ ├── share/vikix/epubcheck/ fetched epubcheck, W3C's EPUB validator: a pinned release, checked against its checksum (vikix publish setup) │ ├── share/vikix/hunspell/ fetched the spelling's dictionaries: LibreOffice's British English, Esperanto and Arabic, pinned and checksummed (vikix publish setup) │ ├── share/vikix/publish Vikix's the make targets a book's Makefile includes (epub, pdf, check), and the build behind them (a link to lib/publish) │ ├── share/vikix/emacs Vikix's Vikix's part of Emacs: vikix-ai.el, gptel on vikix ai use's model and your agent in agent-shell; vikix-theme.el, the theme following vikix theme; vikix-notes.el, the notes under C-c n (a link to config/emacs) │ ├── share/info/vikix.info written these guides as an Info manual (`info vikix`) │ ├── share/man/man1/*.1 written a man page for every vikix command (`man vikix`, `man vikix-backup`) and for your plugins' commands (`man inbox`), made from what each -h prints; other programs' pages here are left alone │ ├── share/vikix/guide/ written these guides as web pages, with the diagrams (Super+m → Vikix guide in the browser: in Nyxt when it's installed, through vikix-docs-open) │ ├── share/dbus-1/services/org.freedesktop.FileManager1.service Vikix's the browsers' "Show in folder" opens Esploro (vikix add esploro) │ ├── share/vikix/wallpapers/ fetched Vid's wallpapers, a git clone (vikix add wallpapers; a link to ~/wallpapers if that's a clone of it) │ ├── share/vikix/whisper/ fetched dictation's model and voice detector (vikix dictate) │ ├── share/vikix/piper/ fetched the voice the AI talks with (vikix voice) │ ├── share/vikix/notes/index.db written note's index: passages of your notes and their embeddings (folder 700; note index) │ ├── share/vikix/AGENTS.md written the skill as a guide for Codex, Gemini, Antigravity, Aider (linked as ~/.codex/AGENTS.md, imported by ~/.gemini/GEMINI.md, included by ~/.gemini/antigravity-cli/rules/vikix.md) │ ├── opt/picolisp/ built PicoLisp, from source (with the feature lisp) │ ├── share/vikix/plugins/ Vikix's the plugins repo at its pinned commit (vikix plugin sync) │ ├── share/vikix/plugins-from/NAME/ Vikix's a plugin from another repository: its repository at the commit you pinned (vikix plugin add NAME --from REPO, vikix plugin pin) │ ├── share/vikix/records.db made what plugins found and kept (vikix records; SQLite, 600) │ ├── share/vikix/docs/index.db made the docs catalogue (vikix docs, Super+F2): every document's title and words; made again from the files │ ├── opt/lem/ built Lem, the editor in Common Lisp (vikix add lisp-apps) │ ├── opt/mcclim/ built McCLIM's Listener, with Clouseau (vikix add lisp-apps) │ ├── opt/esploro/ built Esploro, the file explorer: its command, and emacs/esploro.el, its window in Emacs (vikix add esploro) │ ├── opt/hype/ built Hype, Markdown slides (vikix add hype); ~/.local/bin/hype runs it │ ├── opt/ollama/ built Ollama, for local AI models (vikix ai setup) │ ├── opt/whisper.cpp/ built dictation's speech-to-text, built for this computer (vikix dictate setup) │ ├── share/libvirt/images/ the Windows VM's disk and its driver disc (not backed up) │ ├── share/vikix/webapps/ each web app's own Chromium profile: its logins (caches not backed up) │ └── state/vikix/ Vikix's record of this machine (see below) │ ├── quicklisp/ Common Lisp libraries; StumpWM is built from here ├── .lazarus/ Lazarus with the docked IDE, built by 65-languages │ ├── dev/ yours, with parts written for you (see below); a folder per language you added ├── learn/c/ yours: your work in vikix learn c, one folder a lesson (copied once; the checks stay in ~/vikix/learn) ├── .ollama/models/ local AI models (vikix ai models): big, not backed up ├── vikix-debug-*.txt the reports vikix debug writes (yours to delete; vikix diagnose's are in ~/.local/state/vikix/diagnose/) ├── .config/io.datasette.llm/ llm's settings and its log of everything asked (vikix ai llm) ├── journal/ yours the diary: a day a file, written by vikix day (700; what you write under Notes is kept) ├── Pictures/Screenshots/ Shift+Print and friends ├── Videos/Recordings/ Super+Ctrl+v ├── Windows/ yours drive Z: in the Windows VM (vikix windows); ~/Documents is drive Y: there once vikix windows apps setup has run └── Restored/ `vikix backup restore` puts files here, never over yours
~/.local/state/vikix: the record of this machine ¶logs/One log per install and per vikix update, named by date. Also the long output of a few builds, kept out of the update’s own: nvim-plugins.log (Neovim’s plugins), whisper-build.log (dictation), lazarus-build.log (the Lazarus IDE); and windows-app.log, what FreeRDP said each time a Windows program was opened (vikix windows app)
session.log, session.log.oldEverything the desktop session printed, this login and the one before. The first place to look when the desktop won’t start.
yours.gitThe history of your files (vikix snapshot, changes, history, undo). A git repository whose work tree is ~, limited to the files in ~/vikix/config/yours.list
errors/Every error the desktop met, one file each, with its backtrace: a mistake in user.lisp or a Vikix file, or one StumpWM didn’t catch (When something breaks). The newest 50 are kept
user-last-snapshot.lispThe copy of your last snapshot of user.lisp, written when you chose to load it instead of a broken one
migrations/Which one-off fixes this machine has had
day/What had the screen, for vikix day: screen-YYYY-MM.log, a line when the workspace, project, program or folder in front changed (never a window’s title; 600), and docs.log, the documents opened from the catalogue. To keep none of the first: (setf *vikix-day-on* nil) in user.lisp
docs/random-deckGuide pages still to be shown this round by vikix docs random, one filename per line (600). An empty or missing file starts a new round; newly added guides join that next round
docs/watch.pid, docs/watch.logThe watch on ~/src (vikix docs watch on): its process, and what it read when
welcomeThe welcome’s steps you’ve done (vikix welcome); that it exists means the welcome has been shown, so it doesn’t open at login again
checkout-changes/Changes someone made in ~/vikix, set aside by vikix update as patch files (see When something breaks)
diagnose/The last five reports vikix diagnose gave your agent
mcp.log, mcp-servers/Every call an agent made to vikix mcp, refused ones too (600), and the servers running now, with their version (vikix mcp status reads both)
session.envThis session’s display, D-Bus and runtime folder (600), for a vikix mcp started by an agent that doesn’t pass them on (Codex)
agent-shell/Emacs’s agent chats, one transcript per chat, named after the project (700)
nvim-lock.jsonThe plugin versions Vikix last left in your ~/.config/nvim/lazy-lock.json: how an update knows whether you moved them yourself
voice-chatSuper+F10’s conversation: llm’s id for it, and when it was last used
dictatingOnly while dictation listens (Super+F9): the recorder’s process, so the next press can stop it
jupyter.logJupyterLab’s messages (jlab)
ollama.logLocal AI’s log (vikix ai); one old one is kept as ollama.log.old
test-flakes.logEach screen test that failed in a run of tests/run.sh and passed once more alone: when, the commit, the test, the load, its first FAIL lines (a test often here is one to mend)
updatesWhat the bar’s updates field shows, written by vikix-updates every 6 hours: the counts, and on the main channel GitHub’s verdict on the commit this machine runs
tests-toldThe commit whose failed tests were told in a notification, so it is said once
mimeapps-offeredThe starter’s default programs already offered to your ~/.config/mimeapps.list (added, or yours kept), so each is offered once
wallpaper-now, wallpaper-queue, wallpaper-shown, wallpaper.lockThe picture the cycling wallpaper shows, the pictures still to come this round and those it has had, and the lock that keeps its watcher (vikix-wallpaper --watch) to one
initramfs-*Marks that the initramfs was rebuilt with this microcode
soak/Each vikix times soak’s samples, one CSV a run: StumpWM’s answer time, memory, windows, timers, every ten seconds
times.log, times-measured.logHow long things took: each login and Reload config on this desktop, and each vikix times measure (When something breaks)
windows-apps.jsonThe programs in Windows’ Start menu, as vikix windows apps last read them: where vikix windows app NAME finds a program
windows-launcher.jsonThe Windows programs you put in the launcher (vikix windows apps add): an entry gone missing is written again by vikix update or vikix windows apps restore
obsidian/vikix obsidian’s record: which folders of the vault are converted, each note as it was written (so one you changed since is left alone), and each folder’s report
~/dev ¶A folder per language you added (vikix add python …), made by 67-dev: ~/dev/<language>/README.md (the tools on this machine, and where to learn; written again by every update, so keep your notes in another file), examples/ (copied once, yours), and docs/ (filled by vikix docs get). ~/dev/index.html links every offline doc. ~/dev/ai is the same without a language of its own: small programs that call Claude and the local models (AI). Anything else you put in ~/dev is left alone.
~/vikix ¶Everything Vikix is. readlink -f ~/.local/bin/vikix finds it if you cloned it somewhere else.
VERSIONThe version you have (vikix version, or vikix --version; Super+m → Reload config says it too)
install.sh, install/The installer (the base, then --with features) and its stages, NN-name.sh. Each is safe to run again: ./install.sh --only 40-config
bin/vikix and its helpers, linked into ~/.local/bin. Each starts with a comment saying what it does.
config/Everything that ends up in your home: the files linked there, and the starters copied once
config/stumpwm/vikix/The StumpWM layer. Read it to see how a key, the bar or the menu is made, then change it from user.lisp
config/yours.listThe files the snapshot history covers
config/what/A page for each kind of thing vikix what explains (a process, a key, each field of the bar): a short paragraph, then the guide, manual and file to read on
packages/*.listWhat gets installed, one list per concern, lang-*.list one per language. packages/optional/ holds lists only a feature brings, like the Windows VM
features.list, bundles.listWhat vikix add offers: each feature’s lists, and the bundles (essentials, developer, everything). A list no feature names is the base
services.listThe runit services Vikix switches on
examples/Samples to copy and change: hype/vikix-tour/, a Hype presentation (vikix add hype)
learn/The courses vikix learn runs (learn/c/): each lesson’s text, example and exercise, copied once to your ~/learn/c/, and its checks, which stay here
themes/The themes that come with Vikix (vikix-dark, vikix-light, gruvbox-dark, nord-dark, tokyo-night-dark, contrast-dark) and their wallpapers, drawn by lib/make-wallpaper.py
dev/The READMEs and examples ~/dev is made from
migrations/One-off fixes for machines installed before a change
lib/Shared shell helpers, and the script that builds StumpWM
docs/These pages
site/The website, vikix.dev, and site/install, the one-line install
tests/The tests: tests/run.sh
The checkout is a git repository. git -C ~/vikix log shows what each version changed.
What Vikix changes on the system itself. Everything else under / is as Void left it, plus the packages.
/etc/xbps.d/*-repository-*.confWhat: The mirror, the fastest one found at install; the multilib repository’s file joins them with the feature steam
By: 05-mirror, vikix steam setup
/var/service/*What: Links that switch on the services in services.list, and NetworkManager
By: 20-services, 25-network
/etc/ufw/What: The firewall’s settings and rules: on, nothing comes in but SSH and the ports allowed (vikix firewall)
By: 25-network, vikix firewall
/etc/polkit-1/rules.d/50-vikix-printers.rulesWhat: With the feature printing: the lpadmin group manages printers without a password
By: 20-services
/etc/security/limits.d/50-vikix-steam.confWhat: With the feature steam: your hard limit of open files raised to 524288, for Proton’s esync
By: vikix steam setup
/etc/alsa/conf.d/What: Links that send ALSA programs to PipeWire
By: 50-audio
/etc/X11/xorg.conf.d/40-libinput.confWhat: Touchpad: tap to click, natural scrolling
By: 55-hardware
/etc/udev/hwdb.d/90-vikix-keys.hwdbWhat: Keys put right: the ROG Flow Z13’s F6 is Print (config/udev/90-vikix-keys.hwdb says which keyboards and why)
By: 55-hardware
/boot/initramfs-*What: Rebuilt with the Intel microcode
By: 55-hardware
/etc/udev/rules.d/60-vboxguest.rulesWhat: VirtualBox only: the shared clipboard
By: 70-vm
What: You are added to video, network, lpadmin (and vboxsf in VirtualBox)
By: 20-services, 25-network, 70-vm
dhcpcd and wpa_supplicant are switched off by 25-network, since NetworkManager does their job.
Not Vikix’s, but you’ll want them:
/etc/sv/ (switch one on: sv-on NAME)
/var/service/ (list them: svls)
sudo sv status NAME
xl NAME (xbps-query -f)
xbps-query -o /path/to/file