My dotfiles managed with dotstate

Layout

dotstate links each path listed in .dotstate-profiles.toml from the repository into $HOME:

• common/: configs shared by every machine.
• macos/: macOS-only configs (AeroSpace, Ghostty, Kitty, Zed), linked by the macos profile.
• linux profile: common configs only, used on Linux and in Codespaces.

Edit configs at their usual paths; the links write through to this repository. Common tasks:

dotstate add ~/.config/foo --common --yes   # track a new config for every machine
dotstate profile switch macos               # pick this machine's profile
dotstate doctor                             # check links and the manifest
dotstate sync -m "Update foo"               # commit, pull --rebase and push

Agent instructions

• AGENTS.md contains instructions for working in this dotfiles repository.
• common/AGENTS.md contains cross-project rules. dotstate links it to $HOME/AGENTS.md.
• Repository-local instruction files can refine or override the user-level defaults. Tools with different discovery behavior may require their own supported instruction entry point.
• Medium-or-larger features use Worktrunk worktrees under $HOME/worktrees/<repository>/<sanitized-branch>. The user chooses whether formal SDD uses OpenSpec or no formal framework.

Agent skills

• common/.agents/skills/ holds skills shared by every coding agent. dotstate links each one into $HOME/.agents/skills/, the same directory the skills CLI installs into, so that directory stays real instead of becoming a link into the repo.
• Harness directories point at the shared copy: common/.config/opencode/skills/ carries a tracked symlink, and ~/.claude/skills/, ~/.codex/skills/ and ~/.copilot/skills/ get one via ln -s ../../.agents/skills/<name> ~/<harness>/skills/<name>.
• paranoid-review is an adversarial, evidence-first code review that reports only verified defects and lists unproven concerns separately.

Install

git clone git@github.com:mainframev/dotfiles.git ~/dotfiles
cd ~/dotfiles
./install.sh            # everything
./install.sh --no-gui   # CLI tools only, no casks

install.sh installs Homebrew and the Brewfile, oh-my-zsh and its custom plugins, and dotstate (from its Homebrew tap on macOS, the pinned release on Linux). On first run it writes ~/.config/dotstate/config.toml for this checkout in Local mode with the macos or linux profile, then links everything with dotstate. Files in the way are moved to ~/.dotstate-backups/<timestamp>/ with their paths kept. Re-running is safe and links paths added to the manifest since. Run ./test.sh to validate configs and installer behavior.

Coming from the old Stow layout, install.sh moves untracked state left at the old paths (for example .config/zsh/secrets.zsh, herdr sessions, tmux plugins) into common/ or macos/, and drops dangling folded Stow links such as ~/.pi/agent. To stop managing a path, run dotstate remove <path> --yes before deleting it from the repository, or dotstate doctor keeps reporting its dangling link.

What I currently use:

• Aerospace - Tiling window manager for macOS
• Bat - Cat clone with syntax highlighting
• btop - Resource monitor
• ccstatusline - Claude Code status line
• Git with Delta - Version control with Delta configured as the pager
• GitHub CLI - GitHub command line tool
• gh-dash - GitHub CLI dashboard
• Ghostty - Terminal emulator
• herdr - Terminal agent multiplexer
• Kitty - Fast, feature-rich terminal emulator
• lazygit - Terminal UI for Git
• Neovim - Hyperextensible Vim-based text editor
• OpenCode - AI coding assistant
• pi - Coding agent; only ~/.pi/agent/settings.json is managed, and pi installs missing packages from it on startup
• Starship - Cross-shell prompt
• Taskwarrior - Command line task manager
• Tmux - Terminal multiplexer
• Worktrunk - Git worktree manager (wt)
• Yazi - Blazing fast terminal file manager
• Zed - Code editor
• Zsh with Oh-my-zsh - Shell with framework