laptop

Personal macOS configuration management system with automated dotfiles synchronization, security scanning, and one-command setup/rollback capabilities.

Core Components

This repository manages configurations for the following applications:

Category	Application	Config Location
Shell	Zsh + Oh-My-Zsh	`~/.zshrc`, `~/.zsh/`
Terminal	Ghostty, iTerm2	`~/.config/ghostty/config`, `iterm2/`
Editor	Neovim, Vim	via Homebrew
Version Control	Git, Tig	`~/.gitconfig`, `~/.tigrc`
Multiplexer	tmux	`~/.tmux.conf`
Fuzzy Finder	fzf	`~/.fzf.zsh`
Packages	Homebrew	`Brewfile`
Runtimes	mise	`~/.config/mise/config.toml`
Launcher	Raycast	`raycast/*.rayconfig`
AI Assistant	Claude Code	`~/.claude/` (settings, hooks, agents, skills)

Brewfile includes:

100+ CLI tools (aws, gh, ripgrep, bat, jq, etc.)
40+ GUI applications (Cursor, Ghostty, Arc, Raycast, etc.)
80+ VSCode/Cursor extensions

Architecture

Symlink Strategy

Configuration files reside in this repository and symlink to their standard locations:

~/.zshrc          → laptop/zsh/.zshrc
~/.gitconfig      → laptop/git/.gitconfig
~/.config/ghostty → laptop/ghostty/config

Why symlinks?

Git tracks actual content, not just symlink paths
No specialized tooling required (stow, chezmoi, etc.)
Easy to understand and debug
Industry-standard approach

Directory Structure

laptop/
├── install.sh              # Main installer
├── rollback.sh             # Restore from backup
├── Brewfile                # Homebrew packages manifest
│
├── zsh/                    # Shell configuration
│   ├── .zshrc              # Main config (loads below in order)
│   ├── .aliases            # Shell aliases
│   ├── functions/          # Custom zsh functions (5)
│   └── configs/            # Modular configs
│       ├── *.zsh           # Main configs (color, editor, history, etc.)
│       └── post/           # Loaded last (PATH, completion, mise)
│
├── git/                    # Git configuration
│   ├── .gitconfig          # Main git config
│   ├── .gitignore          # Global gitignore
│   ├── .gitmessage         # Commit message template
│   └── .git_template       # Git hooks template
│
├── ghostty/                # Ghostty terminal config
├── iterm2/                 # iTerm2 settings plist
├── tmux/                   # tmux configuration
├── tig/                    # Tig (git TUI) config
├── fzf/                    # Fuzzy finder config
├── mise/                   # mise runtime manager config
├── bin/                    # Executable scripts (tat)
├── raycast/                # Raycast settings export
├── claude/                 # Claude Code configuration → ~/.claude/
│   ├── CLAUDE.md           # User global instructions
│   ├── settings.json       # Hooks, plugins, permissions
│   ├── statusline.sh       # Custom status line script
│   ├── hooks/              # Lifecycle hooks (4)
│   ├── agents/             # Subagents (18)
│   └── skills/             # Custom skills (10)
│
├── .claude/                # Local skills (project-specific, 15)
│   └── skills/             # Not symlinked to ~/.claude/
│
├── scripts/
│   └── auto-sync.sh        # Hourly auto-sync script
│
├── .github/
│   └── workflows/main.yml  # CI/CD (gitleaks + shellcheck)
│
├── .pre-commit-config.yaml # Pre-commit hooks
├── .gitleaks.toml          # Secret scanning rules
└── .gitignore              # Security-focused ignore patterns

Security

Three-Layer Protection

Pre-commit Hooks - Runs before every commit:
- gitleaks - Scans for secrets and credentials
- detect-private-key - Catches SSH/PGP keys
- trailing-whitespace, end-of-file-fixer - Code hygiene
Comprehensive .gitignore - Blocks 30+ sensitive patterns:
- Environment files (.env, .secrets.env)
- Cloud credentials (AWS, GCP, Azure)
- SSH/GPG keys (id_rsa*, *.pem)
- Terraform state (*.tfstate, *.tfvars)

Secrets Template - API keys belong in ~/.secrets.env:

# ~/.secrets.env (gitignored, created by install.sh)
export OPENAI_API_KEY=""
export ANTHROPIC_API_KEY=""
export GITHUB_TOKEN=""

Security Scanning Commands

# Manual gitleaks scan
gitleaks detect --source=. --no-git

# Run all pre-commit hooks
pre-commit run --all-files

Automation

Auto-Sync (launchd)

An hourly launchd agent runs scripts/auto-sync.sh:

