Skip to content

t1k:omarchy-setup

FieldValue
Modulet1k-devops
Version4.1.3
Effortmedium
ToolsAskUserQuestion, Bash, Edit, Glob, Grep, Read, Write

Keywords: claude fleet, desktop setup, herdr, herdr bar, hyprland workspaces, omarchy, omarchy setup, quickshell bar, tuha.workspaces

/t1k:omarchy-setup
[init-config | --dry-run | --dest DIR | lint | --enable-units]

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.

IntentPath
“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)
Group (--only)InstallsWhere
barshell.json (bar layout, dock, idle) and four user plugins: workspaces pills, system monitor popup, Claude-agents popup, clipboard button~/.config/omarchy/
hyprlandherdr-yolo.lua (group workspaces, red border for blocked), managed blocks in bindings.lua and hyprland.lua~/.config/hypr/
herdrconfig.toml, sidebar-tree.json, no-desktop-window, herdr-desk-map.conf~/.config/herdr*/
systemdherdr@ (+ limits drop-ins), restore, status daemon, desktop layout, sidebar-tree and wt-board timers~/.config/systemd/user/
bin19 herdr-* / hh* scripts~/.local/bin/
claudeClaude launcher helpers (claude-pick, claude-yolo, claude-yolo-run, ccs-yolo-run, claude-live-in-dir, claude-settings-guard)~/.local/bin/
desktopmerged, 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/
mobileOPT-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/
owetheme-set hook 10-owe-sync (only when owe.enabled)~/.config/omarchy/hooks/theme-set.d/

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.

  1. Read the options. bun $S/install.cjs --list-options --json prints every configurable key with component, type, allowed, default, description, ask and suggestions. Build the questions from that output, not from memory; skip keys with ask: false.
  2. 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; offer components.herdrMobile only 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.layout suggestions), dock pins, idle timers; (d) CCS gateway (claude.ccsEnabled, herdr.ccsBaseUrl) or plain Anthropic. Detail and detection recipes: config-wizard (references/config-wizard.md).
  3. 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.
  4. Preview, then install (S=.claude/skills/t1k-omarchy-setup/scripts, or under ~/.claude/skills/):
Terminal window
bun $S/install.cjs --dry-run # plan only, writes nothing
bun $S/install.cjs --dest "$HOME/omarchy-stage" # full install into a scratch root, lint, no live checks
bun $S/install.cjs # real install + live verification
bun $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.

  • 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 in thirdPartyPlugins with 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.lua and hyprland.lua are 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 through Style.duration().
  • Live verification (hyprctl configerrors, omarchy-shell shell rescanPlugins, systemctl --user) runs only for a real-$HOME install, never with --dest or --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.list and the mise config are merged key by key (a mise version you already pinned is kept and reported), portrait.yml is 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-run reads the token from gh auth token at run time.

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.

StepAgent
Edit the config for this machineinline (main session)
--dry-run, --dest, lintinline: read-only against the real desktop
Real install, --enable-unitsinline: needs the user’s go-ahead
  • references/config-wizard.md - turning --list-options into questions, detecting groups
  • references/config-schema.md - every config key, type, and what it drives
  • references/architecture.md - pipeline, template syntax, managed blocks, adding a template
  • references/herdr-integration.md - data flow, units, prerequisites outside this skill
  • references/verification.md - proof commands, tests, troubleshooting
  • references/dropped-legacy.md - what the port from KDE dropped, and why
  • Tests: bun test .claude/skills/t1k-omarchy-setup/tests/