\n\n# Haoshoku: Color of the Supreme King\n\nHaoshoku is a personal, modular setup toolkit for Arch-family desktops and\nDebian servers. Its desktop path is designed around Omarchy: Haoshoku installs\napplications and portable developer configuration while Omarchy remains the\nowner of the desktop experience. The desktop path requires Omarchy 4\n(Quattro) or newer; Omarchy 3 is no longer supported.\n\n## Install\n\n```bash\ngit clone https://github.com/axatbhardwaj/haoshoku.git\ncd haoshoku\nbun install\nbun link\nhaoshoku --os arch\n```\n\n`bun haoshoku.js --os arch` works without creating a global link. The legacy\n`--os cachyos` spelling is accepted with a deprecation warning.\n\nInstall the pinned, checksum-verified Axstack release and configure its Claude\nand Codex harness targets with `haoshoku --axstack`. Run\n`haoshoku --axstack-check` to report the shim/version, each harness check, and\nthe Paseo profile-file readback separately.\nClaude and Codex setup skip config synchronization when their CLI installation fails.\n\n## Arch and Omarchy behavior\n\nThe Arch setup:\n\n- authenticates sudo once up front and keeps that authorization alive with\n silent, non-interactive refreshes until setup finishes or aborts. Later\n Haoshoku sudo calls are non-interactive and fail instead of prompting again;\n- performs a full system upgrade before package installation through\n `omarchy update -y` on Omarchy or `pacman -Syu` on other Arch-family\n systems, aborting setup if that preflight fails;\n- prefers Omarchy's `yay`, falls back to `paru`, and bootstraps an AUR helper\n only when neither is available;\n- uses `pacman` for repository packages and the AUR helper only for AUR\n packages;\n- batches repository and AUR packages, filters missing targets, and retries only\n still-uninstalled packages individually when a batch fails;\n- installs only JetBrains Mono Nerd Font instead of the conflicting complete\n Nerd Font group;\n- installs the AUR `paseo-bin` desktop app, launches `/usr/bin/paseo` at login,\n and binds `Super+T` to its exact `Paseo` window class. The absolute desktop\n path prevents a user-installed Paseo CLI in `~/.local/bin` from shadowing it;\n- keeps Bash as the account shell and adds portable aliases and tool\n initialization through `~/.config/haoshoku/bashrc`;\n- preserves Omarchy's `.bashrc`, lock screen, and core Quickshell/Hyprland\n configuration. It asks Omarchy to apply the pinned Aurora theme, selected\n background, and font from `configs/omarchy/appearance.json`; it does not\n copy generated `current/theme` state between machines. Displaced Omarchy\n keybindings are\n relocated or explicitly superseded and documented in\n [`configs/omarchy/keybinding-swaps.json`](configs/omarchy/keybinding-swaps.json),\n the canonical swap record;\n- deploys `~/.config/hypr/haoshoku/{bindings,workspaces}.lua` and appends\n exactly two `require` lines to `~/.config/hypr/hyprland.lua`; Omarchy 4\n loads user config via `require()` and no longer sources `.conf` files;\n- automatically determines `pc` or `laptop` from Linux DMI chassis data, with\n battery detection as the fallback, and saves it to `~/.haoshoku.json` before\n device-routed audio and Hyprland configuration. A valid stored choice wins,\n so `haoshoku --device-type pc|laptop` remains the explicit override. Only\n ambiguous hardware falls back to the interactive selector; Skip persists\n nothing and leaves device-specific audio unset;\n- keeps Claude stay-awake, PR watch, and the Matt Pocock skill set as portable\n setup steps. Full setup asks before Claude Remote Control and automatic git\n worktree cleanup; both default to No. The worktree offer explains that it enables a\n persistent weekly timer running\n `cleanup-worktrees.sh --apply`, which deletes eligible worktrees. Without\n interactive confirmation—including piped stdin—Haoshoku declines these real\n user decisions immediately and does not treat input as answers;\n- adds a device-routed behavior-only Lua workspace overlay. The hyprmoncfg\n plugin owns the generated `~/.config/hypr/monitors.lua`; Haoshoku owns only\n `~/.config/hyprmoncfg/profiles/*.json`, the source profile JSON that\n hyprmoncfg reads to generate that Lua file, and never writes\n `monitors.lua` directly. Monitor-bound workspace rules live in the\n hyprmoncfg PC profile, matched by hardware identity instead of connector\n name so they survive DP connector swaps; laptop workspace rules are\n monitor-independent and remain in the Lua overlay;\n- adds two-key special-workspace toggles under `Super`: A Haki (the tagged Warp\n `haki` tab), I AI assistants (Claude Desktop and Codex Desktop) on ordinary\n workspace 1,\n M music, O 1Password, G communication, B Flux Brave Origin,\n D DeFi Brave Origin,\n S Steam, and `Super+Shift+X` X (`Super+Shift+S` stashes the focused window,\n `Super+Alt+S` toggles the stash workspace);\n see the canonical swaps JSON above for every Omarchy default relocated or\n superseded to make room;\n- starts Steam silently in special:steam at login and binds `Super+2` to\n Omakade on demand, keeping `Super+Shift+G` as the gaming-workspace toggle\n that ensures Omakade. Steam login autostart is configurable\n (`~/.config/haoshoku/gaming.json` defaults to Steam on, Omakade off):\n `haoshoku --gaming-steam-autostart enabled|disabled` and\n `haoshoku --gaming-omakade-autostart enabled|disabled`. Use\n `haoshoku-gaming-workspace place -- %command%` as a Steam launch option to\n move the launched game's process-tree windows there. The same wrapper lifts\n the kernel split-lock penalty while the game runs and restores it on exit\n once `haoshoku --gaming-split-lock` has installed its narrow sudoers rule\n (Division 2 otherwise sits near 50 fps with an idle CPU and GPU);\n- starts Flux, DeFi, WhatsApp, and Notion with empty Brave Origin profiles\n below `~/.config/brave-haoshoku/`; existing Chromium profile data remains\n untouched at `~/.config/chromium-haoshoku/` for manual import;\n- installs packaged Omazed and safely points Zed at its generated theme so Zed\n follows the active Omarchy palette. Haoshoku never runs Omazed's manual\n installer or deletes unrelated Zed themes;\n- adds a non-locking `Screens Off` command to every paired KDE Connect device.\n It turns off all Hyprland displays through DPMS; keyboard or mouse input, or\n an existing phone-side Wake command, turns them back on. Pair new phones\n first, then run `haoshoku --kde-connect-commands` to add the command;\n- continues after individual optional application failures and reports them.\n\nHaoshoku deliberately does not configure Fish, KDE Plasma, KWin, SDDM, or\narbitrary application themes. Omarchy remains responsible for generating and\napplying all files downstream of the declared appearance.\n\n## Omarchy appearance\n\n[`configs/omarchy/appearance.json`](configs/omarchy/appearance.json) declares a\npublic theme repository at an immutable Git commit, one background filename\ninside that theme, and the font family. Full Arch setup and\n`haoshoku --omarchy-appearance` reconcile the theme under\n`~/.config/omarchy/themes/`, then call Omarchy's own theme, background, and font\ncommands. `haoshoku --discord-theme` then deploys that theme's Vencord CSS from\n`configs/discord/theme.json` into Vesktop and Vencord, setting `enabledThemes`\nwhile preserving every other settings key.\n\nAn existing checkout from another repository is never replaced. A matching\ncheckout with local changes is preserved and applied as-is; a clean matching\ncheckout advances to the declared commit. The manifest may identify exact\nlegacy revisions from older local-origin installs. Those recognized checkouts\nare moved to a timestamped sibling backup before Haoshoku installs the clean\npinned theme, and a failed install restores the original checkout. This keeps\ncustom work recoverable while making a fresh laptop reproduce the tracked\nappearance.\n\n## Omarchy plugins\n\nOn Arch-family desktops, Haoshoku installs the plugins listed in\n[`common/omarchy-plugins.json`](common/omarchy-plugins.json) by running\n`omarchy plugin add --enable --yes` for each one. Each repository is\ncloned and enabled at its current default branch HEAD — there is no commit\nor tag pinning. An entry may declare `disableOnInstall` to switch off a stock\nwidget it replaces. That list is applied only when Haoshoku first creates the\nplugin and is never re-applied, so a user can re-enable a displaced widget\nwithout a later Haoshoku run overriding the choice. Every run otherwise\nreconciles manifest plugins back to installed and enabled. If\n`omarchy plugin list --json` cannot provide a trustworthy snapshot, the helper\nperforms no plugin work and returns `snapshotUnavailable: true`; the\nside-effect-free manual-auth checklist is still printed.\n\nThe manifest includes the Speech Orb dictation HUD. Setup turns off voxtype's\nown OSD (`voxtype config set osd.enabled false`) and restarts a running\n`voxtype.service`, so only the orb appears while you dictate.\n\nThese plugins run as arbitrary, unsandboxed code inside the long-lived\nomarchy-shell process — the same risk Omarchy's own CLI warns about when\nadding plugins manually. The `--yes` flag is passed deliberately so setup\nstays unattended and non-interactive; this also suppresses Omarchy's\nper-plugin confirmation/warning prompt, so only add this manifest to\nmachines where you trust and have reviewed those repositories. Plugins\nthat need manual setup afterwards (API tokens, OAuth, device pairing) are\nprinted as a manual-auth checklist after installation.\nThe Galaxy Buds plugin is installed from `aislandener/galaxy-buds-control` and\nreports Bluetooth pairing in that checklist; it requires no credentials.\nPullbar (`io.github.ciryon.pullbar`) replaces both the former GitHub widget\n(`robzolkos.github`) and Agent Usage Plus on the right side of the bar. The full Arch setup deploys its required\n`~/.local/bin/omarchy-agent-usage-update` wrapper before installing plugins. If\nrunning only selected steps, run `haoshoku --scripts` before\n`haoshoku --omarchy-plugins`. That wrapper also scopes the Omarchy 4.0.0 Codex\ncollector's retired `-a untrusted` compatibility translation to usage refreshes;\nordinary Codex commands still execute the user's normal binary unchanged.\n\n## Omarchy bar\n\nUse `haoshoku --omarchy-bar` to deploy `configs/omarchy/bar.json`, and use\n`haoshoku --omarchy-bar-backup` to capture the live bar back into the repo.\nThe same commands deploy and back up Haoshoku's bundled `xzat.tray` plugin at\n`~/.config/omarchy/plugins/xzat.tray`. Its overflow drawer combines status\nnotifier items with Galaxy Buds, hyprmoncfg, Display, and No Sleep controls.\nThe full Arch setup restores the plugin and layout automatically; no separate\nclone step is needed. Feishin and Omarchy's generic MPRIS widget remain in the\nleft section, while Pullbar and the stock Agents widget stay visible on the right.\nHaoshoku claims the `bar` key of `~/.config/omarchy/shell.json` wholesale,\nincluding bar-widget enablement. Disabling a bar widget through Omarchy's UI is\ntherefore reverted on the next deploy. Every other top-level key — including\n`idle`, `plugins`, `disabledPlugins`, `version`, and unknown keys — is preserved.\n\n## Agent and orchestration policy\n\nHaoshoku deploys the compact Claude/Codex instructions, installs the Matt\nPocock and upstream Paseo skill sources through the Skills CLI, and syncs its\nthree owned workflow skills: `model-routing`, `paseo-pr-babysit`, and\n`paseo-pr-review`. It also installs the pinned upstream `visual-explainer`\npayload without treating it as a Haoshoku-owned backup source. Back up live\nedits with:\n\n```bash\nhaoshoku --claude-backup\nhaoshoku --codex-backup\nhaoshoku --agent-skills-backup\nhaoshoku --paseo-profiles-backup\n```\n\nThe shared profile lives at `configs/agent-profile/PROFILE.md`. Apply it to\nClaude, Codex, Opencode, and Antigravity with `haoshoku --agents`, or capture\nthe live Claude copy with `haoshoku --agents-backup`. The bundled policy routes\nboth Notion accounts and Linear through the configured Executor MCP while Orca\nremains responsible for orchestration.\n\n`--paseo-profiles` merges the bundled profile IDs and whitelisted provider\nfields into `~/.paseo/config.json`, preserving unknown profiles, credentials,\nrelay/listen/auth settings, and every unrelated key. Its backup writes only\nprofile fields plus provider `extends`, `label`, `description`, `command`, and\n`enabled`; it never copies credentials, daemon identity, relay state, or\nruntime files. Claude/Codex runtime state and `settings.json` remain\nmachine-local.\n\nThe visual explainer defaults to a fixed dark theme. Set and persist a different\npreference with `haoshoku --explainer-theme dark|light|system`; an explicit\ntheme in a request takes precedence. Fixed dark or light output uses the full\nupstream renderer, while the system theme may use quick mode. On the first\nsync after this migration, Haoshoku archives the retired shared\n`html-deliverables` skill under `~/.config/haoshoku/retired-agent-skills/`\nbefore removing only its managed Claude/Codex links.\n\n`haoshoku --agent-skills` also ensures\n`~/.config/haoshoku/paseo-tasks.json`. Its defaults enable the future-task\nlifecycle, readable ` · ` chat names, and archival after the\nparent records completion. Configure it independently with:\n\n```bash\nhaoshoku --paseo-tasks\nhaoshoku --paseo-tasks-enabled enabled\nhaoshoku --paseo-tasks-enabled disabled\nhaoshoku --paseo-task-renaming enabled\nhaoshoku --paseo-task-renaming disabled\nhaoshoku --paseo-task-cleanup archive\nhaoshoku --paseo-task-cleanup keep\n```\n\nThe config merge preserves unknown fields. Malformed JSON or invalid owned\nfields are left byte-for-byte untouched and return failure; the routing policy\nthen makes no metadata or cleanup changes. `keep` disables completion cleanup\nwithout disabling shared task labels.\n\n### Bounded Paseo schedule settings\n\nHaoshoku can manage only the provider, model, reasoning effort, and optional\nmode of three explicitly mapped native Paseo `new-agent` schedules. Initialize\nthe private host-local config, preview it, and apply verified differences with:\n\n```bash\nhaoshoku --paseo-schedules\nhaoshoku --paseo-schedules-check\nhaoshoku --paseo-schedules-apply\n```\n\nThe config lives at `~/.config/haoshoku/paseo-schedules.json`. It starts with\nall `scheduleId` values set to `null`: stale archive and worktree cleaner use\nClaude Sonnet 5 at high reasoning, while merge readiness uses Codex Luna at\nhigh reasoning. Run the configure command in a terminal to select only the\nroles this host owns and enter each native schedule ID and settings. An\nunmapped role is skipped, so a host may own none, one, or several roles.\n\n`--paseo-schedules-check` is read-only. It validates every mapped ID against\nthe running local daemon, requires a `new-agent` target, and reports capability\nsupport plus owned-field differences. `--paseo-schedules-apply` repeats the\nfull preflight, writes an exclusive mode-`0600` backup under\n`~/.config/haoshoku/paseo-schedule-backups/`, updates only differences through\nPaseo's native API, and verifies readback. Cadence, prompt, status, safety\nsettings, limits, and every other schedule remain untouched. If a write was\nattempted but verification fails, inspect the reported schedule and backup\nbefore retrying; Haoshoku never retries or rolls back uncertain state\nautomatically.\n\nThese modes never infer ownership from schedule titles, create, delete, pause,\nresume, or run schedules, and never reload or restart Paseo. Normal Haoshoku\nsetup does not configure, check, or apply schedules. Run the command locally on\neach host; ambient `PASEO_HOME` and `PASEO_HOST` values are ignored.\n\nThis is a bundled model-routing convention implemented with existing Paseo\nmetadata and preferred no-force archive commands, not a new daemon feature,\ntimer, state engine, or native UI grouping/filter. Paseo 0.7.2 performs the\nrunning-state check before its archive API call, so it cannot guarantee atomic\nidle-only archival; the convention requires owner quiescence, no pending\nlaunches, and an immediate recheck, retaining ambiguous workers. Each future\nrun gets an identity made from its human task slug, full parent agent ID, and a\nfresh run discriminator. The bundled task-lifecycle reference is the\nauthoritative procedure: it keeps workflow chats available until completion\nand requires exit reconciliation before a final response, handoff, or driver\narchive. Exact rosters plus launch/reuse and current label-update receipts bind\nsupported background CLI launches even when `ParentAgentId` is null; mismatched\nnon-null parentage is retained. Cross-run reuse first settles the prior run,\nthen re-rosters and relabels the exact agent. Provider-native subagents remain\ninside their owning Paseo agent's report and never receive Paseo lifecycle\ncommands. Existing chats are not inferred or migrated. Phone and desktop\nclients on the same daemon see the same metadata; each independent agent host\nmust run its own Haoshoku configuration.\n\nOrdinary documentation uses `docs`; PR correctness and requirements review\nuse `pr-correctness` and `pr-requirements`. Targeted web research uses\n`research-web`. Recurring PR monitoring uses `pr-monitor`, while the independent\n`pr-watchdog` checks its health. Exact profile defaults are 21 total: 2 high, 10\nmedium, 6 low, 2 xhigh, and 1 max:\n\n- Xhigh: `explore-codebase` and `explainer` (Sonnet), as explicit fixed\n exceptions rather than a blanket escalation policy.\n- High: `pr-security`, `pr-architecture`.\n- Max: `explainer-review` (Luna), independently reviewing the exact artifact.\n- Medium: `planning-advisor`, `research-requirements`, `research-code`,\n `implement-code`, `review-code`, `pr-correctness`, `pr-integration`,\n `pr-requirements`, `pr-complexity`,\n `explainer-content-review`.\n- Low: `research-web`, `docs`, `pr-monitor`, `pr-watchdog`,\n `explore-execution`, `explainer-content`.\n\nThe bundled Grok provider is disabled; no active workflow role selects it.\nIts compatibility definition preserves existing authentication without enabling usage. During an upgrade,\nHaoshoku removes superseded managed workflow IDs only when their replacement is\npresent in the bundled policy; custom profile IDs and provider secrets remain\nuntouched.\n\nOrdinary peer PR review and implementation checkpoints use one `review-code`\nsession covering Standards, Spec and the shared simplicity checklist directly.\nThe six-angle workflow is reserved for an explicit six-angle request or\ndocumented, substantial high-risk work needing genuinely distinct coverage. A\ndirect invocation of upstream `code-review` retains its two-axis native-subagent\nmethod.\n\nPR babysitting launches the Opus monitor and watchdog as separate sessions.\nEach owns its own expiring heartbeat; healthy ticks update snapshots without\nwaking the driver, while failures and renewal needs are deduplicated and sent\nto the driver for acknowledgement and coordination.\n\nSubstantial research starts with the profile matching the unresolved question;\nanother researcher is added only for a distinct unresolved question or high-risk\nindependent validation. Requested visual artifacts use the\n`explainer` presentation profile and the pinned upstream visual-explainer;\nsource-content and independent visual review profiles remain available when\nthe artifact's risk warrants them. Ordinary prose stays prose, with no\nmandatory Markdown-to-HTML chain. Upgrades retire the former `research-sonnet`\nand `explainer-sonnet` IDs only when their respective replacements are bundled.\nPrefer Astra at low effort when choosing the main conversation; the actual\nselected model remains the driver. Escalation is bounded to the reasoning work\nthat needs it; outside the two fixed Sonnet roles, xhigh is reserved for an\nexplicit exceptional request, and unrelated work returns to low. Fable Advisor (`planning-advisor`) runs at\nmedium and is consulted only for unresolved consequential decisions after cheap\nfactual checks; there is no dedicated Astra advisor profile or mandatory\ntwo-advisor council. High-stakes decisions still require Fable's plain AGREE and\nthe driver's accepted assessment; an unavailable Fable pauses only that\ndecision unless the user explicitly overrides the gate. Ordinary nontrivial\nchanges use a Sol medium author and an independent Opus medium reviewer.\nHigh-stakes changes use an Opus high author and a fresh Sol high reviewer; the\nsame author owns fixes, and the reviewer session must have authored none of the\ncandidate, including uncommitted work. Simple known edits stay direct.\nDiscovery, workspace ownership and unchanged skill references are cached for\nthe task and refreshed on relevant configuration or capability changes.\n\n## Claude Remote Control\n\nThe optional Claude Remote Control setup runs persistent Claude sessions from\nthree fixed roots: `haki` at `$HOME`, `dev` at `$HOME/dev`, and `work` at\n`$HOME/Work`. Instances whose roots do not exist are skipped with a warning.\nOn Omarchy, `haoshoku-special-workspace haki` opens the tagged Ghostty `haki`\nsplit on its special workspace, with Claude above a fresh Codex pane below;\nit has no default keybinding. KDE uses its own Warp `agents` route.\nSet `claudeSessionName` in\n`~/.haoshoku.json` only to resume a named Haki Claude session. A missing or null\nvalue starts plain Claude; a\nsyntactically invalid value is preserved, reported, and ignored. A valid name is\npassed as one literal argument to `claude -r`, but it resumes directly only when\nthe name resolves uniquely; otherwise Claude may open its picker. This\nHaki launcher never attaches to tmux\nor calls systemd.\n\nThese sessions run Claude Remote Control in **server mode**\n(`claude remote-control --spawn same-dir --capacity 5`): each is a persistent\nhost that spawns up to five on-demand sessions in its own directory, launched\nwith `--permission-mode bypassPermissions`. The Arch setup calls this out\nbefore installation. The user services enable\nsystemd lingering when possible so sessions can survive logout; if lingering\ncannot be enabled automatically, setup prints the exact `loginctl` command to\nrun.\n\nInstallation sets `bypassPermissionsModeAccepted: true` in `~/.claude.json`.\nThis machine-wide acceptance affects every Claude Code session, not only the\nthree managed services, and persists until manually reverted. To undo it, edit\n`~/.claude.json` and remove `bypassPermissionsModeAccepted` or set it to\n`false`.\n\nAttach to any enabled managed session from a terminal with:\n\n```bash\n~/.local/bin/haoshoku-claude-remote-control attach haki\n~/.local/bin/haoshoku-claude-remote-control attach dev\n~/.local/bin/haoshoku-claude-remote-control attach work\n```\n\nDeploy or snapshot the supervisor and user unit independently with:\n\n```bash\nhaoshoku --claude-remote-control\nhaoshoku --claude-remote-control-backup\n```\n\n## Gaming\n\nAccepting the gaming prompt installs a portable Arch gaming base:\n\n- Steam\n- GameMode and its 32-bit library\n- Gamescope\n- MangoHud and its 32-bit library\n- ProtonUp-RS\n\nOn Omarchy, Haoshoku also invokes Omarchy's GPU-aware helper for the correct\n32-bit Vulkan/NVIDIA libraries. Other Arch distributions are not given guessed\nGPU packages.\n\n## Bash additions\n\nThe managed fragment exposes both package-installed Bun and a user installation\nunder `~/.bun/bin`, and provides guarded initialization for Starship, direnv,\nzoxide, thefuck, pyenv, and Conda, plus the aliases formerly kept in the Fish\nconfiguration. Machine-local secrets can be stored in\n`~/.config/haoshoku/secrets.bash`; that file is never copied into this repo.\n\n## One-shot configuration\n\n```bash\nhaoshoku --claude\nhaoshoku --claude-backup\nhaoshoku --claude-remote-control\nhaoshoku --claude-remote-control-backup\nhaoshoku --claude-update\nhaoshoku --codex\nhaoshoku --codex-backup\nhaoshoku --server-t3-code\nhaoshoku --server-paseo\nhaoshoku --device-type laptop\nhaoshoku --kde-connect-commands\nhaoshoku --audio\nhaoshoku --audio-backup\nhaoshoku --mimeapps\nhaoshoku --mimeapps-backup\nhaoshoku --skills\nhaoshoku --skills-update\nhaoshoku --skills-list\nhaoshoku --agent-skills\nhaoshoku --agent-skills-backup\nhaoshoku --explainer-theme dark\nhaoshoku --paseo-tasks\nhaoshoku --paseo-tasks-enabled disabled\nhaoshoku --paseo-task-renaming disabled\nhaoshoku --paseo-task-cleanup keep\nhaoshoku --paseo-schedules\nhaoshoku --paseo-schedules-check\nhaoshoku --paseo-schedules-apply\nhaoshoku --paseo-profiles\nhaoshoku --paseo-profiles-backup\nhaoshoku --gh-stack\nhaoshoku --claude-stay-awake\nhaoshoku --pr-watch\nhaoshoku --worktree-cleanup\nhaoshoku --workspaces\nhaoshoku --gaming\nhaoshoku --gaming-split-lock\nhaoshoku --gaming-steam-autostart disabled\nhaoshoku --gaming-omakade-autostart enabled\nhaoshoku --monitors\nhaoshoku --hyprmoncfg-backup\nhaoshoku --omarchy-plugins\nhaoshoku --omarchy-bar\nhaoshoku --omarchy-bar-backup\nhaoshoku --omarchy-appearance\nhaoshoku --discord-theme\nhaoshoku --3-4-migrate\n```\n\nOn Omarchy, the primary desktop app starts on workspace 1. Meta+1 brings its\nwindow to workspace 1 and focuses it; Meta+6 brings it to workspace 6 and\nfocuses it. If the app is closed, either key launches it before placing it on\nthe selected workspace. The default is Orca (`stably-orca`). To switch to T3 Code,\nput `t3code` in `~/.config/haoshoku/primary-app` and run `hyprctl reload`.\nHaoshoku creates this file on the first `--workspaces` setup and preserves your\nchoice on later runs. Other apps can use their desktop executable name; the\ndesktop entry's `StartupWMClass` identifies their window.\n\nUse `haoshoku --device-type pc` or `laptop` to override automatic detection.\nLater full Arch-family setups honor that stored explicit value.\n\n`haoshoku --3-4-migrate` is a re-runnable, idempotent migration from an\nOmarchy 3 layout to Omarchy 4: it strips dead `source =` lines, removes\norphaned overlay `.conf` files, repoints theme paths, backs up and clears\nOmarchy's stock `monitors.lua`, deploys the Lua overlay and hyprmoncfg\nprofiles, installs plugins, and validates — and if Omarchy's legacy config\nshim is still present it reports validation deferred and asks for a reboot\nand re-run instead of claiming success.\n\nRun `haoshoku --help` for the complete current list.\n\n## Debian Server\n\n```bash\nhaoshoku --os debian-server\n```\n\nThe Debian path remains deliberately headless. In addition to server hardening,\nit installs the portable Claude/Codex policy, Matt Pocock and upstream Paseo\nskills, Haoshoku-owned workflow skills, PR-watch, and the native Paseo daemon.\nPaseo is required and its managed orchestration policy is synced after the\nservice is ready. T3 Code is an optional, default-No compatibility step.\n\nWhen T3 Code is selected, Haoshoku ensures its current Node.js runtime range\nbefore installing and verifying the upstream-managed service. It then inspects\nT3 Connect's machine-readable status. An existing\nprovisioned link is left running without reauthorization or restart. Otherwise,\nHaoshoku runs `npx --yes t3@latest connect link --headless` in the attached\nterminal, allowing T3 to install and verify its managed relay client and guide\nyou through browser authorization. It updates and restarts `t3code.service`,\nwaits for the environment link and relay to become ready, and verifies the\nservice again. The service belongs to the account that runs Haoshoku, including\nroot when root ownership is intentional.\n\nT3 remains bound to `127.0.0.1:3773`; Haoshoku does not create an Nginx virtual\nhost, change DNS, open that port, or add a firewall rule. After setup, open the\nT3 Code phone app, choose T3 Connect, and sign in with the same account used\nduring authorization. The phone does not need Tailscale. Run\n`haoshoku --server-t3-code` to install or repair only this complete server\ncomponent; normal Debian setup offers the same flow without removing existing\nT3 installations or sessions when declined.\n\nIf the server previously used Haoshoku v8.5.3's Tailscale integration, inspect\n`tailscale serve status` after confirming T3 Connect works. Only when it still\nshows the old T3 HTTPS handler, remove that handler with\n`tailscale serve --https=443 off`. `No serve config` means cleanup is already\ncomplete; Haoshoku never changes existing Tailscale routes automatically.\n\nThe full Debian path asks about Git, Claude stay-awake, Claude Remote Control,\nautomatic worktree cleanup, and optional T3 Code. `haoshoku --skills` refreshes\nboth declared external skill sources independently using Bun's `bunx` runner.\n\n### Native headless Paseo\n\nRun `haoshoku --server-paseo` directly as the account that should own Paseo.\nNormal login users and direct root logins are supported; do not prefix a\nnon-root run with `sudo` unless root ownership is intentional. Haoshoku installs\n`@getpaseo/cli` under `~/.local`, writes a new `~/.paseo/config.json` only when\nnone exists, and manages `paseo-daemon.service` as that account's systemd user\nservice. For root this means `/root/.local`, `/root/.paseo`, and the root user\nmanager at `/run/user/0/bus`. If that manager is unavailable, Haoshoku stops\nwith recovery guidance instead of targeting another user's session. A new config\nlistens on `127.0.0.1:6767`, enables the Paseo MCP endpoint, disables relay,\nand keeps the bundled web UI off. An existing valid JSON object is left\nbyte-for-byte untouched, so its listen, authentication, relay, providers,\nprofiles, and unknown settings remain authoritative. Edit that file directly,\nthen use `paseo reload`; restart only when Paseo reports a restart-required\nsetting.\n\nThe unit runs `paseo daemon start --foreground --home ~/.paseo`, restarts only\nafter failure, and enables user lingering for startup after reboot and logout.\nHaoshoku refuses to replace a foreign unit or take over an unmanaged/desktop\ndaemon. Useful lifecycle and recovery commands are:\n\n```bash\nsystemctl --user status paseo-daemon.service\nsystemctl --user restart paseo-daemon.service\njournalctl --user -u paseo-daemon.service -n 100\npaseo daemon status --home ~/.paseo\n```\n\nIn an attached terminal Haoshoku optionally runs\n`paseo daemon pair --relay --home ~/.paseo`; otherwise it prints that command\nfor later. Pairing enables Paseo's end-to-end encrypted relay and creates a\nphone offer. It does not authenticate an agent provider or prove that a phone\nconnected. For local-only access, keep relay disabled and connect through\nPaseo's SSH transport; Haoshoku does not open a port or alter the firewall.\n\nTo operate a VPS from a PC agent without enabling a public Paseo port, first\nconfigure and verify a normal SSH alias in `~/.ssh/config`, then pass that alias\nafter each Paseo subcommand (the installed 0.7.2 CLI does not accept a global\n`--host` before the command):\n\n```bash\nssh my-vps\npaseo ls --host ssh://my-vps --json\npaseo reload --host ssh://my-vps --json\n```\n\nThe desktop app can keep the local PC and VPS available through the same app.\nFor phone access, run the pairing command on each desired host and accept its\nencrypted relay offer in the app. SSH and relay are independent; neither flow\ncauses Haoshoku to expose port 6767.\n\nThis setup does not install or authenticate provider CLIs. Install and log in\nto Claude Code, Codex, or another enabled provider separately as\nthe same user, then verify the daemon's environment and available models:\n\n```bash\npaseo provider diagnostic codex\npaseo provider models codex\n```\n\nThe standalone `--server-paseo` flag remains lifecycle-only. Full Debian setup\nfollows it with `--paseo-profiles` behavior; use that one-shot flag explicitly\nafter editing the bundled policy. Browser tools require a connected Paseo\ndesktop app because the headless daemon brokers browser tabs but does not host\na browser itself.\n\n### VPS Hermes conversation relay\n\n`haoshoku --server-hermes-relay` configures a generic Telegram-to-Paseo\nconversation transport only on a Debian-family server. Its legacy native plugin\nname and data path remain `paseo-review-relay` for compatibility. The full\nDebian setup runs this step after native Paseo and the managed Paseo profiles.\nArch/Omarchy setup never calls it and never creates its enable marker.\n\nAn existing Hermes installation is reused and never upgraded. If Hermes is\nmissing, Haoshoku downloads the official installer and installs the validated\ncommit from [`configs/hermes-relay/hermes-runtime.json`](configs/hermes-relay/hermes-runtime.json)\nwith `--skip-setup --skip-browser --skip-computer-use --non-interactive`. That\nbootstrap deliberately leaves credentials and gateway setup to the operator.\nComplete those private steps without placing secrets in this repository:\n\n1. Run `hermes setup` and configure the Telegram bot token in `~/.hermes/.env`.\n2. Set one private Telegram owner/DM in Hermes. Haoshoku derives IDs only when\n the existing private configuration is unambiguous; otherwise set\n `telegramChatId` and `telegramUserId` in\n `~/.hermes/plugin-data/paseo-review-relay/config.json`.\n3. Install login startup with\n `hermes gateway install --no-start-now --start-on-login`, start or verify the\n gateway manually, then rerun `haoshoku --server-hermes-relay`.\n\nMissing credentials, an unverifiable local Paseo identity, plugin doctor\nfailure, or pending activation returns failure rather than reporting success.\nThe helper preserves Hermes YAML, auth, unrelated plugins, database, and relay\nanchors; it backs up a changed plugin directory, deploys only allowlisted files,\nand creates `~/.local/bin/hermes-relay` as a symlink. A changed installation is\nrestarted only after an interactive confirmation that the gateway is idle. A\nrequired activation deferred because the gateway is busy, an unknown gateway\nstate, and an incomplete noninteractive run revoke the host marker. An\nunchanged, previously activated relay remains enabled while its running gateway\nis busy. Haoshoku never restarts Paseo or changes schedules.\n\nRelay source is controlled by [`configs/hermes-relay/lock.json`](configs/hermes-relay/lock.json).\nIt pins the public `paseo-hermes-relay` v0.2.0 release to immutable commit\n`73846214657a165379a1698b6bccff6c9c9e484f`. Haoshoku fetches that exact commit,\nverifies both `HEAD` and the peeled tag, and rejects mismatches. An offline test\ncheckout may be supplied with `HAOSHOKU_HERMES_RELAY_SOURCE=/absolute/path`; the\nsame commit, tag, and manifest checks still apply.\n\nOnly a fully configured and activated server receives\n`~/.config/haoshoku/hermes-relay.json` with `version: 1` and `enabled: true`.\nBundled PR workflows must run their `hermes-relay-host-enabled` check before any\nrelay command, pending-state inspection, or escalation transport. A missing or\ndisabled marker means normal local handling in the Paseo conversation with no\nHermes or remote relay calls. Bundled PR workflows explicitly use `mode: \"pr\"`,\nwhose receipts retain the live GitHub head/base/open-state guard. Generic\nconversation receipts are separately opt-in delivery only: they do not activate\nlocal work, and the persistent owner must revalidate authority, context, and live\nstate before acting. High-stakes decisions and action authority stay with the\nhuman in the Paseo conversation.\n\nDebian Server does not ask for `deviceType`: that value only selects desktop\naudio and Hyprland/Omarchy variants. For the same reason the Debian path does\nnot deploy audio, browser/MIME integration, the desktop-oriented user-script\nbundle, Brave managed policies, Hyprland monitors/workspaces, or Omazed. Those\nsteps remain on the Arch/Omarchy path instead of being installed onto a\nheadless server for superficial symmetry.\n\n## Development\n\n```bash\nbun install\nbun test\nbun run lint\n```\n","readmeFilename":"README.md"}
![\"Haoshoku\"](\"icons/haoshoku-readme.gif\")