Regenerates Brewfile from current installations
Runs gitleaks scan (aborts if secrets detected)
Executes pre-commit hooks
Commits and pushes changes automatically

Log files:

~/.dotfiles_autosync.log - Standard output
~/.dotfiles_autosync.error.log - Errors

Manual sync:

./scripts/auto-sync.sh

Installation

New Machine Setup

# Clone repository
git clone https://github.com/snkrheadz/laptop.git ~/ghq/github.com/snkrheadz/laptop

# Run installer
cd ~/ghq/github.com/snkrheadz/laptop
./install.sh

What install.sh does:

Checks macOS and installs Xcode CLI tools
Installs Homebrew (if not present)
Creates timestamped backup of existing configs
Creates symlinks to repository configs
Installs all Homebrew packages from Brewfile
Sets up mise and installs runtimes (Go, Node.js, Python, Ruby)
Sets up gitleaks + pre-commit hooks
Configures launchd auto-sync agent
Creates ~/.secrets.env template

Rollback

# List available backups
./rollback.sh

# Restore specific backup
./rollback.sh 20231223_120000

What rollback.sh does:

Disables auto-sync launchd agent
Removes all symlinks
Restores files from backup

Update Packages

# Dump current installations to Brewfile
brew bundle dump --force --file=Brewfile

# Install packages from Brewfile
brew bundle --file=Brewfile

Runtime Management (mise)

mise manages programming language runtimes (Go, Node.js, Python, Ruby).

Installed Runtimes

Runtime	Version
Go	1.24.3
Node.js	25.2.1, 22.16.0
Python	3.13.x
Ruby	3.4.8

Commands

# List installed runtimes
mise list

# Install all runtimes from config
mise install

# Install specific runtime
mise use go@1.23.1

# Update to latest versions
mise upgrade

Configuration

Edit mise/config.toml to change versions:

[tools]
go = "1.24.3"
node = "25.2.1"
python = "3.13"
ruby = "3.4.8"

Customization

Local Overrides

Create ~/.zshrc_local for machine-specific settings (automatically sourced, not tracked):

# ~/.zshrc_local
export WORK_PROJECT_PATH="/path/to/work"
alias deploy="./scripts/deploy-work.sh"

Adding New Dotfiles

Add config file to appropriate directory (e.g., tool/.toolrc)

Update install.sh to create symlink:

safe_ln "$DOTFILES_DIR/tool/.toolrc" "$HOME/.toolrc"

Update rollback.sh symlinks array
Commit and push

Development Notes

zsh Loading Order

