This is the full developer documentation for Dotfiles # Overview > Public Omarchy dotfiles managed with GNU Stow and the dot command. These are my public [Omarchy](https://omarchy.org) dotfiles (Omarchy is an Arch Linux based distro), managed with [GNU Stow](https://www.gnu.org/software/stow/) and a single compiled `dot` binary. They cover shell, editor, and desktop config, plus the tooling that keeps multiple machines in sync. These are my personal dotfiles They are tightly tuned for my [Omarchy](https://omarchy.org) setup and my specific machines, and are **not** meant to be installed as-is by anyone else. They are unlikely to work on plain Arch (or any other distro) without replicating my setup, and they lean on a deeply integrated private overlay (`dotfiles-private`) that is not public, so the public repo on its own is an incomplete picture. Use them as a reference to borrow from, or pull individual pieces into your own dotfiles, rather than as a turnkey setup. The shared [OpenCode](https://opencode.ai) config (agents, commands, skills, and plugins) is the exception: it is published separately as [`opencode-config`](https://github.com/timmo001/opencode-config) and deliberately written to be portable and reusable on its own. AI-generated Large parts of this project - including this documentation and much of the codebase - are generated or heavily assisted by LLMs and coding agents. Expect the rough edges that come with that, and verify anything before relying on it. ## At a glance [Section titled “At a glance”](#at-a-glance) Stow-based dotfiles Public config for shell, editor, and tooling, rooted at `~/.config/dotfiles` and laid down with GNU Stow. The dot binary A single compiled binary ([Bun](https://bun.sh) + [Effect](https://effect.website) v4 + [OpenTUI](https://github.com/anomalyco/opentui)) with a TUI dashboard and a full CLI for setup, updates, and git tooling. Git & GitHub tooling Diff, log, status, workflow runs, and a notification inbox across every managed repo, with status-bar modules. Omarchy & Hyprland Managed Omarchy repos and per-host Hyprland overrides, with a desktop controls menu. OpenCode & agents Shared agents, commands, skills, and plugins, published to [opencode-config](https://github.com/timmo001/opencode-config). Private overlay A deeply integrated private overlay (`~/.config/dotfiles-private`) layers machine-specific config on top of the public repo. ## Get started [Section titled “Get started”](#get-started) [Getting Started ](/getting-started/)Bootstrap a fresh machine and run the ongoing workflow. [New Machine Checklist ](/getting-started/new-machine/)Step-by-step setup for a new Omarchy machine. ## Explore [Section titled “Explore”](#explore) [The dot Command ](/dot/)The TUI dashboard and CLI, with the stow, notes, and utilities workflows. [Git & GitHub ](/git/)Diff, log, status, workflow runs, and notifications. [Omarchy & Hyprland ](/omarchy/)Managed Omarchy repos and per-host Hyprland overrides. [OpenCode & Agents ](/opencode/)Agents, commands, skills, and plugins, with the generated reference. [Configuration & Reference ](/configuration/)Environment options, private git config, and private packages. # Bar Integrations > The --bar-json status-bar contract shared by dot commands and external tools. `--bar-json` is a shared status-bar contract rather than a single command. Tools emit one-line `--bar-json` output (with `text`, `tooltip`, and `class` fields) meant to be polled by a status bar module through its own short-lived cache. Left click opens the relevant TUI; right click refreshes the cache. The JSON format is bar-agnostic: it works with [Waybar](https://github.com/Alexays/Waybar), [Quickshell](https://quickshell.outfoxxed.me), or any bar that can run a command and parse JSON. My own setup uses Waybar, so the bundled modules and `dot doctor` checks target Waybar, but the commands themselves do not depend on it. ## dot commands with bar output [Section titled “dot commands with bar output”](#dot-commands-with-bar-output) [Status & Diff ](/git/status/)dot git-diff --bar-json flags managed repos that have uncommitted or unpushed changes. [Workflow Runs ](/git/workflows/)dot git-workflows --bar-json --since surfaces recent GitHub Actions activity for each repo's checked-out commit. [Notifications ](/git/notifications/)dot git-notifications --bar-json shows the GitHub notification inbox; left click opens the filtered TUI. The [command reference](/dot/commands/) lists the full `--bar-json` flag set on each command. ## External applications [Section titled “External applications”](#external-applications) `--bar-json` is not limited to `dot`. Other tools in this setup emit the same bar-friendly JSON, so one bar can poll them the same way. [go-automate](https://go-automate.timmo.dev) is one example: its [`--bar-json` reference](https://go-automate.timmo.dev/reference/bar-json/) documents the Home Assistant watcher output it exposes to a status bar. ## Configuration [Section titled “Configuration”](#configuration) Which repos and which activity reach the bar is controlled by the private `dot-git.yml` config; the `notifications.bar.ignore_bot_activity` key tames bot noise. See [Private Git Config](/configuration/private-git/). ## Health checks [Section titled “Health checks”](#health-checks) `dot doctor` verifies the active status-bar module wiring for `git-workflows` and `git-notifications`, alongside `dot-git.yml` and the absence of legacy `git-workflow-watch` leftovers. # Configuration > Environment options and private git configuration. Most behaviour is controlled by explicit CLI flags. Runtime configuration is done with environment variables for process context, and a private YAML file for git/GitHub repo tracking. [Environment Variables ](/configuration/environment/)All DOT\_\*, DOTFILES\_\*, and OMARCHY\_\* options. [Private Git Config ](/configuration/private-git/)The dot-git.yml schema for repo activity, workflows, and notifications. [Private Packages ](/configuration/private-packages/)Build and publish Arch packages to the private pacman repo. Configuration policy For dotfiles and system scripts, prefer explicit CLI flags over environment-variable toggles for runtime behaviour. Environment variables are used for standard process context (`HOME`, `PATH`, `XDG_*`), secrets, paths, and compatibility shims. # Environment Variables > All DOT_*, DOTFILES_*, and OMARCHY_* options that influence dot. These variables tune paths and behaviour for `dot`. Most have sensible defaults; set them only when you need to override the default. ## Paths and overlay [Section titled “Paths and overlay”](#paths-and-overlay) | Variable | Description | | ---------------------- | -------------------------------------------------------------- | | `DOTFILES_PUBLIC_DIR` | Public dotfiles path (default `~/.config/dotfiles`). | | `DOTFILES_PRIVATE_DIR` | Private dotfiles path (default `~/.config/dotfiles-private`). | | `DOT_ALLOW_PRIVATE` | `auto\|always\|never` (default `auto`). | | `DOT_PRIVATE_GH_USER` | Expected GitHub user for private actions (default `timmo001`). | ## Git and GitHub [Section titled “Git and GitHub”](#git-and-github) | Variable | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DOT_GIT_CONFIG_FILE` | Private git repo config for `git-diff`, `git-log`, `git-workflows`, `git-notifications --bar-json`, `update`, and `doctor` (default `$DOTFILES_PRIVATE_DIR/dot-git.yml`). | | `DOT_INCLUDE_OMARCHY_DIFF_REPOS` | Include Omarchy repos in `dot git-diff` (`1\|0`, default `1`). | | `DOT_INCLUDE_OMARCHY_UPDATE_REPOS` | Include Omarchy repos in `dot update` sync (`1\|0`, default `1`). | | `DOT_FETCH_TTL_SECONDS` | Seconds to reuse the last upstream fetch (default `300`). | | `DOT_AUTO_CD` | zsh wrapper auto-cd to the first repo with changes after `dot git-diff` (`1\|0`, default `1`). | ## Private packages [Section titled “Private packages”](#private-packages) | Variable | Description | | -------------------------------- | --------------------------------------------------------------------------------------- | | `DOT_PRIVATE_PACKAGE_REPO_FILE` | Private pacman repo config (default `$DOTFILES_PRIVATE_DIR/.dot-private-package-repo`). | | `DOT_PRIVATE_PACKAGES_FILE` | Private package list (default `$DOTFILES_PRIVATE_DIR/.dot-private-packages`). | | `DOT_PRIVATE_PACMAN_REPO_CONFIG` | Pacman repo snippet path written by `dot` (default `/etc/pacman.d/timmo-private.conf`). | ## Omarchy and Hyprland [Section titled “Omarchy and Hyprland”](#omarchy-and-hyprland) | Variable | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | `OMARCHY_REPO_BASE_DIR` | Omarchy repo base path (default `~/.config`). | | `OMARCHY_HOST` | Hypr host override name; `dot init` defaults to `desktop` when unset unless `--host ` is passed. | | `DOT_OMARCHY_BRANCH` | Branch override for non-bootstrap Omarchy repos during sync. | | `DOT_BOOTSTRAP_BRANCH` | Branch for `bootstrap` sync (default `distro/omarchy`). | ## Init and timers [Section titled “Init and timers”](#init-and-timers) | Variable | Description | | ---------------------------------- | ------------------------------------------------------------------------------------- | | `DOT_INIT_NONINTERACTIVE` | Force non-interactive init mode (`1\|0`, default `0`). | | `DOT_INIT_LOG_FILE` | Default `dot init` log path when `--log` is not passed (default `/tmp/dot-init.log`). | | `DOT_DAILY_VOLUME_ZERO_TIMER_UNIT` | 5am volume reset timer unit name (default `daily-volume-zero.timer`). | ## Agents sync [Section titled “Agents sync”](#agents-sync) | Variable | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `DOT_AGENTS_SYNC_SOURCE` | AGENTS file to mirror (default `~/.config/opencode/AGENTS.md`). | | `DOT_AGENTS_SYNC_RULE_FILE` | Cursor rule output path (default `$DOTFILES_PRIVATE_DIR/agents/.cursor/rules/global-agents.mdc`, else `~/.cursor/rules/global-agents.mdc`). | | `DOT_AGENTS_SYNC_ON_UPDATE` | Run `agents-sync` after `dot update` (`1\|0`, default `1`). | ## Notes [Section titled “Notes”](#notes) | Variable | Description | | --------------- | ------------------------------------------------------------------------------------------------------------- | | `NOTES` | Notes vault git repo used by `dot notes` and OpenCode note commands (preferred; default `~/Documents/notes`). | | `DOT_NOTES_DIR` | Compatibility notes vault override used when `NOTES` is unset. | # Private Git Config > The dot-git.yml schema for repo activity, workflows, and notifications. The git and GitHub tooling reads a private YAML config that lists the repositories to track and how. It lives in the private overlay at `$DOTFILES_PRIVATE_DIR/dot-git.yml` by default (override with `DOT_GIT_CONFIG_FILE`). It is consumed by `dot git-diff`, `dot git-log`, `dot git-workflows`, `dot git-notifications --bar-json`, `dot update`, and `dot doctor`. ## Per-repo keys [Section titled “Per-repo keys”](#per-repo-keys) Each repo entry has three required sections, each with an explicit `enabled` flag and a 5-field cron `schedule`: * `activity` — include the repo in `dot git-diff` / `dot git-log` and pull it during `dot update`. * `workflows` — show the repo’s GitHub Actions runs in `dot git-workflows`. * `notifications` — include the repo in the notification inbox surfaces. The `notifications.bar.ignore_bot_activity` key controls status-bar bot noise. A repo’s `remote.upstream.url` lets upstream notifications match a managed fork. Private by default `dot-git.yml` lives in the private dotfiles overlay because it contains a machine- and user-specific repository list. The public dotfiles only contain the logic that reads it. ## Requirements [Section titled “Requirements”](#requirements) * `dot git-notifications` requires `gh` authenticated with a classic token carrying the `notifications` or `repo` scope. * `dot doctor` verifies `dot-git.yml`, the active status-bar module wiring, and the absence of legacy `git-workflow-watch` leftovers. # Private Packages > Build and publish Arch packages to the private pacman repo. `dot` can build and publish mapped private packages into a private pacman repository, and register the repo include in `pacman.conf`. ## Register the private repo [Section titled “Register the private repo”](#register-the-private-repo) ```bash dot setup-private-repo ``` Syncs the private Arch package repo mirror, writes the private pacman repo snippet, and adds the `Include` line to `/etc/pacman.conf` when it is missing. This repairs Omarchy `pacman.conf` refreshes that remove local repository includes. Privileged writes prefer `pkexec` and fall back to `sudo`. ## Publish a package [Section titled “Publish a package”](#publish-a-package) ```bash dot private-pkg-publish dot private-pkg-publish --install dot private-pkg-publish --skip-build --no-git ``` Builds and publishes a mapped private package into the private pacman repo, syncs the mirror, refreshes pacman metadata, optionally installs it, and commits/pushes by default. | Flag | Effect | | -------------- | ------------------------------------------------------- | | `--no-git` | Skip the package repo commit and push. | | `--skip-build` | Publish an existing dist package artifact. | | `--install` | Install the published package after syncing the mirror. | ## Configuration [Section titled “Configuration”](#configuration) Private package sources and the repo config live in the private overlay: * `DOT_PRIVATE_PACKAGE_REPO_FILE` — private pacman repo config (default `$DOTFILES_PRIVATE_DIR/.dot-private-package-repo`). * `DOT_PRIVATE_PACKAGES_FILE` — private package list (default `$DOTFILES_PRIVATE_DIR/.dot-private-packages`). * `DOT_PRIVATE_PACMAN_REPO_CONFIG` — pacman repo snippet path written by `dot` (default `/etc/pacman.d/timmo-private.conf`). See [Environment Variables](/configuration/environment/) for the full list. # The dot Command > The TUI dashboard and CLI that drives the dotfiles system. `dot` is the single binary that manages these dotfiles. It is compiled from `dot/` in the repo ([Bun](https://bun.sh) + [Effect](https://effect.website) v4 + [OpenTUI](https://github.com/anomalyco/opentui)) to a single executable, stowed to `~/.local/bin/dot`. It has two faces: * **A TUI dashboard** — run `dot` with no arguments to open the interactive menu, with git diff/log views, GitHub workflow runs, the notification inbox, repo notes, Omarchy menus, git staging, and AI commit suggestions. * **A native CLI** — every action is also a subcommand (`dot update`, `dot git-diff --raw`, `dot doctor`, …), suitable for scripts and status bars. [Command Reference ](/dot/commands/)Every command, alias, flag, and example, generated from the CLI registry. [Stow Workflow ](/dot/stow/)How packages are stowed into your home directory. [Notes & Handoffs ](/dot/notes/)The repository notes browser and handoff workflow. [System Utilities ](/dot/utilities/)Health checks, benchmarks, and optional timers. ## Common commands [Section titled “Common commands”](#common-commands) | Command | What it does | | ---------------- | -------------------------------------------------------- | | `dot init` | One-time first-use setup for a fresh machine. | | `dot update` | Self-update, install deps, rebuild, pull, stow, restart. | | `dot stow` | Stow refresh only (no git pull). | | `dot doctor` | Run dotfiles system health checks. | | `dot git-diff` | Diff / repo watcher view across managed repos. | | `dot git-status` | Branch status for the current repo (agent context). | | `dot omarchy` | Open the Omarchy desktop controls menu. | See the full [Command Reference](/dot/commands/) for every subcommand and flag. ## Source of truth [Section titled “Source of truth”](#source-of-truth) Command and flag metadata lives in `dot/src/cli/spec.ts`. Help rendering, shell completions, and the generated [Command Reference](/dot/commands/) all read from that one registry, so they never drift. When a command changes, the reference page is regenerated from `spec.ts`. # Command Reference > Every dot command, alias, flag and example, generated from the CLI registry. This page lists every `dot` command, generated from the same registry that powers `dot help` and shell completions. Run any command with `--help` to see the same details at the terminal. ## `dot init` [Section titled “dot init”](#dot-init) Run one-time first-use machine setup ```text dot init [options] ``` Run the one-time first-use setup workflow for a fresh machine. Init prepares repos, stow links, mise tools, packages, machine hooks, and then finishes by running dot update. After init completes, use dot update for ongoing maintenance. **Options** | Option | Description | | ----------------------------- | ----------------------------------------------------------------------------------------------- | | `--confirm` | Acknowledge non-interactive package helpers | | `--noninteractive` | Skip interactive prompts for this run | | `--interactive` | Allow interactive prompts for this run | | `--host` `` | Hypr host to link before stow (default: OMARCHY\_HOST or desktop) (one of: `desktop`, `laptop`) | | `--log` `` | Init log path (default: /tmp/dot-init.log) | | `--branch` `` | Branch override for non-bootstrap Omarchy repos | | `--bootstrap-branch` `` | Branch override for bootstrap | **Examples** ```bash dot init --noninteractive --confirm dot init --host laptop --noninteractive --confirm dot init --branch main --bootstrap-branch distro/omarchy ``` ## `dot install` [Section titled “dot install”](#dot-install) Ensure prerequisites, then backup/adopt dotfiles ```text dot install ``` ## `dot update` [Section titled “dot update”](#dot-update) Pull repos, stow dotfiles, install deps, rebuild ```text dot update ``` **Options** | Option | Description | | ------------- | -------------------------------------------------------------------- | | `--pull` | Pull repos only | | `--stow` | Stow only | | `--tui` | Install deps and rebuild dot binary only | | `--check` | Report core/system repos behind upstream (no update); exit 10 if any | | `--check-all` | Report all tracked repos behind upstream (no update); exit 10 if any | ## `dot stow` [Section titled “dot stow”](#dot-stow) Re-stow public/private dotfiles ```text dot stow ``` **Options** | Option | Description | | ----------- | -------------------------- | | `--public` | Stow public dotfiles only | | `--private` | Stow private dotfiles only | ## `dot doctor` [Section titled “dot doctor”](#dot-doctor) Run dotfiles system health checks ```text dot doctor [options] ``` Run health checks on the dotfiles system. Verifies dependencies, repos, stow integrity, systemd timers, packages, browser config, and more. All checks run in parallel. Results are printed per-section with a grouped summary at the end. A log file is always written to \~/.local/state/dot/logs/. **Options** | Option | Description | | ----------------- | ----------------------------------- | | `--open-opencode` | Save report and open it in OpenCode | **Checks performed** ```text Dependencies Required/optional CLI tools (git, stow, gh, gum, ...) Secret Service kwallet vs gnome-keyring provider Repositories Public/private dotfiles + private git repos exist and have upstreams Origin HEAD Local origin/HEAD tracks the remote default branch (not stale) Stow integrity Dry-run restow to detect drift OpenCode location Canonical paths, legacy remnants Git config Managed include is active Workflow runs Repo list, status bar config, legacy watcher cleanup Git notifications API scope and status bar notification module wiring Doctor startup Startup notification timer Daily volume reset Laptop-only optional timer Omarchy repos Diff repos + worktree branch correctness Legacy Hypr repo Flags a retired omarchy-hypr clone at ~/.config/hypr Browser flags Symlinks from private stow package Hardware video VAAPI render nodes, drivers, packages Browser extensions Private extension check list Public packages AUR packages installed + version check Private packages Private repo + packages installed Pacman hooks Hook files installed and up to date ``` **Exit codes** ```text 0 No critical errors (warnings may still be present) 1 One or more critical errors found ``` **Examples** ```bash dot doctor dot doctor --open-opencode ``` ## `dot clean` [Section titled “dot clean”](#dot-clean) Unstow managed dotfiles ```text dot clean ``` ## `dot git-diff` [Section titled “dot git-diff”](#dot-git-diff) Aliases: `dot diff` Open the git diff/repo watcher view ```text dot git-diff [options] ``` Open the diff/repo watcher view. Without flags, opens the interactive TUI. **Modes** ```text (default) Interactive TUI diff view --raw Text summary of repos with changes --bar-json JSON output for status bars and shell modules --list-changed Changed repos as name|path rows --list-all All tracked repos as name|path rows ``` **Options** | Option | Description | | ---------------- | ----------------------------------------------------------------------------------------- | | `--no-fetch` | Skip fetching from remotes (use local refs only) | | `--tab` `` | Initial pane to focus in TUI (default: changed) (one of: `changed`, `other`, `unchanged`) | | `--raw` | Text summary output | | `--bar-json` | JSON output for status bars and shell modules | | `--list-changed` | Changed repos as rows | | `--list-all` | All tracked repos as rows | **Examples** ```bash dot git-diff dot git-diff --raw dot git-diff --bar-json dot git-diff --tab other ``` ## `dot git-status` [Section titled “dot git-status”](#dot-git-status) Show branch status for the current repository ```text dot git-status [options] ``` Print unstaged files, staged files, and the last 10 commits — each with a compact relative timestamp, a pushed/local remote marker, and its changed files inline with (+added -deleted) line counts — for the current git repository. Designed as a single command for agents to get full working-tree and branch context. Substitutes running these separately: git status, git diff —stat / git diff —numstat, git diff —cached —stat, git log —oneline —stat, and git log @{upstream}..HEAD (ahead/pushed check). Add —diff to append the full unstaged and staged diffs under their sections, and —branch-diff to append the full diff of the current branch against the default branch (measured from their merge base so committed and uncommitted changes both show). —branch-diff errors on the default branch, where that range is empty. The flags combine. **Modes** ```text (default) Status summary: unstaged, staged, recent commits --diff Also print full unstaged and staged diffs --branch-diff Also print the full diff vs the default branch ``` **Options** | Option | Description | | --------------- | ------------------------------------------------------------------------------- | | `--diff` | Append full unstaged and staged diffs for changed files | | `--branch-diff` | Append the merge-base diff vs the default branch (errors on the default branch) | **Examples** ```bash dot git-status dot git-status --diff dot git-status --branch-diff dot git-status --diff --branch-diff ``` ## `dot git-log` [Section titled “dot git-log”](#dot-git-log) Open recent commits across tracked repos ```text dot git-log [options] ``` Open the recent commit history view. The left pane lists tracked repositories from dot git-diff, sorted by latest commit activity. The right pane lists recent commits for the selected repository. **Modes** ```text (default) Interactive git log TUI --raw Text summary of recent commits ``` **Options** | Option | Description | | ------- | ------------------------------ | | `--raw` | Text summary of recent commits | **Examples** ```bash dot git-log dot git-log --raw ``` ## `dot git-workflows` [Section titled “dot git-workflows”](#dot-git-workflows) Open watched GitHub workflow runs ```text dot git-workflows [options] ``` Open the watched GitHub workflow runs view. The left pane lists watched repositories from the private repo list. The right pane lists runs for the selected repo’s locally checked-out HEAD commit. **Modes** ```text (default) Interactive workflow runs TUI --raw Text summary of watched workflow runs --bar-json JSON output for status bars and shell modules --list-repos Watched repo summaries as rows --list-runs Workflow runs as rows ``` **Options** | Option | Description | | ------------------ | -------------------------------------------------------------- | | `--since` `` | Only include runs active at or after this date (ISO/RFC/epoch) | | `--raw` | Text summary of watched workflow runs | | `--bar-json` | JSON output for status bars and shell modules | | `--list-repos` | Watched repo summaries as rows | | `--list-runs` | Workflow runs as rows | **Examples** ```bash dot git-workflows dot git-workflows --raw dot git-workflows --bar-json dot git-workflows --since "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" dot git-workflows --list-runs ``` ## `dot git-notifications` [Section titled “dot git-notifications”](#dot-git-notifications) Open GitHub notification inbox ```text dot git-notifications [options] ``` Open the authenticated user’s GitHub notification inbox. Without machine or action flags, opens the interactive TUI. **Modes** ```text (default) Interactive notifications TUI --raw Text summary of notification threads --bar-json JSON output for status bars and shell modules --list-threads Notification threads as rows --bar-filter Apply watched-repo filtering in raw/list output ``` **Options** | Option | Description | | -------------------- | --------------------------------------------------------- | | `--raw` | Text summary of notification threads | | `--bar-json` | JSON output for status bars and shell modules | | `--list-threads` | Notification threads as rows | | `--bar-filter` | Apply watched-repo filtering in raw/list output | | `--all` | Include read notifications | | `--participating` | Only include participating or mentioned threads | | `--since` `` | Only include notifications updated after this date | | `--mark-read` `` | Mark a notification thread as read | | `--mark-bot-read` | Mark unread Renovate/Dependabot/bot notifications as read | | `--dry-run` | Preview —mark-bot-read without mutating GitHub state | | `--mark-done` `` | Mark a notification thread as done | | `--ignore` `` | Ignore future notifications for a thread | | `--unignore` `` | Stop ignoring future notifications for a thread | **Examples** ```bash dot git-notifications dot git-notifications --bar-json dot git-notifications --participating dot git-notifications --mark-bot-read --dry-run dot git-notifications --mark-read 12345 ``` ## `dot notes` [Section titled “dot notes”](#dot-notes) Open repository notes or run note utility commands ```text dot notes [--all] [command] [options] ``` Manage repository notes used by OpenCode note commands. **Modes** ```text (default) Interactive notes TUI --all Interactive notes TUI across all repos ``` **Options** | Option | Description | | ------- | ------------------------------------------ | | `--all` | Show notes from every repo-notes directory | **Examples** ```bash dot notes dot notes --all dot notes root dot notes context --command notes-list dot notes list --all dot notes list --format json ``` ### `dot notes root` [Section titled “dot notes root”](#dot-notes-root) Print the notes vault root ```text dot notes root ``` **Options** | Option | Description | | -------------- | -------------------------------- | | `--repo-notes` | Print repository notes directory | ### `dot notes context` [Section titled “dot notes context”](#dot-notes-context) Print the context block for OpenCode notes ```text dot notes context ``` **Options** | Option | Description | | -------------------- | --------------------- | | `--command` `` | OpenCode command name | ### `dot notes list` [Section titled “dot notes list”](#dot-notes-list) List repository notes ```text dot notes list ``` **Options** | Option | Description | | --------------------- | ------------------------------------------ | | `--all` | Show notes from every repo-notes directory | | `--format` \`\\` | ## `dot handoffs` [Section titled “dot handoffs”](#dot-handoffs) Aliases: `dot handoff` Open handoff notes ```text dot handoffs [--all] [--list] ``` Open the interactive notes TUI filtered to notes tagged handoff. Use —list for a plain text listing without the TUI. **Options** | Option | Description | | -------- | ---------------------------------------------------- | | `--all` | Show handoff notes from every repo-notes directory | | `--list` | List handoff notes to stdout without opening the TUI | **Aliases** ```text dot handoff dot handoffs ``` ## `dot note` [Section titled “dot note”](#dot-note) Read, write, or delete note files ```text dot note [options] ``` Read, write, and delete note files. Writes and deletes are committed to the notes vault when possible. **Examples** ```bash dot note read --path ~/Documents/notes/repo-notes/owner/repo/topic.md dot note write --path /tmp/notes/repo-notes/owner/repo/topic.md --stdin dot note delete --path /tmp/notes/repo-notes/owner/repo/topic.md ``` ### `dot note read` [Section titled “dot note read”](#dot-note-read) Print a note file ```text dot note read ``` **Options** | Option | Description | | ----------------- | -------------- | | `--path` `` | Note file path | ### `dot note write` [Section titled “dot note write”](#dot-note-write) Write stdin to a note file and commit it ```text dot note write ``` **Options** | Option | Description | | ----------------- | ---------------------------- | | `--path` `` | Note file path | | `--stdin` | Read note content from stdin | ### `dot note delete` [Section titled “dot note delete”](#dot-note-delete) Delete a note file and commit it ```text dot note delete ``` **Options** | Option | Description | | ----------------- | -------------- | | `--path` `` | Note file path | ## `dot agents-sync` [Section titled “dot agents-sync”](#dot-agents-sync) Sync AGENTS.md to Cursor rule ```text dot agents-sync ``` ## `dot opencode-debug` [Section titled “dot opencode-debug”](#dot-opencode-debug) Debug OpenCode config and paths ```text dot opencode-debug ``` **Options** | Option | Description | | ------------------ | ------------------------------- | | `--agent` `` | Debug a specific OpenCode agent | ## `dot setup-private-repo` [Section titled “dot setup-private-repo”](#dot-setup-private-repo) Register private pacman repo include ```text dot setup-private-repo ``` Sync the private Arch package repo mirror, write the private pacman repo snippet, and add the Include line to /etc/pacman.conf when it is missing. This repairs Omarchy pacman.conf refreshes that remove local repository includes. Privileged writes prefer pkexec and fall back to sudo. **Examples** ```bash dot setup-private-repo ``` ## `dot private-pkg-publish` [Section titled “dot private-pkg-publish”](#dot-private-pkg-publish) Build and publish a private package ```text dot private-pkg-publish [options] ``` Build and publish a mapped private package into the private pacman repo. **Options** | Option | Description | | -------------- | ------------------------------------------------------ | | `--no-git` | Skip package repo commit and push | | `--skip-build` | Publish an existing dist package artifact | | `--install` | Install the published package after syncing the mirror | **Arguments** | Argument | Description | | ---------------- | ----------- | | `` | | **Examples** ```bash dot private-pkg-publish twitch-notifications --install dot private-pkg-publish --skip-build --no-git twitch-notifications ``` ## `dot skill-updates` [Section titled “dot skill-updates”](#dot-skill-updates) Check/apply imported skill updates ```text dot skill-updates ``` **Options** | Option | Description | | --------------- | --------------------------- | | `--check` | Check only without applying | | `--update` | Auto-apply clean updates | | `--skip-review` | Skip local-edit review | ## `dot skill-check` [Section titled “dot skill-check”](#dot-skill-check) Validate skill references ```text dot skill-check ``` **Options** | Option | Description | | ----------------- | -------------------------------------------------------------------------------------------------------- | | `--open-opencode` | Run checks then open OpenCode analysis | | `--diff-origin` | Diff imported skills against their upstream origins; with —open-opencode, include the diff in the prompt | ## `dot completions` [Section titled “dot completions”](#dot-completions) Generate shell completions ```text dot completions [zsh] [--stdout] ``` Generate shell completions for dot. By default this writes the managed Zsh completion file in the public dotfiles repo so the next dot stow installs it to \~/.local/share/zsh/site-functions/\_dot. **Options** | Option | Description | | ---------- | ------------------------------------------------- | | `--stdout` | Print the completion script instead of writing it | **Arguments** | Argument | Description | | --------- | -------------- | | `` | One of: `zsh`. | **Examples** ```bash dot completions zsh dot completions zsh --stdout ``` ## `dot omarchy` [Section titled “dot omarchy”](#dot-omarchy) Open an Omarchy submenu by path ```text dot omarchy [submenu...] ``` Open the Omarchy desktop controls menu. Pass a submenu path to jump straight to it: dot omarchy theme Theme submenu dot omarchy theme set Execute theme set directly **Arguments** | Argument | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Repeatable. One of: `theme`, `font`, `toggle`, `capture`, `system`, `launch`, `refresh`, `restart`, `install`, `remove`, `packages`, `share`, `reminder`, `setup`, `snapshot`, `brightness`, `power`. | **Available submenus** ```text theme Theme management font Font management toggle Toggle system features capture Screenshots and recordings system Lock, logout, reboot, shutdown launch Launch applications refresh Refresh system components restart Restart system services install Install software and tools remove Remove software and features packages Package management share Share clipboard, files, folders reminder Reminders setup DNS, security setup snapshot System snapshots brightness Display and keyboard brightness power Power profiles ``` ## `dot help` [Section titled “dot help”](#dot-help) Show this help menu ```text dot help ``` # Notes & Handoffs > The repository notes browser and the handoff workflow. `dot` includes a repository notes system used by the OpenCode note commands. Notes live in a notes vault git repo (`~/Documents/notes` by default, overridable with the `NOTES` environment variable). Inside the vault, notes are filed per repository under `repo-notes/{owner}/{repo}/`, keyed off the current git remote and branch. There are two ways into the same vault: * The **`dot notes` / `dot note` CLI** below, for humans browsing and editing notes directly. * The **OpenCode integration** ([slash commands, plugins, and the handoff skill](#opencode-integration)), for agents creating and loading notes during a session. ## Browse notes [Section titled “Browse notes”](#browse-notes) ```bash dot notes # two-pane repository notes browser (TUI) dot notes --all # browse every repo-notes directory (or press g in the TUI) dot notes list --all # CLI listing grouped by repo ``` Utility subcommands: ```bash dot notes root # print the notes vault root dot notes root --repo-notes # print the repository notes directory dot notes context --command # print the OpenCode notes context block dot notes list --format json # list current repo notes as JSON ``` ## Handoffs [Section titled “Handoffs”](#handoffs) Handoffs are notes tagged `handoff`, used to pass context between agents or sessions. ```bash dot handoffs # notes browser filtered to handoff notes (TUI) dot handoffs --all # handoffs across every repo dot handoffs --list # list handoff notes to stdout ``` `dot handoff` is an alias for `dot handoffs`. ## Read / write note files [Section titled “Read / write note files”](#read--write-note-files) ```bash dot note read --path # print a note file dot note write --path --stdin # write stdin to a note file and commit it dot note delete --path # delete a note file and commit it ``` Writes and deletes are committed to the notes vault when possible. ## OpenCode integration [Section titled “OpenCode integration”](#opencode-integration) Agents do not touch the vault with the `dot note` CLI directly. The same files are created and loaded inside an OpenCode session through a set of slash commands, backed by two plugins. ### Slash commands [Section titled “Slash commands”](#slash-commands) | Command | What it does | | ----------------- | ----------------------------------------------------------------------------------------- | | `/note-create` | Summarise the current conversation into a new note for this repo. | | `/note-append` | Add new content to an existing note (pick from a ranked list). | | `/note-reference` | Load one or more notes, any skills they reference, and suggested next steps into context. | | `/notes-list` | List this repo’s notes, optionally filtered by tag. | | `/notes-search` | Rank this repo’s notes against a topic, keyword, or tag. | | `/handoff` | Write a handoff document for the next agent session. | | `/handoffs-list` | List handoff notes for this repo (equivalent to `/notes-list handoff`). | See the [commands reference](/reference/commands/) for the full list. ### How it works [Section titled “How it works”](#how-it-works) Two OpenCode [plugins](/reference/plugins/) wire the commands to the vault: * **`repo-notes`** injects a `` block at the top of each note command. It runs `dot notes context --command `, which resolves the owner, repo, and branch from git and reports the target notes path. For listing and search commands it also includes existing note metadata; `/note-reference` additionally gets the full note bodies. The plugin also registers the `note_read`, `note_write`, `note_delete`, and `note_list` tools, each a thin wrapper over the `dot note` CLI. * **`notes-guard`** blocks the built-in `read`, `write`, `edit`, `grep`, `glob`, `list`, and `bash` tools from touching the vault, so the `note_*` tools are the only way in. So a typical create flow is: run `/note-create` → `repo-notes` injects the repo context → the command summarises the conversation and calls `note_write` → `dot note write` validates the path, writes the file, and commits it to the vault. ### Handoffs [Section titled “Handoffs”](#handoffs-1) `/handoff` defers to the [`handoff` skill](/reference/skills/), which compacts the conversation into a `handoff-{slug}.md` note tagged `handoff`. For work spanning multiple phases, branches, or PRs, the skill offers to split the handoff rather than writing one combined note, using a shared `handoff-{feature}-{phase}` naming convention so related handoffs group together under `dot handoffs --list`. ## Configuration [Section titled “Configuration”](#configuration) * `NOTES` — notes vault git repo (preferred; default `~/Documents/notes`). * `DOT_NOTES_DIR` — compatibility override used when `NOTES` is unset. # Stow Workflow > How dotfiles packages are applied into your home directory with GNU Stow. The repository is a [GNU Stow](https://www.gnu.org/software/stow/) package root targeting `~/`. Each top-level directory (`zsh`, `neovim`, `starship`, `hypr`, `scripts`, …) is a stow package whose contents are symlinked into your home directory. ## Always use `dot stow` [Section titled “Always use dot stow”](#always-use-dot-stow) Apply packages with `dot stow` (or `dot update`, which refreshes stow). Do **not** run GNU `stow` directly from the repo root: `dot` applies the correct adopt / no-folding flow and the public-then-private ordering. ```bash dot stow # stow public + private dot stow --public # public only dot stow --private # private only ``` ## What `dot stow` does [Section titled “What dot stow does”](#what-dot-stow-does) * Lays down public packages first, then the private overlay from `~/.config/dotfiles-private`. * Stows the Hypr package with `--no-folding` and creates/repairs the `~/.config/hypr/host` symlink for the active host. * Adopts existing files where needed so a fresh machine does not clobber stock config. ## Ignore rules [Section titled “Ignore rules”](#ignore-rules) `.stowrc` sets the stow target and ignore rules. Files that should never be symlinked into `~/` are ignored there, including top-level docs, the `dot/` source, the `docs/` site, and repo metadata. Keep `.stowrc` ignore rules in sync when adding root-only files. Caution The repo root stows to `~/`. Anything not ignored in `.stowrc` becomes a symlink under your home directory. When adding new root-level files or directories that should not be stowed (such as `docs/`), add a matching `--ignore` rule. ## Health check [Section titled “Health check”](#health-check) `dot doctor` runs a dry-run restow to detect drift, alongside its other checks. Run it after changing stow packages to confirm nothing is broken. # System Utilities > Health checks, benchmarks, and optional timers. ## System health check [Section titled “System health check”](#system-health-check) `system-health-check` is a friendly multi-snapshot system health report covering CPU, memory, network, pressure, and known logs. ```bash system-health-check # write a health report system-health-check --open-opencode # run opencode run against the report, then open an interactive session ``` Add `--open-opencode` to run `opencode run` against the saved report and then open a full interactive OpenCode session with `opencode --continue`. ## Benchmarks and tests [Section titled “Benchmarks and tests”](#benchmarks-and-tests) The repo includes minimal system-wide benchmark and resource-leak test scripts under `.benchmarks/` and `.tests/` (excluded from stow): * `.benchmarks/system-quick-bench.sh` — short CPU/memory/network benchmark snapshot. * `.tests/system-resource-leak-test.sh` — short leak and growth check over time. ```bash # Quick benchmark (minimal defaults) .benchmarks/system-quick-bench.sh # Include LAN throughput (requires an iperf3 target) .benchmarks/system-quick-bench.sh --iperf-host 192.168.1.50 # Resource leak test (short run) .tests/system-resource-leak-test.sh ``` * Benchmarks write outputs to `.benchmarks/output/`; tests write to `.tests/output/` (both gitignored). * LAN network throughput is opt-in and requires `--iperf-host`. * Scripts use ANSI colour output by default; set `NO_COLOR=1` to disable. * All scripts include an uptime/load snapshot near the top of output. ## Daily volume reset (laptop only) [Section titled “Daily volume reset (laptop only)”](#daily-volume-reset-laptop-only) Public dotfiles provide `daily-volume-zero.timer` in laptop-only stow packages (`scripts--laptop` and `systemd--laptop`), a user systemd timer that runs at 5am local time. * The timer runs `daily-volume-zero`, which sends a 10-second desktop notification, clears default sink mute, then sets the default PipeWire/WirePlumber sink volume to `0%`. * It is optional and not enabled by `dot`. Enable it on machines that should use it: ```bash systemctl --user enable --now daily-volume-zero.timer ``` # Getting Started > Bootstrap a fresh Omarchy machine and run the ongoing dotfiles workflow. The dotfiles are designed to bootstrap a fresh [Omarchy](https://omarchy.org) machine and then keep it in sync with a single command. Start with the install guide, then use the checklist for a clean walkthrough. Personal dotfiles These are my own dotfiles, tuned for [Omarchy](https://omarchy.org) and my machines, and they lean on a deeply integrated private overlay that is not public. Don’t install them wholesale on a machine you care about, and don’t expect them to work on plain Arch without replicating my setup. Read them, take the bits you want, and fold them into your own dotfiles instead. The steps below are how *I* set up a new machine, documented for reference. [Install ](/getting-started/install/)Prerequisites, bootstrap build, and the ongoing workflow. [New Machine Checklist ](/getting-started/new-machine/)A numbered, end-to-end setup for a new machine. ## How it fits together [Section titled “How it fits together”](#how-it-fits-together) * Public dotfiles live at `~/.config/dotfiles` and are applied with GNU Stow. * Optional private dotfiles at `~/.config/dotfiles-private` overlay machine-specific config. * The [`dot`](/dot/) binary owns setup (`dot init`), ongoing sync (`dot update`), and day-to-day tooling. Note The `dot` binary is compiled from `dot/` in the repo. On a fresh machine you build it once with system `mise` before it is on your `PATH`. See [Install](/getting-started/install/). # Install > Prerequisites, bootstrap build, and the ongoing dotfiles workflow. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) On a fresh [Omarchy](https://omarchy.org) machine, install the bootstrap build prerequisites ([git](https://git-scm.com) and [mise](https://mise.jdx.dev)): ```bash sudo pacman -S --needed git mise ``` If you want the private dotfiles overlay, authenticate [`gh`](https://cli.github.com) (the GitHub CLI) before `dot init` so it can clone `dotfiles-private` automatically: ```bash gh auth status || gh auth login ``` ## Clone and build [Section titled “Clone and build”](#clone-and-build) Clone the public dotfiles first, then build the `dot` binary before it is on your `PATH`: ```bash git clone git@github.com:timmo001/dotfiles.git ~/.config/dotfiles cd ~/.config/dotfiles/dot mise --no-config exec bun@latest -- bun install mise --no-config exec bun@latest -- bun run build ``` ## First-use setup [Section titled “First-use setup”](#first-use-setup) `dot init` runs the one-time first-use setup: it bootstraps private dotfiles when `gh auth` is available, syncs Omarchy repos, selects the Hypr host, installs and adopts config, installs stowed mise tools, sets up packages and machine hooks, syncs agents, and finishes with `dot update`. It logs to `/tmp/dot-init.log` by default. ```bash ~/.config/dotfiles/scripts/.local/bin/dot init --noninteractive --confirm ``` For a laptop, select the laptop host: ```bash dot init --host laptop --noninteractive --confirm ``` Or run `dot init` in an interactive shell to be prompted. Note If stock Omarchy directories already exist at `~/.config/waybar`, `~/.config/ghostty`, or `~/.config/uwsm`, `dot init` backs them up with a `.dot-init-backup-*` suffix before cloning the managed repos. Hyprland config is stowed from the `hypr/` package instead. ## Ongoing workflow [Section titled “Ongoing workflow”](#ongoing-workflow) After restarting your shell so `dot` is on `PATH`: ```bash dot update # self-update, install deps, rebuild, pull, stow, restart dot git-diff # review changes across managed repos dot doctor # health checks ``` `dot update` is the everyday command: it self-updates the public dotfiles, installs dependencies, rebuilds and restarts on the new binary, then runs Omarchy and public/private pulls, a stow refresh, and Hypr host-link setup. See the [Command Reference](/dot/commands/) for the full flag list. # New Machine Checklist > Step-by-step setup for a new Omarchy machine. A clean, end-to-end walkthrough for setting up a new machine. 1. Clone `dotfiles` to `~/.config/dotfiles`. 2. If you want private dotfiles, confirm `gh auth status` works before `dot init`; init clones `dotfiles-private` to `~/.config/dotfiles-private` automatically when auth is available. 3. Install bootstrap build prerequisites: ```bash sudo pacman -S --needed git mise ``` 4. Build the `dot` binary: ```bash cd ~/.config/dotfiles/dot mise --no-config exec bun@latest -- bun install mise --no-config exec bun@latest -- bun run build ``` 5. Run first-use setup: * Desktop / VM: `~/.config/dotfiles/scripts/.local/bin/dot init --noninteractive --confirm` * Laptop: `dot init --host laptop --noninteractive --confirm` * Interactive: `dot init` in an interactive shell 6. If stock Omarchy config directories already exist at `~/.config/waybar`, `~/.config/ghostty`, or `~/.config/uwsm`, `dot init` backs them up with a `.dot-init-backup-*` suffix before cloning the managed repos. Hyprland config is stowed from the `hypr/` package instead. 7. Restart your shell and confirm `dot help` is on `PATH`. 8. Run `dot git-diff` and verify the expected repo state. 9. Run `dot update` for ongoing sync, stow, rebuild, and init-state backfill. Hypr host and mise tools `dot init` selects the Hypr host early (setting `OMARCHY_HOST`), and the stow phase of the final update creates `~/.config/hypr/host`. It runs `mise install` immediately after stowing dotfiles and before installing managed Arch/AUR package lists, so Bun, Node, pnpm, and similar tools come from the stowed mise config rather than global pacman packages. GNOME Boxes shared folders Arch provides `spice-webdavd` in the `phodav` package. Share a host folder from Boxes and pass `--log /dot-init.log` when you want init output written somewhere visible from the host. # Git & GitHub > Diff, log, status, workflow runs, and a notification inbox across managed repos. `dot` includes a suite of git and GitHub tools that work across every managed repo (public and private dotfiles, configured private git repos, and Omarchy repos). Most have an interactive TUI plus `--raw` and `--bar-json` output for scripts and status bars. [Status, Diff & Log ](/git/status/)Branch status, diff/repo watcher, and recent commit history. [Workflow Runs ](/git/workflows/)Watched GitHub Actions runs for each repo's checked-out HEAD. [Notifications ](/git/notifications/)The GitHub notification inbox with read/done/ignore actions. ## Status bar integration [Section titled “Status bar integration”](#status-bar-integration) Several of these commands emit `--bar-json` output for a status bar module. See [Bar Integrations](/bar-integrations/) for the JSON format, click actions, and which commands support it. ## Private repo configuration [Section titled “Private repo configuration”](#private-repo-configuration) Repo activity, workflow, and notification settings live in the private `dot-git.yml` config. See [Private Git Config](/configuration/private-git/) for the schema. # Notifications > The GitHub notification inbox with read, done, ignore, and bot-read actions. ## `dot git-notifications` [Section titled “dot git-notifications”](#dot-git-notifications) The authenticated user’s GitHub notification inbox. Without machine or action flags it opens the interactive TUI with open, mark-read, done, ignore, unignore, and bot-read actions. ```bash dot git-notifications # interactive TUI dot git-notifications --raw # text summary of notification threads dot git-notifications --bar-json # JSON for status bars and shell modules dot git-notifications --list-threads # notification threads as rows dot git-notifications --participating # only participating or mentioned threads dot git-notifications --all # include read notifications ``` ### Actions [Section titled “Actions”](#actions) ```bash dot git-notifications --mark-read # mark a thread read dot git-notifications --mark-done # mark a thread done dot git-notifications --ignore # ignore future notifications for a thread dot git-notifications --unignore # stop ignoring a thread ``` ### Bot notifications [Section titled “Bot notifications”](#bot-notifications) ```bash dot git-notifications --mark-bot-read --dry-run # preview matched bot threads dot git-notifications --mark-bot-read # mark Renovate/Dependabot/bot threads read ``` Use `--dry-run` first to preview the threads that would be marked. ## Requirements [Section titled “Requirements”](#requirements) The notification API requires `gh` authenticated with a classic token carrying the `notifications` or `repo` scope. ## Status bar module [Section titled “Status bar module”](#status-bar-module) A status bar module refreshes `dot git-notifications --bar-json` through its own short-lived cache. Notification surfaces hide repos that are not enabled in `dot-git.yml`, while upstream notifications can match a managed fork’s `remote.upstream.url`. Left click opens `dot git-notifications --bar-filter`; right click refreshes the cache. `dot doctor` verifies GitHub notification API access plus the active notification module wiring. # Status, Diff & Log > Branch status, the diff/repo watcher, and recent commit history. ## `dot git-status` [Section titled “dot git-status”](#dot-git-status) Branch status for the current repository, designed as a single command for agents to get full working-tree and branch context. It prints unstaged files, staged files, and the last 10 commits — each with a compact relative timestamp, a pushed/local remote marker, and its changed files inline with `(+added -deleted)` line counts. ```bash dot git-status # status summary dot git-status --diff # also print full unstaged and staged diffs dot git-status --branch-diff # also print the full diff vs the default branch ``` It substitutes running these separately: `git status`, `git diff --stat` / `git diff --numstat`, `git diff --cached --stat`, `git log --oneline --stat`, and `git log @{upstream}..HEAD` (ahead/pushed check). The flags combine. `--branch-diff` measures from the merge base, so committed and uncommitted changes both show, and errors on the default branch where that range is empty. ## `dot git-diff` [Section titled “dot git-diff”](#dot-git-diff) The diff / repo watcher view. Without flags it opens the interactive TUI showing managed repos with changes, including fetched unpushed/incoming commit checks. The alias `dot diff` remains for compatibility. ```bash dot git-diff # interactive TUI dot git-diff --raw # text summary of repos with changes dot git-diff --bar-json # JSON for status bars and shell modules dot git-diff --tab other # focus the Other pane in the TUI dot git-diff --list-changed # changed repos as name|path rows dot git-diff --list-all # all tracked repos as name|path rows ``` Press Enter on a repo to launch [lazygit](https://github.com/jesse-duffield/lazygit) via suspend/resume. ## `dot git-log` [Section titled “dot git-log”](#dot-git-log) Recent commit history across the same tracked repos as `dot git-diff`, sorted by latest commit activity. ```bash dot git-log # interactive TUI dot git-log --raw # text summary of recent commits ``` # Workflow Runs > Watched GitHub Actions runs for each repo's locally checked-out HEAD commit. ## `dot git-workflows` [Section titled “dot git-workflows”](#dot-git-workflows) A two-pane view of watched GitHub workflow runs. The left pane lists watched repositories from the private repo list; the right pane lists runs for the selected repo’s locally checked-out HEAD commit. Disabled workflows are hidden. ```bash dot git-workflows # interactive TUI dot git-workflows --raw # text summary of watched workflow runs dot git-workflows --bar-json # JSON for status bars and shell modules dot git-workflows --list-repos # watched repo summaries as rows dot git-workflows --list-runs # workflow runs as rows dot git-workflows --since # only runs active at or after this date ``` The `--since` filter accepts ISO/RFC/epoch dates. For status bars, combine `--bar-json` with `--since`: ```bash dot git-workflows --bar-json --since "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" ``` ## Status bar module [Section titled “Status bar module”](#status-bar-module) A status bar module refreshes `dot git-workflows --bar-json --since ` through its own short-lived cache; left click opens the filtered TUI and right click refreshes the cache. `dot doctor` verifies `dot-git.yml`, the active workflow-runs module wiring, and the absence of legacy `git-workflow-watch` leftovers. Note The old `git-workflow-watch` hook and its user systemd timer are obsolete and should not be installed. # LLMs > Feed this documentation to an agent using llms.txt. This site publishes [llms.txt](https://llmstxt.org) files so you can hand the whole documentation to a language model or agent in one go. They are generated at build time from the same content as this site. | File | Contents | | ---------------------------------- | ----------------------------------------------------- | | [/llms.txt](/llms.txt) | Index and links to the documentation sets. | | [/llms-full.txt](/llms-full.txt) | The complete documentation as a single file. | | [/llms-small.txt](/llms-small.txt) | A compact version with non-essential content removed. | ## Using them [Section titled “Using them”](#using-them) Point an agent or model at the full set: ```text https://dotfiles.timmo.dev/llms-full.txt ``` Or share the index and let the tool pick the set it needs: ```text https://dotfiles.timmo.dev/llms.txt ``` The content is generated automatically from the same source as the official documentation, so it stays in sync with this site. # Omarchy & Hyprland > Managed Omarchy repos and per-host Hyprland overrides. These dotfiles run on [Omarchy](https://omarchy.org). Some Omarchy components are tracked as managed git repos that `dot` keeps in sync, while [Hyprland](https://hyprland.org) config is a stowed dotfiles package with per-host overrides. [Host Overrides ](/omarchy/host-overrides/)Managed Omarchy repos and per-host Hyprland config. [Controls ](/omarchy/controls/)The dot omarchy desktop controls menu. ## Managed Omarchy repos [Section titled “Managed Omarchy repos”](#managed-omarchy-repos) * `waybar`, `ghostty`, and `uwsm` are single-branch Omarchy repos expected on `main`. * `bootstrap` is expected on `distro/omarchy`. * `dot update` syncs these by default; `dot doctor` verifies their worktree branches. ## Hyprland [Section titled “Hyprland”](#hyprland) Hyprland config is **not** a tracked Omarchy repo. It is a stowed dotfiles package (`hypr/.config/hypr/`, conf-only) laid down with `--no-folding`, with host-specific overrides selected by a runtime symlink. See [Host Overrides](/omarchy/host-overrides/). # Controls > The dot omarchy desktop controls menu. ## `dot omarchy` [Section titled “dot omarchy”](#dot-omarchy) Opens the Omarchy desktop controls menu. Pass a submenu path to jump straight to it, or chain a path to execute an action directly. ```bash dot omarchy # open the controls menu (TUI) dot omarchy theme # jump to the Theme submenu dot omarchy theme set # execute theme set directly ``` ## Available submenus [Section titled “Available submenus”](#available-submenus) | Submenu | Controls | | ------------ | ------------------------------- | | `theme` | Theme management | | `font` | Font management | | `toggle` | Toggle system features | | `capture` | Screenshots and recordings | | `system` | Lock, logout, reboot, shutdown | | `launch` | Launch applications | | `refresh` | Refresh system components | | `restart` | Restart system services | | `install` | Install software and tools | | `remove` | Remove software and features | | `packages` | Package management | | `share` | Share clipboard, files, folders | | `reminder` | Reminders | | `setup` | DNS, security setup | | `snapshot` | System snapshots | | `brightness` | Display and keyboard brightness | | `power` | Power profiles | Tip When restarting Omarchy-managed apps, prefer `omarchy restart ` (via the `restart` submenu) over manual process kills. # Host Overrides > Managed Omarchy repos and per-host Hyprland configuration. ## Managed Omarchy repos [Section titled “Managed Omarchy repos”](#managed-omarchy-repos) `dot` tracks a small set of Omarchy components as git repos and keeps them on the expected branch: * `waybar`, `ghostty`, and `uwsm` — single-branch Omarchy repos expected on `main`. * `bootstrap` — expected on `distro/omarchy`. `dot init` clones these into `~/.config/{waybar,ghostty,uwsm}`. If a stock Omarchy config directory already exists there and is not a git repo, init moves it aside with a `.dot-init-backup-*` suffix before cloning. `dot update` syncs them, and `dot doctor` verifies their worktree branches. ## Hyprland host overrides [Section titled “Hyprland host overrides”](#hyprland-host-overrides) Hyprland config is a stowed dotfiles package (`hypr/.config/hypr/`, conf-only), not a tracked repo. Host-specific overrides live under `~/.config/hypr/hosts/$OMARCHY_HOST`, selected by the runtime `~/.config/hypr/host` symlink. * `dot stow` lays down the Hypr package with `--no-folding` and creates/repairs `~/.config/hypr/host` to point at the active host. * `dot init` selects the Hypr host early (via `--host `, defaulting to `OMARCHY_HOST` or `desktop`), and the stow phase creates the `host` symlink. * `dot doctor` checks the host link and flags any leftover legacy `omarchy-hypr` clone at `~/.config/hypr`. Retired omarchy-hypr clone A machine still on the retired `~/.config/hypr` `omarchy-hypr` clone halts `dot update` until the clone is backed up and re-stowed. Hyprland is now a stowed package, not a cloned repo. ## Environment [Section titled “Environment”](#environment) * `OMARCHY_HOST` — the Hypr host override name (e.g. `desktop`, `laptop`). * `OMARCHY_REPO_BASE_DIR` — Omarchy repo base path (default `~/.config`). * `DOT_OMARCHY_BRANCH` / `DOT_BOOTSTRAP_BRANCH` — branch overrides during sync. See [Environment Variables](/configuration/environment/) for the full list. # OpenCode & Agents > Shared OpenCode agents, commands, skills, and plugins. The repo ships a shared [OpenCode](https://opencode.ai) configuration: agents, slash commands, skills, and lifecycle plugins. The source lives in `agents/.config/opencode/` (agents, commands, plugins) and `agents/.agents/skills/` (skills shared by OpenCode and Codex via `~/.agents/skills/`). These are generated from this dotfiles repo and published automatically to [`timmo001/opencode-config`](https://github.com/timmo001/opencode-config) so they can be browsed, imported, and installed independently of the full dotfiles repo. The portable basis Unlike the rest of these (personal) dotfiles, the OpenCode config is built to be reused. `opencode-config` is a standalone, portable export with its own install instructions, so you can adopt individual agents, commands, skills, or plugins without taking on anything else here. [Agents ](/reference/agents/)Execution posture: permissions, tools, and delegation. [Commands ](/reference/commands/)Slash commands that route to agents and skills. [Skills ](/reference/skills/)Reusable workflows and behavioural contracts. [Plugins ](/reference/plugins/)Context, evidence, and enforcement hooks. ## How it fits together [Section titled “How it fits together”](#how-it-fits-together) * **Graduated agent permissions** — agents range from fully read-only (`reviewer`, `ask`) through ask-gated (`build-ask`) to edit-capable (`refactorer`, `build-locked`). A guard plugin stops read-only agents from escalating via subagent delegation. * **Skill-based routing** — commands are thin wrappers that name an agent, declare required skills, and state whether branch context is needed. The workflow logic lives in skills and plugins. * **Branch context injection** — the `branch-context` plugin pre-computes git/PR state once per command and injects it as structured XML, so commands do not run their own `git`/`gh` calls. * **Secret protection** — the `env-protection` plugin blocks reads of `.env` files (except `.env.example`). ## Tooling [Section titled “Tooling”](#tooling) * `dot agents-sync` — mirror `~/.config/opencode/AGENTS.md` into a Cursor rule. * `dot opencode-debug [--agent ]` — inspect resolved OpenCode config, paths, and skills. * `dot skill-updates` / `dot skill-check` — check/apply upstream skill updates and validate skill references. Publishing to `opencode-config` happens automatically via GitHub Actions on push. The Agents, Commands, Skills, and Plugins pages above are generated by `bun run gen:opencode` from the live assets, so they always match what ships — edit the source assets, not the generated pages. See also the generated [`dot` Command Reference](/dot/commands/). # Agents > OpenCode agents defined in this repo, with their permission posture. Agents set the execution posture (permissions, tool access, delegation) for OpenCode sessions. They are published to [`opencode-config`](https://github.com/timmo001/opencode-config) and loaded from `~/.config/opencode/agents/`. | Agent | Description | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`ask`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/ask.md) | Ask clarifying questions before taking action | | [`build-ask`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/build-ask.md) | Build agent that executes clear tasks and relies on permissions for write actions | | [`build-locked`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/build-locked.md) | Build agent that can edit files but cannot run shell commands | | [`general-readonly`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/general-readonly.md) | General-style parallel subagent that researches with read-only tools and a narrow shell inspection allowlist (for delegation from read-only primaries). | | [`grill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/grill.md) | Extended read-only planning interview agent for one-question-at-a-time grilling | | [`refactorer`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/refactorer.md) | Refactor code while preserving behavior and following local command and skill workflows | | [`reviewer`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/agents/reviewer.md) | Reviews code for quality, bugs, security, and best practices | # Commands > OpenCode slash commands defined in this repo. Commands are thin routing prompts: they name an agent, declare required skills or injected context, and define the output shape. They are loaded from `~/.config/opencode/commands/`. | Command | Description | Agent | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------ | | [`/all-lit-skills`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/all-lit-skills.md) | Apply all Lit rendering skills in current git scope | `default` | | [`/all-ts-skills`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/all-ts-skills.md) | Apply all TypeScript-specific skills in current git scope | `default` | | [`/check-skill-updates`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/check-skill-updates.md) | Check imported skills for upstream updates | `default` | | [`/debug-frontend`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/debug-frontend.md) | Debug browser-specific UI issues with Chrome DevTools tools first | `ask` | | [`/explore-codebase`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/explore-codebase.md) | Explore a codebase topic with the task explore subagent | `ask` | | [`/fallow-audit`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/fallow-audit.md) | Audit changed JavaScript or TypeScript code with Fallow | `ask` | | [`/fallow-project-analyse`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/fallow-project-analyse.md) | Analyse a JavaScript or TypeScript project with Fallow | `ask` | | [`/grill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/grill.md) | Stress-test a proposed change with one-question-at-a-time planning questions | `grill` | | [`/handoff`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/handoff.md) | Write a handoff document for the next agent session | `default` | | [`/handoffs-list`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/handoffs-list.md) | List handoff notes for the current repository | `default` | | [`/home-assistant/all-frontend-skills`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/home-assistant/all-frontend-skills.md) | Apply all Home Assistant frontend skills in current git scope | `default` | | [`/home-assistant/lazy-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/home-assistant/lazy-context.md) | Review and fix Home Assistant frontend lazy-context and memoization usage in current git scope | `default` | | [`/home-assistant/list-components`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/home-assistant/list-components.md) | Migrate Home Assistant list components from MWC to new primitives in current git scope | `default` | | [`/home-assistant/lit-rendering`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/home-assistant/lit-rendering.md) | Review and fix Home Assistant Lit rendering and picker callback-shape patterns in current git scope | `default` | | [`/home-assistant/replace-spacing`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/home-assistant/replace-spacing.md) | Replace hardcoded spacing values with ha-space tokens from core.globals.ts | `default` | | [`/import-external-skill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/import-external-skill.md) | Import or review external skills for the local skill library | `default` | | [`/improve-codebase-architecture`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/improve-codebase-architecture.md) | Review a codebase area for architectural friction and focused structural improvements | `plan` | | [`/inject-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/inject-context.md) | Inject branch context and optionally execute an instruction | `default` | | [`/investigate`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/investigate.md) | Investigate a topic, issue, or area without editing by default | `ask` | | [`/note-append`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/note-append.md) | Append new notes to an existing note file for the current repository | `default` | | [`/note-create`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/note-create.md) | Create a new note for the current repository in your Obsidian notes vault | `default` | | [`/note-reference`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/note-reference.md) | Load one or more notes, relevant skills, and next steps for the current repository | `default` | | [`/notes-list`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/notes-list.md) | List notes for the current repository, optionally filtered by tag | `default` | | [`/notes-search`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/notes-search.md) | Search notes for the current repository by topic, keyword, or tag | `default` | | [`/plan`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/plan.md) | Manual entrypoint to native plan mode from the current conversation context | `plan` | | [`/refactor-cleanup-variables`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/refactor-cleanup-variables.md) | Refactor - inline and remove unnecessary variables from current git scope | `refactorer` | | [`/refactor-current-work`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/refactor-current-work.md) | Refactor current branch work while preserving behaviour | `refactorer` | | [`/refactor-enforce-types`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/refactor-enforce-types.md) | Refactor - enforce TypeScript type safety in current git scope | `refactorer` | | [`/refactor-remove-single-use`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/refactor-remove-single-use.md) | Refactor - inline and remove safe single-use functions from current git scope | `refactorer` | | [`/reset-branch-reapply`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/reset-branch-reapply.md) | Reset branch to default and reapply current diff staged | `build` | | [`/review-current-work`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/commands/review-current-work.md) | Review current branch work with BranchContextPlugin context | `reviewer` | # Plugins > OpenCode lifecycle plugins defined in this repo. Plugins provide context, evidence, or enforcement hooks for OpenCode. They are loaded from `~/.config/opencode/plugins/`. | Plugin | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | [`branch-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/branch-context.ts) | Injects branch-context blocks into command prompts before execution | | [`env-protection`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/env-protection.ts) | Blocks direct access to .env files to prevent leaking secrets | | [`notes-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/notes-guard.ts) | Restricts file tools to the repository notes directory for note commands | | [`notification`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/notification.ts) | Plays a desktop notification sound when agent tasks complete | | [`readonly-subagent-task-guard`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/readonly-subagent-task-guard.ts) | Forces read-only primary agents to delegate only to non-modifying subagents | | [`repo-notes`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/repo-notes.ts) | Routes OpenCode note commands through `dot note` against the notes vault | | [`tui-dot-git-diff`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/tui-dot-git-diff.ts) | Registers a TUI keybinding (ctrl+shift+g) to open `dot git-diff` | | [`tui-lazygit`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.config/opencode/plugins/tui-lazygit.ts) | Registers a TUI keybinding to open lazygit | # Skills > OpenCode skills defined in this repo, including imported ones. Skills own reusable workflows and behavioural contracts. They are shared by OpenCode and Codex via `~/.agents/skills/` and published to [`opencode-config`](https://github.com/timmo001/opencode-config). ## Skills [Section titled “Skills”](#skills) | Skill | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`branch-context-consumer`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/branch-context-consumer/SKILL.md) | Consume BranchContextPlugin injections in commands. Use when a command depends on an injected block for its scope. | | [`check-skill-updates`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/check-skill-updates/SKILL.md) | Check imported skills for upstream changes and apply updates. Use when reviewing whether externally imported skills have new upstream content, or when `dot skill-updates` reports available changes. | | [`cleanup-unnecessary-variables`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/cleanup-unnecessary-variables/SKILL.md) | Safe unnecessary-variable cleanup guidance for code review and refactoring. | | [`dotfiles-stow`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/dotfiles-stow/SKILL.md) | REQUIRED when changing configs managed by \~/.config/dotfiles or \~/.config/dotfiles-private. Enforces editing stow source paths (not ad-hoc live paths) and using the dot command for stow/update/validation workflows. | | [`fallow-coexistence`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/fallow-coexistence/SKILL.md) | Guidance for using Fallow alongside code-quality and framework skills without conflict. Use when running Fallow or acting on its findings — applying fix/suppress suggestions, interpreting dead-code or complexity output, or analysing Effect, Lit, or Home Assistant code — to decide what to apply, what to verify first, and how to configure Fallow. | | [`git-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/git-context/SKILL.md) | Patterns for working with git branches, remotes, diffs against the default branch, and rebases. Use when resolving rebase conflicts, continuing interactive rebases, amending commits, or any git operation that would open an interactive editor. | | [`grill-questions`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/grill-questions/SKILL.md) | Run an extended one-question-at-a-time planning interview to stress-test a proposed change before implementation. Use when the user says grill, grill me, stress-test this plan, ask more questions, or wants to expand the planning/question window instead of moving straight to a plan. | | [`handoff`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/handoff/SKILL.md) | Compact the current conversation into a handoff document for another agent to pick up. | | [`home-assistant-frontend`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/home-assistant-frontend/SKILL.md) | Home Assistant frontend development with Lit Web Components and TypeScript. Use when working in the Home Assistant frontend repo, editing ha-\* components, reviewing HA PRs, or applying HA-specific conventions (localization, theming, dialogs, panels, cards). | | [`home-assistant-lazy-context`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/home-assistant-lazy-context/SKILL.md) | Home Assistant frontend lazy-context, memoization, and `hass` removal guidance. Use when migrating Lit components from `hass!: HomeAssistant`, `.hass=${...}`, or broad `hass` access to context slices. | | [`home-assistant-list-components`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/home-assistant-list-components/SKILL.md) | Home Assistant list component migration and usage guidance. Use when editing ha-list, ha-list-item, ha-md-list, or migrating to ha-list-nav, ha-list-selectable, ha-list-item-button, ha-list-item-option, or ha-list-item-base. | | [`home-assistant-lit-rendering`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/home-assistant-lit-rendering/SKILL.md) | Home Assistant Lit rendering extensions for HA components and context-aware picker callback shape. | | [`import-external-skill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/import-external-skill/SKILL.md) | Import skills from external repos into the local dotfiles skill library. Use when pulling in a skill from a public repo, reviewing an external skill set for useful additions, or adapting external skill content into existing local skills. | | [`lit-rendering`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/lit-rendering/SKILL.md) | Lit rendering and picker callback-shape guidance for editing and reviewing Lit components. | | [`pkexec-root`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/pkexec-root/SKILL.md) | Use pkexec first for commands that need root directly or indirectly. | | [`pr-review`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/pr-review/SKILL.md) | Guidelines for reviewing pull requests - what to analyze, review etiquette, and output formatting | | [`remove-single-use-functions`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/remove-single-use-functions/SKILL.md) | Safe single-use function removal guidance for code review and refactoring. | | [`safe-process-signals`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/safe-process-signals/SKILL.md) | Safe process killing and signal handling for agent/subprocess contexts. Use when running pkill, killall, kill, or any process termination command from a shell subprocess, automated script, or coding agent. | | [`types-enforce-ts`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/types-enforce-ts/SKILL.md) | TypeScript type-safety guidance for editing and reviewing `.ts`, `.tsx`, `.mts`, and `.cts` files. | | [`writing-style`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/writing-style/SKILL.md) | Write commit messages, PR and issue text, docs, code comments, and user-facing copy in the project owner’s voice: concise, human, UK English, no em-dashes, no robotic or marketing tone. Use when authoring or editing any commit message, pull request or issue description, README or docs, code comment, or user-facing string (notifications, UI labels, toasts, error messages). Defer to a repo’s established house style when it has one; otherwise this sets the default voice. | ## Imported Skills [Section titled “Imported Skills”](#imported-skills) These skills were imported from other repos and tracked with an `# origin:` marker. Some are used as-is; others are adapted for local workflows. | Skill | Description | Origin | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | [`ask-questions-if-underspecified`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/ask-questions-if-underspecified/SKILL.md) | Ask minimal clarifying questions only when ambiguity materially changes implementation. Use for routine underspecification; do not use for extended grilling, plan stress-testing, or broad design interviews. | [trailofbits/skills](https://github.com/trailofbits/skills/tree/main/plugins/ask-questions-if-underspecified/skills/ask-questions-if-underspecified) | | [`css-motion-systems`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/css-motion-systems/SKILL.md) | CSS motion design and implementation for web interfaces. Use when designing or building transitions, animations, `linear()` easing, transform strategy, View Transitions API patterns, motion tokens, or reviewing motion quality and accessibility. | [stolinski/s-stack](https://github.com/stolinski/s-stack/tree/main/skills/css-motion-systems) | | [`diagnose`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/diagnose/SKILL.md) | Disciplined diagnosis workflow for hard bugs, regressions, flaky behavior, and performance issues. Use when behavior is broken, failing, intermittent, or slower than expected and the agent needs a reproducible feedback loop before fixing. | [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnose) | | [`effect`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/effect/SKILL.md) | Work with Effect v4 / effect-smol TypeScript code. Use when writing, reviewing, or refactoring TypeScript code using the Effect library (Effect.gen, Context.Tag, Layer, Schema, Effect.fn). | [anomalyco/opencode](https://github.com/anomalyco/opencode/tree/dev/.opencode/skills/effect) | | [`fallow`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/fallow/SKILL.md) | Codebase intelligence for JavaScript and TypeScript. Free static layer finds unused code (files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence - a single local capture is free, while continuous/cloud runtime monitoring is paid. 94 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, find unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow. | [fallow-rs/fallow-skills](https://github.com/fallow-rs/fallow-skills/tree/main/fallow/skills/fallow) | | [`html`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/html/SKILL.md) | Writes and reviews semantic, accessible HTML and template markup that stays readable and low-noise. Use when creating or refactoring HTML or Svelte templates, cleaning up div soup, choosing better elements, improving form markup, fixing heading or landmark structure, or replacing custom controls with native HTML. | [stolinski/s-stack](https://github.com/stolinski/s-stack/tree/main/skills/html) | | [`improve-codebase-architecture`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/improve-codebase-architecture/SKILL.md) | Review a codebase area for architectural friction and propose focused structural improvements. Use when the user wants to improve maintainability, reduce coupling, simplify understanding, or identify where code should be consolidated or deepened. | [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) | | [`motion-choreography-patterns`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/motion-choreography-patterns/SKILL.md) | Use when orchestrating multi-element UI motion, stagger systems, list reorder/insert/remove flows, modal and overlay stacks, gesture-driven transitions, and route-level choreography that preserves hierarchy and attention. | [stolinski/s-stack](https://github.com/stolinski/s-stack/tree/main/skills/motion-choreography-patterns) | | [`opentui`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/opentui/SKILL.md) | Build terminal UIs with OpenTUI. Covers the core API, native audio, keymaps, React and Solid bindings, components, layout, keyboard input, plugins, and testing. | [anomalyco/opentui](https://github.com/anomalyco/opentui/tree/main/packages/web/src/content) | | [`write-a-skill`](https://github.com/timmo001/dotfiles/blob/distro/arch-omarchy/agents/.agents/skills/write-a-skill/SKILL.md) | Create new OpenCode skills with concise descriptions, clear triggers, and minimal supporting files. Use when adding or rewriting a local skill, command-adjacent skill, or reusable agent workflow. | [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/write-a-skill) |