Cross-machine config management, one tool at a time. Linux and macOS keep their own copies and are merged only when you decide to merge them. No whole-machine bootstrap, no background syncing - every change lands because you ran a command.
Why it works this way: DESIGN.md.
| Tool | Mode | Linux | macOS |
|---|---|---|---|
| tmux | link | ~/.config/tmux |
~/.config/tmux |
| kitty | link | ~/.config/kitty |
~/.config/kitty |
| ghostty | link | ~/.config/ghostty |
~/.config/ghostty |
| rime | copy | ~/.local/share/fcitx5/rime |
~/Library/Rime |
| fcitx5-guard | link | ~/.local |
- (Linux only) |
| agents | link | ~/.config/agents |
~/.config/agents |
| claude | link | ~/.claude |
~/.claude |
| zsh | link | ~ |
~ |
| brew | link | - (no casks on Linux) | ~/.homebrew |
To add a tool: append a line to manifest, then
mkdir -p tools/<name>/{common,linux,macos}.
~/duotfiles - visible, and the same path on every machine.
Unlike an ordinary git repo, this one's location is not a free choice. Four reasons:
linkmode writes absolute symlinks into this repo. Afterdof pull tmux,~/.config/tmux/tmux.confis a pointer containing the literal text/home/you/duotfiles/tools/tmux/linux/tmux.conf. Move the repo and every pointer goes stale. (Recoverable - re-rundof pull <tool>- but avoidable.)- It must live under
$HOME. Home directories differ across platforms (/Users/youvs/home/you), but a home-relative path is identical on both. A path outside$HOMEsuch as/projects/...cannot even be created on macOS, where the root volume is read-only. - Never inside a cloud-sync folder (iCloud / OneDrive / Dropbox). Sync engines
and
.gitcorrupt each other - a classic way to lose a repository. Git is already your sync mechanism; don't stack a second one under it. - Never anywhere that gets cleaned (
/tmp, Downloads). Underlinkmode this repo holds the only copy of your configs.
Why visible, not ~/.duotfiles. Every other path this repo deploys to is a
conventional location the software itself chose - ~/.config/kitty, ~/.claude.
This repo is not: it is a working directory you edit daily, in a location nobody
else agrees on. Hiding it costs you ls ~, tab completion, and rg / fd, which
skip dotted directories by default. Decided 2026-08-31; the earlier recommendation
was ~/.duotfiles, and this file used to say either was fine - that is what let
the two machines drift apart. Pick one and keep it.
git clone <your-repo> ~/duotfiles
cd ~/duotfiles
# Two one-time settings. This repo is public, and both of these keep it that
# way safely - see AGENTS.md for why each exists.
git config --local user.name "$(git log -1 --format=%an)"
git config --local user.email "$(git log -1 --format=%ae)"
git config core.hooksPath .githooks
./bin/dof list # what exists, what's deployed here
./bin/dof pull kitty # deploy only what you need right nowExisting files at the destination are backed up to <name>.dof-bak-<timestamp>
before anything is overwritten. Nothing is lost.
The identity lines matter because this repo's history was rewritten to carry a
single author address; a machine falling back to a global or hostname-derived
one would put that address into public history. core.hooksPath turns on the
privacy gate below - git does not clone hooks, so every machine enables it once.
dof needs no installation. Pick one:
| Approach | How | Notes |
|---|---|---|
| Do nothing | ~/duotfiles/bin/dof status |
Zero setup, always correct. You rarely need dof day to day - under link mode, changing a config just means git commit |
| Add to PATH (recommended) | echo 'export PATH="$HOME/duotfiles/bin:$PATH"' >> ~/.zshrc |
One line, once per machine. Once your shell config itself is managed here, that line lives in the repo |
| Symlink into an existing PATH dir | ln -s ~/duotfiles/bin/dof ~/.local/bin/dof |
~/.local/bin is usually already on PATH on Linux; on macOS it is not, so you'd still add a line |
dof resolves symlinks on $0 before locating the repo, so the third approach
won't misidentify the repo root. If the script lives away from the repo, override
with DOF_REPO=<path> dof ….
Don't package it for brew / apt. dof is inseparable from this repo - it
locates the repo from its own path. A package manager would install a detached
copy that needs extra configuration to work at all.
dof adopt tmux # copies into tools/tmux/<platform>/
git status # review - drop anything that shouldn't be here
git add -A && git commit -m "tmux(linux): import existing config"
dof pull tmux # switch to link-managed (optional, recommended)link tools (tmux / kitty / ghostty / fcitx5-guard / agents / claude / zsh) - you edited the repo file
directly:
vim ~/.config/tmux/tmux.conf # or change it any other way
git status # the change is already here. No "upload" step.
git add -A && git commit -m "tmux(macos): prefix key -> C-a"
git pushcopy tools (rime) - needs one explicit collection step:
dof diff rime # see what differs first
dof push rime # copy the machine's version back into the repo
git add -A && git commit -m "rime: a few new custom phrases"
git pushgit pull
dof diff tmux # optional: preview what will change
dof pull tmuxdof status # all tools, or: dof status claudeWatch for UNLINKED - it means an application replaced the symlink with a regular
file, so its changes are no longer reaching the repo. See
DESIGN.md.
| Command | What it does |
|---|---|
dof list |
Deployment status of every tool on this machine |
dof status [tool] |
Per-file check, including symlink health |
dof pull <tool> |
Repo → machine. Backs up before overwriting |
dof push <tool> |
Machine → repo. Not needed for link tools; it will tell you |
dof diff <tool> |
Differences between repo and machine |
dof adopt <tool> [subpath] |
Import this machine's existing config into the repo |
dof is bin/dof in this repo - a dependency-free bash script, not a
system command. It handles the one thing git cannot: mapping a repo path to the
place an application actually expects its config.
tools/<name>/
├── common/ shared by both platforms (empty until you merge something)
├── linux/ Linux only
├── macos/ macOS only
├── .dofignore optional: paths dof never touches
└── .dofkeep optional: allow-list of paths `adopt` may import
common/ is laid down first, then <current platform>/ on top - the platform
layer wins on name collisions.
Don't create common/ up front. Keep a full copy per platform, and only move
files into common/ after you have compared them and decided they should be shared.
rime - copy mode. The user dictionary (*.userdb/) never goes into
git; it syncs through Rime's own mechanism. Upstream schemas (rime-ice) are cloned
at deploy time rather than vendored. Each new machine needs installation.yaml
configured once. Full details: notes/rime.md.
claude - ~/.claude mixes configuration with local state, so a .dofkeep
allow-list controls what may be imported. ~/.claude/projects/ holds full transcripts
of every session and must never enter the repo. How the instruction files are organised:
notes/ai-context.md.
agy is not managed by dof. Its one config file holds only per-machine, per-task values (which model, which directories are trusted), so there is nothing long-lived to sync. See notes/agy.md.
kitty / ghostty / tmux - all three have native include mechanisms
(include ${KITTY_OS}.conf, config-file = ?platform-macos.conf, source-file -q).
Use those when you eventually merge platform differences; no template engine needed.
This repository is public, so anything that lands in it is public and permanent. Three layers, from coarse to fine:
1. .gitignore blocks credential-shaped filenames aggressively -
*.key, *.pem, anything matching *token* or *secret*, Claude Code session
transcripts, Rime's installation.yaml. False positives are the intended
trade-off; force a legitimate file through with git add -f.
2. The commit hooks scan what you are about to record - staged blobs and the commit message - for addresses, absolute home paths, institution names, keys, tokens and public IPs, and abort the commit if they find any. Enable once per machine:
git config core.hooksPath .githooks3. bin/audit-privacy --full scans the working tree and every historical
version of every file, about two seconds. Run it before changing the
repository's visibility, and after any history rewrite.
A finding leaves you two options: fix the content, or add an entry to ALLOW in
bin/audit-privacy with a reason. Do not reach for
git commit --no-verify.
What this does not catch: a leak shaped like an ordinary word. A directory name that happens to be an unpublished project name passes every check. New files still deserve a human read - see AGENTS.md.
| Document | Answers |
|---|---|
| DESIGN.md | Why it is built this way: principles, structure, trade-offs |
| AGENTS.md | Rules for AI agents working in this repo (CLAUDE.md is a symlink to it) |
| notes/ | One file per tool: why these parts must stay platform-specific |
Original work here is MIT - see LICENSE.
tools/rime/ also redistributes third-party configuration, most of it from
iDvel/rime-ice under GPL-3.0-only.
Those files keep their upstream license; MIT does not apply to them.
NOTICE has the file-by-file breakdown.