1. zsh/functions/*        # Custom functions
2. zsh/configs/pre/*      # Pre-configs (code exists in .zshrc but directory unused)
3. zsh/configs/*.zsh      # Main configs
4. zsh/configs/post/*     # Post-configs (PATH, completion, mise)
5. ~/.aliases             # Shell aliases
6. oh-my-zsh              # Plugins: git, zsh-autosuggestions

Avoiding Conflicts

Don't create functions with names that conflict with oh-my-zsh aliases
- Example: g is already defined by the git plugin
Run alias after installation to check for conflicts

Symlink Safety

install.sh uses safe_ln() which removes existing symlinks before creating new ones. This prevents circular references when running install.sh multiple times.

Claude Code Configuration

This repository manages Claude Code settings via symlinks to ~/.claude/:

claude/
├── CLAUDE.md           # User global instructions
├── settings.json       # Hooks, plugins, permissions
├── statusline.sh       # Custom status line script
├── hooks/              # Lifecycle hooks (4)
│   ├── validate-shell.sh   # PostToolUse: shellcheck validation
│   ├── save-to-obsidian.js # Stop: Obsidian integration (secret redaction)
│   ├── session-context.sh  # SessionStart: project context injection
│   └── pre-tool-guard.sh   # PreToolUse: sensitive file access blocking
├── agents/             # Subagents (18)
│   ├── verify-shell.md, verify-app.md, build-validator.md
│   ├── code-architect.md, code-simplifier.md, oncall-guide.md
│   ├── aws-best-practices-advisor.md, gcp-best-practices-advisor.md
│   ├── arxiv-ai-researcher.md, gemini-api-researcher.md, huggingface-spaces-researcher.md
│   ├── strategic-research-analyst.md, nano-banana-pro-prompt-generator.md
│   ├── state-machine-diagram.md, migration-assistant.md
│   ├── diagnose-dotfiles.md, verify-subagent-result.md
│   ├── pdm-reviewer.md
└── skills/             # Custom skills (10)
    ├── claude-code-guide/  # Claude Code extension guide
    ├── db-query/           # Database query helper
    ├── first-principles/   # First principles analysis
    ├── merge-pr/           # PR merge automation
    ├── project-setup/      # Project setup wizard
    ├── quick-commit/       # Fast commit workflow
    ├── review-changes/     # Code review helper
    ├── techdebt/           # Tech debt analysis
    ├── trace-dataflow/     # Data flow tracing
    └── test-and-fix/       # Test and fix workflow

Managed Components

Component	Description
`CLAUDE.md`	User global instructions (workflow, best practices, prohibitions)
`settings.json`	Hooks, plugins, permissions, Obsidian integration
`statusline.sh`	Custom status line showing model, cost, context
`hooks/`	4 lifecycle hooks (PostToolUse, Stop, SessionStart, PreToolUse)
`agents/`	18 specialized subagents for various tasks
`skills/`	10 custom skills for common workflows

Status Line

Displays in Claude Code CLI:

[Opus] 📁 laptop | 🌿 main | 💰 $5.20 (Today) | 📊 185k

Hooks

Hook	Lifecycle Event	Description
`validate-shell.sh`	PostToolUse	Runs shellcheck on `.sh` files after Write/Edit
`save-to-obsidian.js`	Stop	Saves conversation context to Obsidian (secret redaction)
`session-context.sh`	SessionStart	Injects project context at session start
`pre-tool-guard.sh`	PreToolUse	Blocks access to sensitive files

Key Subagents

Agent	Purpose
`verify-shell`	Shell script verification
`verify-app`	Application verification
`build-validator`	Build validation
`code-architect`	Architecture design
`aws-best-practices-advisor`	AWS guidance
`gcp-best-practices-advisor`	GCP guidance
`diagnose-dotfiles`	Dotfiles troubleshooting

Available Skills

/claude-code-guide - Claude Code extension documentation
/quick-commit - Fast commit workflow
/merge-pr - PR merge with worktree cleanup
/review-changes - Code review helper
/test-and-fix - Run tests and fix failures

Local Skills (Project-specific)

The .claude/skills/ directory contains 15 project-specific skills that are only available in this repository (not symlinked to ~/.claude/). These skills are tailored for managing this dotfiles repository.

Skill	Description
`brew-manage`	Homebrew package management (add/remove/search, Brewfile update)
`claude-config`	Claude Code configuration (settings.json, hooks, agents, skills)
`dotfiles-rollback`	Backup confirmation and rollback to previous state
`dotfiles-sync`	Manual dotfiles sync (Brewfile update, commit, push)
`git-config`	Git config files (.gitconfig, .gitmessage, .gitignore)
`health-check`	Dotfiles health check (symlinks, configs, dependencies)
`hf-spaces`	HuggingFace Spaces search (research demos, model prototypes)
`launchd-manage`	Auto-sync launchd agent management (start/stop/logs)
`mise-runtime`	Runtime management with mise (Go, Node.js, Python, Ruby)
`new-machine-setup`	New machine setup guide (macOS → dotfiles)
`pdm-review`	Plan/design review from business perspective (PdM review)
`security-check`	Security scanning (gitleaks, pre-commit, secrets)
`symlink-manage`	Symlink status check and repair (broken link detection)
`tmux-config`	tmux configuration (.tmux.conf, keybindings)
`zsh-config`	zsh configuration (functions, configs, aliases)

Usage: These skills are invoked using slash commands (e.g., /brew-manage, /health-check) when working in this repository with Claude Code.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 274 Commits
.claude/skills		.claude/skills
.github/workflows		.github/workflows
bin		bin
claude		claude
fzf		fzf
ghostty		ghostty
git		git
iterm2		iterm2
mise		mise
raycast		raycast
scripts		scripts
tig		tig
tmux		tmux
zsh		zsh
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
Brewfile		Brewfile
CLAUDE.md		CLAUDE.md
README.md		README.md
install.sh		install.sh
rollback.sh		rollback.sh

snkrheadz/laptop

Folders and files

Latest commit

History

Repository files navigation

laptop

Core Components

Architecture

Symlink Strategy

Directory Structure

Security

Three-Layer Protection

Security Scanning Commands

Automation

Auto-Sync (launchd)

Installation

New Machine Setup

Rollback

Update Packages

Runtime Management (mise)

Installed Runtimes

Commands

Configuration

Customization

Local Overrides

Adding New Dotfiles

Development Notes

zsh Loading Order

Avoiding Conflicts

Symlink Safety

Claude Code Configuration

Managed Components

Status Line

Hooks

Key Subagents

Available Skills

Local Skills (Project-specific)

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages