Dotfiles

Optioned Linux for a dev environment

git clone --no-checkout https://github.com/klarkc/dotfiles
mv dotfiles/.git ~
rm -r dotfiles

⚠ Next command will replace current home files with repo files (backup first!)

git checkout main

Features

• Lemurs Window Manager
• Pipewire Sound Server
• Alacritty with ligatures + Tmux + vim
• Vim Language Server Protocol + Automatic Servers
• Nord Theme for the desktop; Alacritty uses its default color theme
• Fira Code with ligatures support
• LSD replaces ls with the modern lsd alternative
• CapsLock as Escape
• Ctrl+ç as Ctrl+b through keyd, while ç remains Unicode without Ctrl
• Using satty with scrot for annotated screenshots
• codex and opencode as coding agents
• Fusion for agents orchestration
• kolu for coding agent orchestration

Machines

Each machine has specific configurations and enabled features so I'm splitting it between different branches.

• ssdinarch: my personal laptop
• main (default): work machine

Aliases

• l: ls -l
• ll: ls -la
• lt: ls -lt

Optional Features

• Maintenance systemd scripts and upstream dependency monitoring
• Sunshine game streaming server (to play games on my TV)
• Handlr manage default apps
• AI models with ollama
• AI Agents with codex and lumen
• Fusion

Supported setups

Below are the supported distro setups

Arch Linux with NVidia

Dependencies

pacman -Syu yay
yay -Syu openssh pwvucontrol pipewire pipewire-audio pipewire-pulse pipewire-alsa git git-lfs gvim qt5-styleplugins nix ttf-fira-code noto-fonts-emoji lsd dconf-editor picom xorg-xmodmap xclip keyd dunst libnotify lemurs haskell-language-server xmonad xmonad-contrib xorg-xsetroot xorg-xset xorg-xmessage feh the_silver_searcher satty scrot wget xorg-server taffybar libappindicator-gtk3 blueman dmenu sword i3lock xss-lock
sudo chmod +s .local/bin/pacman-*
systemctl enable --now nix-daemon.socket
systemctl enable --now lemurs

Alacritty is installed by the Nix profile from the ink-splatters/alacritty-ligatures fork, so it is intentionally not installed from pacman/yay here.

Below dependencies are not mandatory but highly recommended

yay -Syu ffmpeg unzip htop

Below dependencies are not mandatory (see Optional Features)

yay -Syu snapper pacreport yay-cache-cleanup-hook sunshine bat git-delta ripgrep handlr ollama-cuda discord enpass-bin btdu btop

Lumen

yay -Syu lumen
yay --asdeps fzf mdcat

Yazi as file manager with optional deps

yay -Syu yazi
yay -S --asdeps 7zip jq poppler fd fzf zoxide resvg imagemagick xclip xsel chafa

Installation

nix profile install .
make
systemctl --user daemon-reload

Verification (make test)

