tuck
The Modern Dotfiles Manager
https://tuck.sh
tuck
The modern dotfiles manager
Simple, fast, and built in TypeScript. Track any config file — in your home directory or inside any git repo — sync across machines, and never lose your configs again. Agent-native, too: structured JSON output and a write-confined sandbox.
npm install -g @prnv/tuckTrack any dotfile instantly
Smart category detection organizes your configs automatically. Let tuck init and tuck sync discover files automatically, or use tuck add for manual control. Files are copied and organized by category.
Learn about tracking →Know your dotfiles status
See your entire configuration state at a glance. Branch info, sync status, and all tracked files organized by category - everything you need to stay in control.
View all commands →Sync with a single command
Automatically detects changes AND new dotfiles on your system. Select what to track interactively, commit, and push - all in one command. Pulls from remote first if behind. No manual git workflows needed.
See how sync works →Apply dotfiles from anywhere
Bootstrap a new machine in seconds. Point tuck at a GitHub, GitLab, or custom user, any git URL, a local folder, or a tarball. tuck creates Time Machine backup snapshots of your existing configs and applies with smart merging that preserves your local customizations.
Learn about apply →Restore when you need it
Symlink or copy, your choice. Automatic backups before every operation mean you can always restore. SSH and GPG permissions are handled correctly.
Explore restore options →Verify nothing drifted
tuck verify compares your live files, the repo, and the manifest so you always know what's out of sync. Use --exit-code as a CI gate, --json for automation, and --fix to safely re-copy whatever drifted.
See all commands →Track configs inside your repos
Not just your home directory. Track .vscode/settings.json, CLAUDE.md, or .cursorrules that live inside a project, then sync them across machines with 'tuck repo link'. Track any config file, anywhere.
Learn about repo tracking →Quick Start
Up and running in under a minute
Install tuck
npm install -g @prnv/tuckor use yarn, pnpm, or bun
Initialize (does everything!)
tuck initScans your dotfiles, select what to track, syncs to your remote (GitHub, GitLab, or custom — or stay fully local)
Keep in sync (ongoing)
tuck syncRun anytime - detects changes, finds new files, pushes updates
Core Commands
What 99% of users need. Initialize, sync, and check status - the essential workflow for managing your dotfiles.
tuck initSet up tuck, scan for dotfiles, select what to track, and sync - all in one. Works with GitHub, GitLab, custom, or local-only providers. Creates ~/.tuck directory with Git tracking.
tuck syncDetect changes, find new files, and push to remote. Pulls first if behind, scans for new dotfiles, commits and pushes.
tuck statusSee what's tracked and what's changed. Shows branch info, sync status, and all tracked files by category.
Backup Commands
Fine-grained control for creating and managing your dotfile backups. Add files, discover new ones, and sync manually.
tuck add <files>Manually track specific files. Copies files to ~/.tuck organized by category. Use --repo to track config files that live inside any git repo, not just $HOME.
tuck remove <files>Stop tracking dotfiles. Optionally delete from repository or keep original files intact.
tuck listList all tracked files. Filter by category or output as JSON for scripting.
Restore Commands
Apply dotfiles from others, restore your own, or undo changes. Everything you need to use your backups across machines.
tuck apply <source>Apply dotfiles from anywhere: a GitHub, GitLab, or custom user or owner/repo, any git URL, a local directory, or a tarball. Smart merging preserves your local customizations.
tuck restoreRestore dotfiles from ~/.tuck to your system. Useful when setting up on a new machine.
tuck undoRestore files from Time Machine backup snapshots. Created automatically when using tuck apply.
Security & Config
Manage secrets safely and customize tuck to your workflow. Keep sensitive data out of git while staying productive.
tuck secretsManage local secrets for placeholder replacement. Scan files and git history for exposed secrets.
tuck configCustomize tuck behavior - default branch, file strategy, hooks, and more.
tuck diffShow differences between system files and repository. Useful before syncing.
Agent-Native
Drive tuck from AI agents and CI — structured JSON I/O, drift verification, a write-confined --root sandbox, and an MCP server. Every command supports --json, --yes, --plan, and --dry-run for safe, scriptable automation.
tuck verifyDetect drift between your live files, the repo, and the manifest. Gate CI on it or safely re-copy what changed.
tuck repoManage per-machine bindings for config files tracked inside your git repos, synced across machines.
tuck mcp serveExpose tuck as tools to AI agents over MCP. Pair with --root to confine every write to a sandbox.
How it works
tuck stores your dotfiles in ~/.tuck, organized by category. When you run tuck init, it scans your system and lets you choose which files to track. Run tuck sync anytime to detect changes and sync to your remote.
Run tuck sync to detect changes and push to remote. On a new machine: tuck init --from <repo-url> or tuck apply username
How tuck compares
Feature comparison with other dotfile managers
| Feature | tuck | chezmoi | dotbot | rcm | vcsh | yadm | bare git | GNU Stow |
|---|---|---|---|---|---|---|---|---|
| Automatic dotfile discovery | ||||||||
| Secret scanning | ||||||||
| Git history secret scanning | ||||||||
| Time Machine backups | ||||||||
| Smart merge with preserve markers | ||||||||
| Auto-categorization | ||||||||
| Remote repo auto-setup (GitHub/GitLab/custom) | ||||||||
| JSON / agent automation | ||||||||
| Drift detection (verify) | ||||||||
| Write sandbox (--root) | ||||||||
| MCP server | ||||||||
| Track files in any repo | ||||||||
| Interactive CLI prompts | ||||||||
| Distribution | npm, brew, binary | Single binary | Python package | Multiple files | Single script or package | Single script | - | Perl script |
| Install method | Many | Many | git submodule | Many | Many | Many | Manual | Many |
| Non-root install on bare system | ||||||||
| Windows support | ||||||||
| Bootstrap requirements | Node.js 18+, Git | None | Python, git | Bash | sh, git | git | git | Perl |
| Source repos | Single | Single | Single | Multiple | Multiple | Single | Single | Single |
| dotfiles are... | Files or Symlinks | Files | Symlinks | Symlinks | Files | Files | Files | Symlinks |
| Config file | Optional | Required | Optional | None | Optional | Optional | Optional | None |
| Private files | ||||||||
| Show differences without applying | ||||||||
| Whole file encryption | ||||||||
| Password manager integration | ||||||||
| Machine-to-machine file differences | Templates | Alternative files | Alternative files | Branches | Alt files, templates | |||
| Custom variables in templates | ||||||||
| Executable files | ||||||||
| File creation with initial contents | ||||||||
| Externals | ||||||||
| Manage partial files | ||||||||
| File removal | ||||||||
| Directory creation | ||||||||
| Run scripts (hooks) | ||||||||
| Run once scripts | ||||||||
| Machine-to-machine symlink differences | ||||||||
| Shell completion | ||||||||
| Archive import | ||||||||
| Archive export | ||||||||
| Implementation language | TypeScript | Go | Python | Bash | POSIX Shell | Bash | C | Perl |
Built on open source
Built with the open source community
tuck stays small by leaning on tools developers already trust: Git for history, TypeScript for clarity, and standard package managers for distribution. The point is not to invent a new workflow, just to make dotfiles easier to keep.
Install tuck
Choose your preferred method
npm install -g @prnv/tuckbrew install Pranav-Karra-3301/tuck/tuckcurl -fsSL https://tuck.sh/install.sh | bash