🧰 Dotfiles

August 19, 2026 · View on GitHub

My public Omarchy dotfiles, managed with GNU Stow and the dot command.

Full documentation: https://dotfiles.timmo.dev

Caution

These are my personal dotfiles, tightly tuned for Omarchy (an Arch Linux based distro) and my specific machines. They are not meant to be installed as-is by anyone else: they are unlikely to work on plain Arch without replicating my setup, and they lean on a deeply integrated private overlay (dotfiles-private) that is not public, so the public repo alone is an incomplete picture. Use them as a reference to borrow from, or pull individual pieces into your own dotfiles. The shared OpenCode config is the exception: it is generated from this repo and published as opencode-config, written to be portable and reusable on its own.

Much of this project, including the documentation and a lot of the code, is generated or heavily assisted by LLMs and coding agents.

At a glance

Stow-based dotfiles rooted at ~/.config/dotfiles, applied with the dot command
A single compiled binary at scripts/.local/bin/dot (Bun + Effect v4 + OpenTUI) with a TUI dashboard and a full CLI
Git/GitHub tooling: diff, log, status, and a notification inbox across managed repos, surfaced in the Omarchy Quickshell status bar
Stowed UWSM, Hyprland, and Ghostty customisations for Omarchy Quattro
Optional private overlay from ~/.config/dotfiles-private
Shared OpenCode agents, commands, and plugins published to timmo001/opencode-config, with portable skills in timmo001/skills

Quick start

# Fresh Omarchy machine bootstrap prerequisites
yay -S --needed git mise-bin

# Clone public dotfiles. For private dotfiles, authenticate gh before dot init;
# init clones dotfiles-private automatically when gh auth works.
git clone git@github.com:timmo001/dotfiles.git ~/.config/dotfiles
gh auth status || gh auth login

# Build the checked-out dot binary before it is on PATH.
cd ~/.config/dotfiles
mise trust
mise install
mise run dot:build

# One-time first-use setup.
~/.config/dotfiles/scripts/.local/bin/dot init --noninteractive

# Ongoing workflow after restarting the shell
dot doctor
dot update
dot git-diff

See the install guide and new machine checklist for the full walkthrough.

Documentation

Everything is documented at https://dotfiles.timmo.dev:

Getting Started — install and new-machine checklist
The dot Command — TUI + CLI, with the full command reference, stow workflow, notes & handoffs, and system utilities
Git & GitHub — diff, log, status, workflows, notifications
Omarchy & Hyprland — managed repos and host overrides
OpenCode & Agents — agents, commands, skills, plugins, and the generated reference
Configuration & Reference — environment options, private git config, and packages
Bar Integrations — the --bar-json status-bar contract shared by dot and external tools
Agents / LLMs — context bundles for AI-assisted work

Repository layout

dot/ — TypeScript source for the dot binary (excluded from stow)
docs/ — the documentation site at https://dotfiles.timmo.dev (Astro + Starlight; excluded from stow)
scripts/.local/bin/dot — compiled binary (stowed to ~/.local/bin/dot)
.stowrc — stow target and ignore rules
zsh/, neovim/, starship/, editorconfig/ — shell, editor, and prompt config
agents/ — OpenCode config (.config/opencode/) and the pinned skills checkout (.agents/skills/), published through opencode-config
hypr/ — Hyprland config (stowed with --no-folding, per-host overrides)
uwsm/ — user environment overrides layered over Quattro's package defaults
ghostty/ — Ghostty config, host overrides, launcher, and desktop entry

The documentation is the single source of truth; this README links to it rather than duplicating content. The dot command reference and the OpenCode reference on the docs site are generated from dot/src/cli/spec.ts and the OpenCode assets respectively.