make test is the standard verification entrypoint for this repo. It runs nix flake check (static config + no-network self-tests) followed by every .local/bin/*-smoke-test script (out-of-band live checks that require network and user secrets).

Smoke tests are enabled by default and can be disabled with SMOKE_TESTS_ENABLED=false (or the legacy SKIP_SMOKE=1 alias) so static checks can run without sourcing ~/.profile_override.

# Local developer: full run with smoke tests
make test

# CI / static-only run
SMOKE_TESTS_ENABLED=false make test
# or
make test SMOKE_TESTS_ENABLED=false
# backwards-compatible alias
SKIP_SMOKE=1 make test

Use make fmt separately if you want to apply formatting locally; CI does not auto-format.

The CI workflow at .github/workflows/test.yml invokes SMOKE_TESTS_ENABLED=false make test instead of bare nix flake check.

Smoke tests follow the repo convention .local/bin/*-smoke-test. They are out-of-band: they need network access and user secrets, must never be added to nix flake check, and must never print tokens, Authorization headers, or generated Basic base64 strings.

The repo ships two:

• .local/bin/atlassian-smoke-test — verifies Rovo MCP connectivity (api-token via Basic auth, oauth via bridge) and acceptance criteria (required tools, expected Atlassian site).
• .local/bin/coding-agents-smoke-test — verifies that the user's active coding agents (opencode, codex) can use the Atlassian Rovo MCP integration to request real Bitbucket, Jira, and Confluence resources. The script issues a constrained prompt to each active agent asking it to call Atlassian MCP tools (e.g. bitbucketRepository, getVisibleJiraProjects, getConfluenceSpaces) and return a fixed JSON status object. Each probe drives the real agent with opencode run --format json or codex exec --json. The smoke fails if no agent returns a parseable status or if any of Bitbucket/Jira/Confluence are reported unreachable from every probed agent. Auth detection:
  • opencode: parses the tracked ~/.config/opencode/opencode.json; if the configured model's provider has a usable credential (e.g. {env:VLLM_API_KEY} for the local vLLM provider), the probe runs. Otherwise SKIPPED.
  • codex: uses Codex/ChatGPT OAuth state at ${CODEX_HOME:-$HOME/.codex}/auth.json. The probe considers auth available when the JSON file contains non-empty access_token and refresh_token fields either at the top level or nested under a tokens object. The probe never prints token values; it logs only boolean diagnostics (codex: OAuth auth available / OAuth auth unavailable).
  • Run CODING_AGENTS_SELFTEST=1 .local/bin/coding-agents-smoke-test to exercise the Codex OAuth detector against the top-level and tokens-nested auth shapes without driving the live agents.

OpenCode + Codex OAuth

opencode uses OpenCode's native auth store at ~/.local/share/opencode/auth.json. The wrapped opencode command lazily syncs Codex OAuth before launch when ~/.codex/auth.json exists and is newer than the OpenCode auth file, or when the OpenCode auth file does not exist yet.

Run the sync explicitly after authenticating Codex or when rotating accounts:

opencode-codex-auth-import

Verify the imported OpenAI provider auth:

jq '.openai | {type, has_access: has("access"), has_refresh: has("refresh"), has_accountId: has("accountId"), expires}' ~/.local/share/opencode/auth.json

Install the Lemurs XMonad session wrapper after checkout. It starts XMonad with a valid D-Bus session when needed, imports the graphical environment into D-Bus and systemd user activation, and starts a notification daemon if one is installed.

sudo install -Dm755 .local/bin/xmonad-session /etc/lemurs/wms/xmonad

Test desktop notifications after logging in again:

notify-send "dotfiles" "desktop notifications work"

Configure the system-wide keyd remap so ç remains the regular Unicode character, while Ctrl+ç is emitted as Ctrl+b for tmux and terminal shortcuts. This requires sudo because the keyd config lives in /etc/keyd and the daemon runs system-wide.

sudo install -d /etc/keyd
sudo tee /etc/keyd/default.conf >/dev/null <<'EOF'
[ids]
*

[control]
semicolon = C-b
EOF
sudo keyd check
sudo systemctl enable --now keyd
sudo keyd reload

If the ç key is not reported as semicolon on a machine, check it with:

sudo keyd monitor

Fusion's systemd service uses ~/.fusion/ssh_config for Git SSH operations. Keep that file generated when OpenSSH configuration changes so sandboxed Fusion can read a stable SSH config.

Install the pacman hook so this generated SSH config is refreshed after openssh or systemd package updates:

sudo install -Dm644 .local/share/pacman/hooks/fusion-ssh-config.hook /etc/pacman.d/hooks/fusion-ssh-config.hook

Below steps are not mandatory (see Optional Features)

systemctl --user enable home-cleanup.timer
systemctl --user enable nix-cleanup.timer
systemctl --user enable pacreport.timer
systemctl --user enable --now sunshine.service
systemctl --user enable --now fusion-backup.timer
systemctl --user enable --now kolu

To expose a user service running HTTPS on port 4443 through local port 443, allow user processes to bind ports down to 443 once at the system level:

sudo install -Dm644 /dev/stdin /etc/sysctl.d/99-unprivileged-ports.conf <<'EOF'
net.ipv4.ip_unprivileged_port_start=443
EOF
sudo sysctl --system

Then enable the socket-activated user proxy:

systemctl --user enable --now https-proxy.socket

vLLM + Fusion

The vLLM/Fusion workflow is target-based. Only one vLLM model target should run at a time:

• vllm-qwen3.6-35B-a3b.target starts vllm@qwen3.6-35B-a3b.service
• vllm-qwen3.6-27B.target starts vllm@qwen3.6-27B.service

Use vllm-config to choose the active local model. It stops Fusion and all vLLM units, disables the non-selected target, enables the selected target for future user-session starts, starts the selected target, and follows the relevant journal logs until vllm@...service and fusion.service are active.

The target starts only the selected vLLM service. The vLLM service then patches local Fusion and opencode defaults, starts the model, waits for GET /v1/models to respond with the selected served model, and only then restarts Fusion so it rereads changed config files. Fusion is intentionally not pulled directly by the target; readiness is owned by vLLM@...service.

Pick the model interactively:

vllm-config

Or switch directly:

vllm-config qwen3.6-35B-a3b
vllm-config qwen3.6-27B

Verify which target will start with the user systemd session:

systemctl --user is-enabled vllm-qwen3.6-35B-a3b.target
systemctl --user is-enabled vllm-qwen3.6-27B.target

The selected target should be enabled; the other targets should be disabled. The legacy single-model vllm.service is obsolete; vllm-config stops and disables it when switching models.

User systemd services start when the user manager starts. To start the selected vLLM target after reboot before an interactive login, enable lingering once:

loginctl show-user "$USER" -p Linger
sudo loginctl enable-linger "$USER"

After lingering is enabled, re-check:

loginctl show-user "$USER" -p Linger

Expected:

Linger=yes

Watch startup progress:

journalctl --user-unit vllm-qwen3.6-35B-a3b.target -f
journalctl --user-unit vllm@qwen3.6-35B-a3b.service -f
journalctl --user-unit fusion.service -f

Run the maintained vLLM benchmark wrapper against the active target:

vllm-benchmark

Benchmark artifacts are written below ~/.cache/vllm-benchmarks/.

For the 27B target, replace 35B-a3b with 27B in the commands above.

Generic archive pack (archive-pack)

The archive-pack and archive-pack-test commands are provided by the Nix flake (.nix/backup-tools.nix) and installed into the user profile by nix profile install ..

Inputs live in ~/.backup/:

• Any file or directory — archives (*.tar, *.tar.gz, *.tar.bz2, *.tar.xz, *.tar.zst, *.tar.lz, *.zip, *.7z) get extracted and their contents stored.
• Plain files are stored as-is.
• Directories are stored recursively.

Excluded by default: stage/, logs/, manifest/, archive.lrz, archive.lrz.SUMMARY.txt, archive-*.lrz, .gitignore, README.md. Use --exclude GLOB to add more.

Outputs:

• ~/.backup/archive.lrz — single deduplicated archive (lrzip).
• ~/.backup/archive-YYYYMMDD-HHMMSS.lrz — datestamped snapshots when --retain > 0.
• ~/.backup/archive.lrz.SUMMARY.txt — generation report.
• ~/.backup/stage/ — staging directory (visible, kept unless --clean-temp).
• ~/.backup/logs/ — log directory (visible, kept unless --clean-temp).
• ~/.backup/manifest/ — list of files inside the archive.

The script is append-only: re-pack merges the previous archive with new sources. Files removed from ~/.backup/ stay in the archive; lrzip dedups identical content across all files.

Install/upgrade:

nix profile install .
# or
nix profile upgrade klarkc

Run with safe defaults (≈8 threads, ≈8 GB RAM cap, window 2 GB, level 6):

archive-pack

Tune resources:

archive-pack --threads 4 --maxram 40 --window 10 --level 6

Dry run:

archive-pack --dry-run

Skip per-file integrity check:

archive-pack --skip-source-integrity

Keep original archive files alongside their extracted contents:

archive-pack --keep-archives

Exclude additional paths (repeatable):

archive-pack --exclude '*.tmp' --exclude 'cache/'

Snapshot retention (default: keep last 5 datestamped archives):

archive-pack --retain 5
archive-pack --retain-days 30

Clean temporary staging and logs after a successful pack:

archive-pack --clean-temp

Clean original sources (everything in ~/.backup/ except the built-in excludes and any --exclude patterns) after a successful pack and lrzip -t:

archive-pack --clean-source

Combine both:

archive-pack --clean-temp --clean-source

Verify the archive integrity without repacking:

archive-pack --verify

The final archive.lrz is never removed by the script.

Run the self-test (synthetic backup with append-only check):

archive-pack-test
# or, via flake check
nix flake check

nix flake check runs the formatting check, pre-commit checks and archive-pack-test as part of checks.archive-pack-test.

How to extract later (no Nix required at extraction time):

lrzip -t ~/.backup/archive.lrz          # verify integrity
lrzip -d -o - ~/.backup/archive.lrz     # produces .tar on stdout
lrzip -d ~/.backup/archive.lrz          # produces archive.tar
mkdir -p restored && tar -xf archive.tar -C restored