t1k:omarchy-setup
| Field | Value |
|---|---|
| Module | t1k-devops |
| Version | 4.1.3 |
| Effort | medium |
| Tools | AskUserQuestion, Bash, Edit, Glob, Grep, Read, Write |
Keywords: claude fleet, desktop setup, herdr, herdr bar, hyprland workspaces, omarchy, omarchy setup, quickshell bar, tuha.workspaces
How to invoke
Section titled “How to invoke”/t1k:omarchy-setup[init-config | --dry-run | --dest DIR | lint | --enable-units]t1k:omarchy-setup
Section titled “t1k:omarchy-setup”Rebuilds one person’s Omarchy desktop on a fresh Omarchy install from templates plus ONE JSON config: the custom bar, its two popups, the Hyprland workspace rules and the whole herdr (Claude-agent fleet manager) integration. Nothing personal lives in the templates; every project group, city, path and namespace comes from the config.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Set this up on a new machine” | Workflow: choose, write config, dry-run, install |
| “Move a project group to another workspace / add a city / change a limit” | edit the config, re-run install (config-schema (references/config-schema.md)) |
| “What would it change?” | install.cjs --dry-run |
| “Try it without touching my desktop” | install.cjs --dest <scratch dir> |
| “Something looks broken afterwards” | verification (references/verification.md) |
| “How do the pieces talk to each other?” | herdr-integration (references/herdr-integration.md) |
| “Add or change a template” | architecture (references/architecture.md) |
What it installs
Section titled “What it installs”Group (--only) | Installs | Where |
|---|---|---|
bar | shell.json (bar layout, dock, idle) and four user plugins: workspaces pills, system monitor popup, Claude-agents popup, clipboard button | ~/.config/omarchy/ |
hyprland | herdr-yolo.lua (group workspaces, red border for blocked), managed blocks in bindings.lua and hyprland.lua | ~/.config/hypr/ |
herdr | config.toml, sidebar-tree.json, no-desktop-window, herdr-desk-map.conf | ~/.config/herdr*/ |
systemd | herdr@ (+ limits drop-ins), restore, status daemon, desktop layout, sidebar-tree and wt-board timers | ~/.config/systemd/user/ |
bin | 19 herdr-* / hh* scripts | ~/.local/bin/ |
claude | Claude launcher helpers (claude-pick, claude-yolo, claude-yolo-run, ccs-yolo-run, claude-live-in-dir, claude-settings-guard) | ~/.local/bin/ |
desktop | merged, never overwritten: mimeapps.list defaults, mise tools; created only if absent: lazygit portrait.yml; own file: claude-code-url-handler.desktop | ~/.config/, ~/.local/share/applications/ |
mobile | OPT-IN, default off (components.herdrMobile): the herdr mobile app bridge, herdr-hc-sync / -mirror / -spaces plus a 30 s timer and a status-file path unit. Needs components.herdr, herdr-core and jq (details (references/herdr-integration.md#mobile-app-bridge-opt-in)) | ~/.local/bin/, ~/.config/systemd/user/ |
owe | theme-set hook 10-owe-sync (only when owe.enabled) | ~/.config/omarchy/hooks/theme-set.d/ |
Workflow
Section titled “Workflow”The example config holds the original author’s values. Do not write it as the user’s config unasked: let the user choose first. The installer stays non-interactive; the choosing happens here.
- Read the options.
bun $S/install.cjs --list-options --jsonprints every configurable key withcomponent,type,allowed,default,description,askandsuggestions. Build the questions from that output, not from memory; skip keys withask: false. - Ask with
AskUserQuestion, 1-4 questions per call, the author default first and marked “(Recommended)”, each option labelled with what it does. Batches: (a) components (components.*,owe.enabled; offercomponents.herdrMobileonly to someone who uses the herdr mobile app, default off); (b) project groups: start from the example groups, from groups detected on this machine, or from one minimal group, then confirm slug, workspace and name for each; (c) world-clock cities (bar.layoutsuggestions), dock pins, idle timers; (d) CCS gateway (claude.ccsEnabled,herdr.ccsBaseUrl) or plain Anthropic. Detail and detection recipes: config-wizard (references/config-wizard.md). - Write
~/.config/t1k/omarchy-setup.json(mode 0600) from the example with only the chosen values changed. A caller that already has a prepared config skips steps 1-3 and passes--config FILE. - Preview, then install (
S=.claude/skills/t1k-omarchy-setup/scripts, or under~/.claude/skills/):
bun $S/install.cjs --dry-run # plan only, writes nothingbun $S/install.cjs --dest "$HOME/omarchy-stage" # full install into a scratch root, lint, no live checksbun $S/install.cjs # real install + live verificationbun $S/install.cjs --enable-units # also `systemctl --user enable` the units (no --now)init-config copies the example to the default config path (never overwrites) for users who prefer to edit by hand.
Exit codes: 0 ok, 2 usage/config error, 3 live verification failed, 4 syntax lint failed.
Hard rules
Section titled “Hard rules”- Write only under the user’s home. Never touch
/usr/share/omarchy; user plugins live in~/.config/omarchy/plugins/<id>/. - Never read, write or template
calendar-sync.json(private, 0600). The calendar plugin is third-party: it is named inthirdPartyPluginswith its git remote and the verify step tells the user to clone it; this skill never does. - Overwrites are backed up to
<file>.bak.<epoch>; an unchanged file is not rewritten.bindings.luaandhyprland.luaare edited only inside>>> t1k-omarchy-setup:<id> >>>markers, and left alone if the same lines already exist unmarked. - QML text sinks fed by files, IPC or command output use
textFormat: Text.PlainText(agent and session names come from the herdr status file and are untrusted); animation durations go throughStyle.duration(). - Live verification (
hyprctl configerrors,omarchy-shell shell rescanPlugins,systemctl --user) runs only for a real-$HOMEinstall, never with--destor--dry-run. - A missing config key is an error. There is no fallback config; do not add one.
- Files the user owns are merged, not replaced:
mimeapps.listand the mise config are merged key by key (amiseversion you already pinned is kept and reported),portrait.ymlis created only if absent. Never ship name/email git config,gh,rclone, superwhisper or Unity Hub files. - No credential in any template or config.
ccs-yolo-runreads the token fromgh auth tokenat run time.
Executed by
Section titled “Executed by”Runs inline in the invoking session. The only mechanical step is install.cjs, which the user’s own consent gates
(it rewrites dotfiles and, with --enable-units, changes systemd state), so it is not delegated to a cheap agent; the
config edit is judgment about the user’s own projects.
| Step | Agent |
|---|---|
| Edit the config for this machine | inline (main session) |
--dry-run, --dest, lint | inline: read-only against the real desktop |
Real install, --enable-units | inline: needs the user’s go-ahead |
References
Section titled “References”references/config-wizard.md- turning--list-optionsinto questions, detecting groupsreferences/config-schema.md- every config key, type, and what it drivesreferences/architecture.md- pipeline, template syntax, managed blocks, adding a templatereferences/herdr-integration.md- data flow, units, prerequisites outside this skillreferences/verification.md- proof commands, tests, troubleshootingreferences/dropped-legacy.md- what the port from KDE dropped, and why- Tests:
bun test .claude/skills/t1k-omarchy-setup/tests/